SSH certificates

How it works

An OpenSSH user certificate is your public key signed by a certificate authority (CA), with a list of allowed Unix usernames (principals) and an expiry time. A server that lists the CA in TrustedUserCAKeys accepts any unexpired certificate it signed, for the usernames it names. No per-user authorized_keys entry is needed, and access ends on its own when the certificate expires.

Three ways to get a certificate

All three sit in the same key-file section. If more than one is set, MangoSSH uses the first in this order:

Fetched certificates are held in memory for that one login and never written to disk.

Use a certificate file

1. Set up the host with SSH Key and the private key the certificate was issued for.

2. Fill in SSH Certificate file (optional), or click Browse…. OpenSSH names it after the key, for example .ssh/id_ed25519-cert.pub. Relative paths start from your home folder.

The SSH Keys page lists every host's certificate file under SSH certificates, with how long each has left. It flags certificates that are expired, not yet valid, or expire within 30 days.

The built-in MangoSSH CA

Each Self Hosting Vault or Cloud Vault can act as a CA for its members. You never choose your own principals: an admin sets, per vault role, which Unix accounts that role may log in as. A member's device asks for a certificate at connect time, signed with its device identity, and the server decides what goes in it.

Step 1 — Turn the CA on

On a self-hosted server, CA_MASTER_KEY must be set in the vault server's .env (the self-hosting bundle's installer sets it for you); Self-hosting the vault server shows how to generate the value. Vaults created after that get a CA automatically. For a vault that existed before, an admin opens the Certificates tab (below) and clicks Enable the Certificate Authority.

Step 2 — Decide who may get a certificate

1. On an admin device, open Settings → Self Hosting Vault (or Cloud Vault) and click Vault Dashboard. Open the Certificates tab.

2. Under Who may be issued a certificate, each role (admin, editor, viewer) has three settings:

   • Principals: the Unix accounts the role may log in as, comma-separated, such as ubuntu, deploy. Empty means the role is refused a certificate. Every role starts empty, so nobody gets one until you fill this in.
   • Max lifetime in seconds. The server caps it at 3600.
   • needs a grant: issue a certificate only while the member holds an approved just-in-time grant for that host. The certificate then also expires when the grant does. The server enforces this; a modified client cannot skip it.

3. Click Save Policy.

If the vault requires single sign-on or device posture, those checks also apply before a certificate is issued.

Step 3 — Make each server trust the CA

This step has no shortcut: a server without the CA's public key rejects every certificate. The Certificates tab has Copy Public Key and Copy Directive. Install it by hand:

# on the server, as root: paste the CA public key into the file
sudo tee /etc/ssh/mangossh_ca.pub <<'EOF'
ssh-ed25519 AAAA...paste the key from "Copy Public Key"...
EOF
sudo chmod 644 /etc/ssh/mangossh_ca.pub

# add this line to /etc/ssh/sshd_config, above any Match block
TrustedUserCAKeys /etc/ssh/mangossh_ca.pub

sudo sshd -t && sudo systemctl reload sshd   # the service is called "ssh" on Debian and Ubuntu

Or let MangoSSH do it. Connect to the server first, then edit the host and click Deploy to This Host… under the CA toggle (see Step 4). It needs root, or a user with passwordless sudo. It writes /etc/ssh/mangossh_ca.pub, backs up sshd_config to /etc/ssh/sshd_config.mangossh.bak, adds the line, checks the result with sshd -t, and restores the backup if the check fails. It reloads sshd rather than restarting it, so your session stays up. It edits only /etc/ssh/sshd_config; if sshd runs with another config file, it stops and tells you.

Step 4 — Turn it on for a host

1. Edit the host. On the Authentication tab choose SSH Key and set the private key file. Any key works; it is the key that gets signed.

2. In the Enterprise section, turn on Use this vault's certificate authority. Signing vault shows the CA's fingerprint.

3. Optionally set Lifetime (seconds). Blank means 300. The server lowers it to your role's maximum, then to its one-hour ceiling.

4. Click Test. It asks for a certificate without connecting and shows the serial number and the principals you were given. The host's Username must be one of those principals.

The certificate's key ID reads mangossh device=… host=…, plus jit=… when a grant justified it. sshd writes that into the server's auth log, so the server's own logs show which device logged in. Admins see the latest issues under Recently issued on the Certificates tab.

