Skip to content

Security and Compliance

SSH Teams is strongest when you treat it as an operational system, not just a way to log in. This chapter gives you a secure-by-default starting point, then explains the deeper controls for audits and incident response.

Secure in 5 Steps

Follow this sequence in every new environment:

  1. Use least-privilege roles (MANAGE_USERS, MANAGE_POLICIES, MANAGE_SERVERS) and keep the number of ADMIN users small.
  2. Confirm TLS is valid and the hostname is trusted for browser and CLI access.
  3. Require device approval for CLI access and test revoking a device.
  4. Test one allowed and one denied certificate request against a policy.
  5. Enable and review security logs for auth, device, token, signing, and admin events.

Expected outcome:

  • Web and CLI access is authenticated, scoped, and auditable.
  • Certificates are issued only when policy allows.
  • Token replay is resisted.

If any control does not behave as expected, see Device Flow Failures, Policy Mismatch and Access Denials, and Certificate Issuance Failures.

Before a Compliance Review

Requirement Lab Staging Production
TLS enabled with environment hostname Required Required Required
Role model defined and reviewed Recommended Required Required
Device registration and revoke test completed Recommended Required Required
Log retention and access policy documented Optional Recommended Required
Backup encryption and restore ownership defined Optional Recommended Required

Before an audit, make sure you can produce:

  • Recent admin change records.
  • Device approval and revocation evidence.
  • Sample allowed and denied issuance evidence.

Authentication and Sessions

SSH Teams uses browser sessions for the web UI and tokens for CLI/API access.

Why this matters:

  • Browser sessions protect day-to-day operator workflows.
  • Token-based auth protects automation and endpoint tools.

Web session behavior:

  • Login uses team user credentials and creates a server-side session.
  • Session cookies are HTTP-only and tied to the application host.
  • Unauthenticated requests to protected pages are redirected to /login.
  • Authorization is based on roles and permissions (ADMIN, MANAGE_USERS, MANAGE_POLICIES, MANAGE_SERVERS).

Operator guidance:

  • Restrict ADMIN assignments and prefer granular management roles.
  • Enforce strong password policy and centralized credential lifecycle.
  • End stale sessions through logout and upstream session timeout policy.

API Access Controls

API access is split by scope and endpoint.

  • Device authorization endpoints issue scoped tokens for join and signing.
  • The join API needs a valid Bearer token with join scope.
  • The signing API needs Authorization: DPoP <token> plus a valid DPoP proof.
  • Team and policy checks happen before any certificate is issued.

License and edition notes:

  • Edition can affect available admin features.
  • Security-relevant controls, including authentication, authorization, token validation, and policy enforcement, remain mandatory regardless of edition.

License Is Not a Security Boundary

Treat license state as a feature gate, not an authorization boundary.

Compliance Baseline

Document which API surfaces are enabled per environment and edition in your internal control baseline.

CLI Security: OAuth Tokens and DPoP

This section explains why SSH Teams CLI usage resists token replay.

graph TD
    A[User approves device in browser] --> B[CLI receives scoped token]
    B --> C[CLI signs DPoP proof with device key]
    C --> D[Server validates token plus proof]
    D --> E[Policy evaluation]
    E --> F[Team CA signs short-lived certificate]
    F --> G[Joined server trusts CA keys]

    X[Stolen token without key] -. replay blocked .-> D

OAuth in CLI Flows

CLI commands (init, sign, issue, agent, server join) use an OAuth device-style flow:

  1. The CLI requests authorization and receives a device code/user code.
  2. A human approves the request in the browser.
  3. The CLI polls for the token.
  4. The server issues access and refresh tokens with limited scope.

Why DPoP Matters

Why DPoP Matters

A plain bearer token can be replayed if stolen. DPoP (Demonstration of Proof-of-Possession) adds a cryptographic proof so the token can only be used by the device that holds the private key.

DPoP properties:

  • Proof-of-possession: each request includes a signed DPoP proof JWT.
  • Method and URL binding: the proof includes the HTTP method and target URI, reducing cross-endpoint replay.
  • Freshness controls: the proof includes issuance time and nonce/jti semantics to limit replay windows.
  • Key continuity: the server validates proofs against the key material tied to the registered device or token.

How Devices Tie Into Certificate Issuance

The CA private key never leaves the server. A certificate is only issued after all of the following are true:

  • The device was explicitly approved through browser authorization.
  • The OAuth token is valid for the requested operation scope.
  • The DPoP proof validates against the bound device key.
  • Policy checks pass for user, principal, server fingerprint/tag, and time constraints.

This creates a trust chain:

Approved user identity → Approved device identity → Authorized signing request → Certificate signed by team CA.

Security impact:

  • A stolen access token alone is not enough to issue certificates.
  • An attacker would also need the device private key and must satisfy policy.
  • Revoking a device immediately stops future token use and signing.

Secrets and Key Material

SSH Teams handles several sensitive material classes:

  • Team CA private keys (highest sensitivity).
  • Access and refresh tokens.
  • Notification provider secrets (SMTP passwords, API keys, SMS credentials).
  • User password hashes.

Required practices:

  • Never expose CA private key material in logs or API responses.
  • Store secrets encrypted at rest where your deployment supports it.
  • Rotate notification provider credentials and disable unused providers.
  • Restrict access to persistence volumes, backups, and runtime config files.
  • Use TLS for all operator and API traffic.

Backup Sensitivity

Encrypt backups that contain token, session, or security metadata. Restrict restore privileges and audit restore events. Treat backup copies as production-equivalent sensitive data.

Audit and Logging Recommendations

Use verbose security logging, but redact secrets carefully.

Log categories to keep:

  • Authentication events, both success and failure.
  • Device authorization lifecycle: requested, approved, denied, expired.
  • Token and DPoP validation failures, without leaking token or proof contents.
  • Certificate issuance decisions, including match/deny reasons and server context.
  • Administrative changes to users, policies, SSL, notifications, and license.

Never Log Secrets

Never log passwords, OTP codes, access/refresh tokens, private keys, API secrets, cryptographic key material, or unredacted secret-bearing headers.

Audit retention guidance:

  • Define retention windows aligned to organizational policy and regulation.
  • Protect logs from modification and unauthorized deletion.
  • Forward security logs to a centralized SIEM where possible.

Pro Tip and Common Gotcha

Pro tip:

  • Run a monthly security drill: revoke one device, request one denied signing, and confirm logs capture both events end-to-end.

Common gotcha:

  • Teams often test token issuance but skip DPoP failure paths. Validate an invalid_dpop_proof error so replay protection is tested, not just assumed.