Skip to content

01 Product Overview

SSH Teams is a certificate-based access platform for SSH environments. Instead of distributing long-lived public keys to many servers, teams define central access rules and issue short-lived SSH certificates to approved user devices.

This model gives operations and security teams a practical way to scale SSH access while reducing key sprawl, manual cleanup work, and policy drift across servers.

Use this chapter to understand why the platform exists and how the core trust model works before you start deployment.

1.1 What SSH Teams Solves

Most organizations start SSH access management with static keys in authorized_keys. That works at small scale, then becomes hard to control as teams, environments, and compliance requirements grow.

SSH Teams addresses common pain points:

  • Access does not expire by default when using static keys.
  • Offboarding can require touching many hosts.
  • Policy differences appear over time between servers.
  • It is difficult to answer who can access what, and why.

SSH Teams replaces this with a central policy-and-certificate model:

  • Admins define certificate issuance policies centrally.
  • Users register devices through a guided flow.
  • Certificates are short-lived and issued on demand.
  • Servers trust a shared authority instead of individual user keys.

The result is tighter access control with less day-to-day operational friction.

1.2 Core Components and Runtime Model

SSH Teams has three core surfaces:

graph LR
    U[Admins and Users]
    UI[Web UI]
    CLI[CLI and Join Scripts]

    subgraph CONTROL[SSH Teams Server Control Plane]
        AUTH[Auth and Sessions]
        API[REST API]
        POLICY[Policy Engine]
        SIGN[Certificate Signing]
    end

    STORE[(Persistence Nitrate or MongoDB)]
    CA[Team CA Key Material]
    CERT[Short-Lived SSH Certificates]
    TARGET[Joined SSH Servers]
    TRUST[TrustedUserCAKeys]

    U --> UI
    U --> CLI
    UI --> AUTH
    UI --> API
    CLI --> API

    API --> POLICY
    POLICY --> SIGN
    API --> STORE
    SIGN --> CA
    SIGN --> CERT
    CERT --> TARGET
    TARGET --> TRUST
  • Server application: Web UI and API for administration, policy configuration, user/device lifecycle, and certificate issuance.
  • Join tooling/scripts: Scripts and CLI workflows used to attach servers and devices to a team trust domain.
  • Trust integration on target servers: Server-side trust of issued SSH certificates so access decisions follow central policy.

Typical runtime characteristics in Docker deployments:

  • HTTP and HTTPS listeners are exposed by the containerized app.
  • Local persistence can be used for quick starts via mounted host folders.
  • External database configuration is supported for production-style layouts.

In short: the control plane is centralized, while SSH access is still enforced where it matters, on the target servers.

1.3 Roles and Permissions Model

Current implementation (directly from code) defines these application roles:

  • ADMIN
  • USER
  • MANAGE_SERVERS
  • MANAGE_POLICIES
  • MANAGE_USERS

Current enforcement highlights:

  • Server list access checks for MANAGE_SERVERS (ADMIN also passes via hasPermission logic).
  • User administration checks for MANAGE_USERS (ADMIN also passes).
  • Authentication currently establishes Spring authority ROLE_USER for signed-in users; finer-grained access is enforced in controller logic against stored UserRole values.

Notes on maturity:

  • Role definitions are present and active.
  • Administration surfaces now enforce explicit role checks (MANAGE_SERVERS, MANAGE_USERS, MANAGE_POLICIES, and ADMIN where appropriate).
  • Non-administration routes may still rely on authenticated access and team scoping where fine-grained role partitioning is not part of the current design.

1.4 High-Level Usage Flow

The lifecycle below describes a typical onboarding and access path:

  1. Deploy SSH Teams and complete first-time setup.
  2. Create the initial team and administrative account.
  3. Join target servers to the team trust model.
  4. Define certificate issuance policies (who, what, where, and for how long).
  5. Add users and have them register devices.
  6. Issue short-lived certificates according to policy.
  7. Audit, rotate, and refine policies as systems and teams evolve.

Operationally, this gives teams a repeatable and auditable process that is easier to maintain than static key distribution.

1.5 Who Should Read This and Next Step

This chapter is most useful for:

  • Platform engineers deciding whether to replace static SSH key workflows.
  • Security teams validating short-lived certificate controls.
  • Operations teams planning rollout sequence across environments.

If you are ready to deploy, continue to 02-install-with-docker.md for environment-specific install requirements.

If you are new to SSH Teams terms, use the shared glossary: 14-glossary.md.

Next step: continue to 02 Install with Docker for deployment options, volumes, ports, and environment variable guidance.