Rotating the CA

Rotate CA Key… creates a new CA key for the vault. Every certificate issued so far stops working as soon as each server has the new public key, and servers reject all new certificates until they get it. Run Deploy to This Host… again on each server (it refreshes the key file), or update /etc/ssh/mangossh_ca.pub by hand. Serial numbers keep counting up across rotations, so a revocation list never becomes ambiguous.

HashiCorp Vault SSH

If your organisation already runs Vault's SSH secrets engine, MangoSSH can have Vault sign your key on every connect. Open the HashiCorp Vault SSH (optional — overrides the certificate file above) section under SSH Key.

Click Test to have Vault sign the key without connecting. The section only takes effect once Vault address and Role are both filled in.

Token sign-in

With Token (env, ~/.vault-token, or below), MangoSSH uses the first token it finds: the VAULT_TOKEN environment variable, then ~/.vault-token (written by vault login), then a token saved for this host with Save token to OS keychain.

Sign in with your identity provider

With Identity provider (OIDC — Okta, Entra ID, Google), you sign in through Vault's OIDC auth method in your normal browser, so whatever MFA and conditional access your tenant enforces applies as usual.

1. Set OIDC mount (blank means oidc) and OIDC role (blank uses the mount's default role).

2. Make sure the Vault OIDC role lists http://localhost:8250/oidc/callback in its allowed_redirect_uris. That is also what vault login -method=oidc uses, so it is often already there.

3. Click Sign in. Your browser opens; finish signing in within three minutes. The status line then shows how long the token lasts.

The token is cached in your OS keychain per Vault address, mount and role, so every host using the same role shares one sign-in. When it has expired, connecting opens the browser again by itself. Sign out forgets it. In OIDC mode MangoSSH never falls back to VAULT_TOKEN or ~/.vault-token, so you cannot end up connecting as a different identity by accident.

Vault server setup, for reference

A minimal Vault setup that works with the fields above. Adjust usernames and lifetimes to your policy:

vault secrets enable -path=ssh ssh
vault write ssh/config/ca generate_signing_key=true
vault write ssh/roles/my-role - <<'EOF'
{
  "key_type": "ca",
  "allow_user_certificates": true,
  "allowed_users": "ubuntu,deploy",
  "default_extensions": { "permit-pty": "" },
  "ttl": "30m"
}
EOF

# on each server: trust Vault's CA
vault read -field=public_key ssh/config/ca | sudo tee /etc/ssh/vault_ca.pub
# then in sshd_config:  TrustedUserCAKeys /etc/ssh/vault_ca.pub

Server-side sshd_config

Everything a server needs, in one place. A file can list several CA keys, one per line, if you trust more than one CA.

# /etc/ssh/sshd_config — put these above any Match block
TrustedUserCAKeys /etc/ssh/mangossh_ca.pub
RevokedKeys /etc/ssh/revoked_keys.krl          # optional, see below
# optional: map principals to accounts yourself instead of by username
# AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u

Check with sudo sshd -t and reload sshd. On Windows OpenSSH (C:\ProgramData\ssh\sshd_config), placement matters even more: a Match block has no closing line, so a TrustedUserCAKeys line placed after one only applies to that block's users.

Revoking certificates with a KRL

Short-lived certificates mostly revoke themselves. For anything that must stop working before it expires, use an OpenSSH key revocation list (KRL):

# revoke by serial (shown under "Recently issued", or by ssh-keygen -Lf cert.pub)
echo "serial: 42" > revoke.txt
ssh-keygen -k -f revoked_keys.krl -s mangossh_ca.pub revoke.txt
# add more later with -u:  ssh-keygen -k -u -f revoked_keys.krl -s mangossh_ca.pub more.txt
# check a certificate:     ssh-keygen -Q -f revoked_keys.krl id_ed25519-cert.pub

• On the server, RevokedKeys is what actually blocks a login. Copy the KRL to every server.
• In MangoSSH, set Revocation list — KRL (optional, requires a certificate above) on the host. Before connecting, MangoSSH checks the certificate from any of the three sources against it, refuses to connect if it matches, and writes the refusal to the audit log. A policy can set one KRL path for many hosts at once.

MangoSSH's own check understands revoked serial numbers and serial ranges, key IDs and explicit keys. It is a local safety net; keep RevokedKeys on the servers as the real enforcement.

Troubleshooting