SSH Certificate Authority (SSH CA)

Sign in once with your company identity provider and sshs3 hands you a short-lived OpenSSH user certificate. There are no long-lived keys to distribute, rotate or revoke on your servers: they trust the CA, and the certificate expires on its own. sshs3 works with Smallstep Step-CA and HashiCorp Vault / OpenBao, and the private key is either generated in memory for each login or stays on your smartcard.

1. How It Works

You authenticate with an OpenID Connect (OIDC) identity provider such as Keycloak, Okta, Google Workspace or Microsoft Entra ID. The browser sign-in uses the authorization code flow with PKCE and returns to a loopback address that only sshs3 listens on.

sequenceDiagram
    participant U as You
    participant S as sshs3
    participant I as Identity provider
    participant C as CA (Step-CA or Vault / OpenBao)
    participant H as SSH server
    U->>S: Log In with SSH CA
    S->>I: Open browser, authorization code + PKCE
    I-->>S: ID token (via loopback redirect)
    S->>C: Public key + ID token
    C-->>S: Signed SSH user certificate
    S->>S: Load certificate into the app agent
    U->>H: Connect (certificate presented by ssh)
    H-->>U: Trusted CA, principal allowed: logged in

2. Quick Start

1. Prepare your identity provider and the CA (section 3 and 4). This is done once by an administrator.
2. Open Settings → Security & Smartcard, scroll to SSH Certificate Authorities (SSH CA) and click Add CA.
3. Fill in the CA and the identity provider (section 5), click Save Configuration, and save the settings dialog.
4. Click Authenticate with CA on the new entry. Your browser opens; sign in. The entry shows Active (your name).
5. In a connection profile, set Authentication to SSH Agent and tick Use active SSH Certificate Authority session.
6. Open the connection. The Shield icon in the top toolbar is green while the certificate is valid.

3. Prepare the Identity Provider

Create an OIDC client for sshs3 with these properties:

4. Prepare the CA and the Servers

4.1 Step-CA

Add an OIDC provisioner whose client ID is the one you gave sshs3, and make sure SSH certificates are enabled on the CA:

step ca provisioner add keycloak --type oidc \
  --client-id sshs3 \
  --configuration-endpoint https://keycloak.example.com/realms/sshca/.well-known/openid-configuration \
  --domain example.com

Your step version may also ask for --client-secret; sshs3 never sends one. sshs3 sends the ID token to POST /1.0/ssh/sign as the one-time token, with the certificate type user and any Default Principals you configured. The provisioner's own listenAddress and client secret are only used by Smallstep's CLI; sshs3 runs its own sign-in. Without requested principals, Step-CA derives them from the email claim of the token (for carl@example.com: carl and carl@example.com). Templates can add more, for example from a groups claim.

4.2 Vault / OpenBao

sshs3 logs in to the JWT auth method with the ID token, signs the public key with the SSH secrets engine, and then revokes its own short-lived token. The commands below use bao; with HashiCorp Vault use vault.

# 1. JWT auth method: trust the identity provider, one role for sshs3 users
bao auth enable jwt
bao write auth/jwt/config oidc_discovery_url="https://keycloak.example.com/realms/sshca"
bao write auth/jwt/role/sshs3 role_type=jwt user_claim=preferred_username \
    bound_audiences=sshs3 token_policies=sshs3-sign

# 2. SSH secrets engine as a user CA
bao secrets enable -path=ssh-client-signer ssh
bao write ssh-client-signer/config/ca generate_signing_key=true
bao write ssh-client-signer/roles/client -<<'EOH'
{
  "key_type": "ca",
  "allow_user_certificates": true,
  "allowed_users": "*",
  "default_extensions": { "permit-pty": "" },
  "ttl": "30m"
}
EOH

# 3. Policy that lets the sshs3 role sign with that SSH role
bao policy write sshs3-sign - <<'EOH'
path "ssh-client-signer/sign/client" { capabilities = ["create", "update"] }
EOH

In sshs3, select OpenBao / HashiCorp Vault and enter the mount names and roles (section 5). A requested principal must be allowed by the SSH role's allowed_users. The requested Default Principals are sent as valid_principals, and the SSH role's ttl sets how long the certificate is valid.

4.3 Your servers

Servers only need to trust the CA's public key. Print it from the CA (Step-CA: step ssh config --roots; OpenBao: bao read -field=public_key ssh-client-signer/config/ca), save it on the server, for example as /etc/ssh/ca.pub, and add it to sshd_config:

TrustedUserCAKeys /etc/ssh/ca.pub

By default a certificate is accepted for any principal that equals the login name. To map principals to accounts yourself, use AuthorizedPrincipalsFile (see sshd_config(5)). No per-user authorized_keys entries are needed.

5. Configure sshs3

Open Settings → Security & Smartcard and click Add CA. You can define several CAs; Set as Default chooses the one that Log In with SSH CA in the toolbar uses.

Authenticate with CA on an entry runs the full sign-in for that CA and reports Successfully authenticated as <name>! Certificate active. or the error. It is a real login, not a dry run.

6. Daily Use

The status badge

Click the Shield icon in the top toolbar, or focus it and press Enter. Press Escape to close the popup.

Connection profiles

Set Authentication to SSH Agent and tick Use active SSH Certificate Authority session. Terminals, SFTP and file-manager connections, SSH tunnels and Test connection then use the active certificate. When no certificate is active, sign in first; the profile does not trigger a sign-in by itself.

Renewal

• Automatic: if the identity provider issues a refresh token, sshs3 renews the certificate about 60 seconds before it expires. It does this silently and never opens a browser by itself. With the smartcard key source the card has to be unlocked: if you locked it, sshs3 asks for the PIN again. If the silent renewal fails, the certificate runs out and the badge shows Inactive.
• Manual: Renew Certificate tries a silent refresh first and falls back to a browser sign-in if that fails.
• Log Out also cancels a sign-in that is still waiting in the browser.
• Restarting sshs3 ends the session; sign in again.

7. Key Sources

The smartcard source works with any PKCS#11 smartcard that exposes an authentication key, not only YubiKeys. sshs3 asks for the card's PIN when you sign in.

8. Security Model

sshs3 checks every certificate before it uses it, and keeps tokens out of storage:

Technical Architecture: Where Things Live

SshCaService owns the session, installs the certificate and schedules renewal. oidcFlow runs the browser sign-in and token refresh, and an operation queue serialises login, renewal and logout. The Step-CA and Vault providers only perform the signing call. Terminals and SFTP receive the agent socket and, for smartcards, the certificate file through the same preparation step as other agent-based profiles.

9. Troubleshooting & Diagnostics