11 Security and Compliance

SSH Teams security is strongest when you treat it as an operational system, not just an authentication feature. This chapter gives you a practical secure-by-default path, then explains the deeper control model for audits and incident response.

11.1 Secure in 5 Steps (Quick Start)

Use this sequence first in every new environment:

Enforce least privilege roles (MANAGE_USERS, MANAGE_POLICIES, MANAGE_SERVERS) and minimize ADMIN users.
Confirm TLS certificate validity and trusted hostname for browser and CLI/API paths.
Require device-based authorization for CLI and verify device revocation workflow.
Validate one allow and one deny certificate request against policy.
Enable and review security event logs (auth, device, token, sign decisions, admin changes).

Expected outcome:

Web and CLI flows are authenticated, scoped, and auditable.
Certificate issuance is policy-driven and resistant to token replay.

If controls do not behave as expected, use 12-troubleshooting-handbook.md#124-device-flow-failures, 12-troubleshooting-handbook.md#125-policy-mismatch-and-access-denials, and 12-troubleshooting-handbook.md#126-certificate-issuance-failures.

11.2 Prerequisites

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 compliance review, confirm you can produce:

Recent admin change records.
Device approval and revoke evidence.
Sample issuance allow/deny evidence.

11.3 Authentication and Session Expectations

SSH Teams uses standard browser session authentication for the web UI and token-based authentication for CLI/API operations.

Why this matters:

Browser sessions protect operator workflows.
Token-based CLI auth protects automation and endpoint interactions.

Web session expectations:

Interactive login uses team user credentials and establishes 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 checks are role/permission-based (ADMIN, MANAGE_USERS, MANAGE_POLICIES, MANAGE_SERVERS).

Operator controls:

Restrict admin role assignment and prefer granular management roles.
Enforce strong password policy and centralized credential lifecycle controls.
Terminate stale sessions through standard logout and upstream session timeout policy.

11.4 API Access Controls and Unlicensed Behavior

API access is intentionally segmented by scope and endpoint behavior.

Access control model:

Device authorization endpoints issue scoped tokens (join and signing).
Join API requires a valid Bearer token with join scope.
Signing API requires Authorization: DPoP <token> and a valid DPoP proof.
Team and policy checks are enforced before certificate issuance.

License and operational mode considerations:

Community and licensed modes can affect available administration features.
Security-relevant controls (authentication, authorization, token validation, policy enforcement) remain mandatory regardless of edition.
Treat license state as a feature gate, not as an authorization boundary.

Compliance recommendation:

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

11.5 CLI Command Security: OAuth Tokens and DPoP

This section is critical for understanding why SSH Teams CLI usage is resistant to bearer-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) rely on OAuth device-style authorization:

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

Why DPoP matters

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

DPoP security properties:

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

How this ties devices to CA-backed issuance

The CA private key does not leave the server. Certificate issuance only happens after all of the following are true:

The device was explicitly approved through browser-mediated authorization.
The presented OAuth token is valid for the operation scope.
The DPoP proof validates for the bound device key.
Policy checks pass (user, principal, server fingerprint/tag/time constraints).

This creates an operational trust chain:

Approved user identity -> Approved device identity (DPoP key) -> Authorized signing request -> Certificate signed by team CA.

Security impact:

Stolen access token alone is insufficient to mint certificates.
Attackers must also control the device private key and satisfy policy constraints.
Device revocation immediately breaks future token usage and signing eligibility.

11.6 Secrets and Key Material Handling

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 client responses.
Store secrets encrypted at rest where supported by your deployment controls.
Rotate notification provider credentials and disable unused providers.
Restrict access to persistence volumes, backup artifacts, and runtime config files.
Use TLS for all operator and API traffic.

Backup and recovery controls:

Encrypt backups containing token/session/security metadata.
Restrict restore privileges and audit restore events.
Treat backup copies as production-equivalent sensitive data.

11.7 Audit and Logging Recommendations

Use verbose security-relevant logging with strict secret redaction.

Log categories to retain:

Authentication events (successful and failed login attempts).
Device authorization lifecycle (requested, approved, denied, expired).
Token and DPoP validation failures (without leaking token/proof payload secrets).
Certificate issuance decisions (policy matched/denied reasons, server fingerprint context).
Administrative changes (users, policies, SSL, notifications, license operations).

Do not log:

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

Audit retention recommendations:

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

11.8 Pro Tip and Common Gotcha

Pro tip:

Run a monthly security game-day: revoke one device, run one denied signing request, and verify logs capture both events end-to-end.

Common gotcha:

Teams often verify token issuance but skip DPoP error-path testing. Validate an invalid_dpop_proof failure case so replay protection is not only theoretical.