Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 36 ยท Secrets Engines

The SSH Secrets Engine

Learn how Vault controls SSH access with signed SSH certificates and one-time passwords, how to configure a CA, roles and servers, and the trade-offs of each mode.

Distributing SSH public keys to every server, and remembering to remove them when people leave, is another form of secret sprawl. The SSH secrets engine lets Vault decide who may log in to which servers, and for how long. It has two main modes: signed SSH certificates (the recommended one) and one-time passwords (OTP). A third, dynamic SSH keys, is deprecated.

This lesson explains both modes, the setup steps and the trade-offs, and gives runnable models of the signing rules and OTP behaviour.

Vault and SSH servers are not available here. Commands are read-only, and the Python examples model validation and expiry rules without doing any real cryptography.

Signed SSH certificates

OpenSSH supports certificates: a public key signed by a certificate authority, with a validity period and a list of allowed usernames (principals). Servers trust the CA's public key instead of listing individual user keys.

sequenceDiagram
    participant U as User
    participant V as Vault (SSH CA)
    participant H as SSH host
    U->>V: login, send public key, ask to sign
    V-->>U: certificate valid 30 min, principal "deploy"
    U->>H: ssh with key + certificate
    H->>H: trusts the CA key, checks validity and principal
    H-->>U: access granted

Hosts trust one CA key; access is granted by short-lived certificates.

Setup on the Vault side:

Terminal
vault secrets enable -path=ssh-client-signer ssh
vault write ssh-client-signer/config/ca generate_signing_key=true   # Vault makes the CA key pair
vault read -field=public_key ssh-client-signer/config/ca > trusted-user-ca-keys.pem

vault write ssh-client-signer/roles/deploy -<<"EOH"
{
  "algorithm_signer": "rsa-sha2-256",
  "allow_user_certificates": true,
  "allowed_users": "deploy,ops",
  "default_user": "deploy",
  "ttl": "30m0s",
  "max_ttl": "4h",
  "default_extensions": { "permit-pty": "" }
}
EOH

On each SSH server, copy trusted-user-ca-keys.pem to a path such as /etc/ssh/trusted-user-ca-keys.pem and add this line to sshd_config, then reload sshd:

TEXT
TrustedUserCAKeys /etc/ssh/trusted-user-ca-keys.pem

A user then asks Vault to sign their existing public key:

Terminal
vault write -field=signed_key ssh-client-signer/sign/deploy \
    public_key=@$HOME/.ssh/id_ed25519.pub > ~/.ssh/id_ed25519-cert.pub
ssh -i ~/.ssh/id_ed25519-cert.pub -i ~/.ssh/id_ed25519 deploy@host

The private key never leaves the user's machine. Access ends when the certificate expires; nothing needs to be removed from servers.

One-time passwords

In OTP mode, Vault generates a password valid for one login. A small helper, vault-ssh-helper, runs on each target host and, through PAM, checks the password with Vault, which then marks it used. OTP suits environments where you cannot change the SSH server configuration enough to use certificates. It requires installing and maintaining the helper on every host, and the OTP travels as a password, so certificate mode is generally preferred.

Terminal
vault write ssh/creds/otp-role ip=10.0.0.5

Which mode?

Mode Server changes Private key Revocation
Signed certificates One sshd_config line Stays on the client Short TTL
OTP Install helper, PAM None One use

Principal checks you can run

This model checks that a requested principal and TTL match the role, as Vault would before signing.

Python Validate an SSH signing request against a role

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Certificate validity on the host

A host enforces the validity window and the principal list itself. This model mirrors that check, including clock skew.

Python Model of how an SSH host checks a certificate

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Hosts need accurate clocks: a few minutes of skew will make 30-minute certificates fail.

Good practice

  • Keep certificate TTLs short (minutes to hours) and rely on Vault authentication, with MFA, as the gate.
  • Use one role per purpose, with a narrow allowed_users list, rather than allowing any username.
  • Consider a separate host-signing CA so clients can verify servers without trust-on-first-use prompts.
  • Protect ssh-client-signer/config/ca with policy; whoever can sign can become any allowed principal.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What do SSH servers trust in the signed certificate mode?

    Servers list a trusted CA key with TrustedUserCAKeys and accept certificates signed by it.
  2. 2. What is a principal in an SSH certificate?

    The server checks that the login name is among the certificate's principals.
  3. 3. Why can access end without touching the servers?

    Certificates carry a validity period, so a short TTL removes access automatically.
  4. 4. Which mode needs vault-ssh-helper on every host?

    OTP mode checks passwords with Vault through a PAM helper on each target host.

Summary

  • The SSH engine replaces scattered authorized_keys with CA-signed, short-lived certificates (recommended) or one-time passwords.
  • Hosts trust one CA key; users get signed certificates after authenticating to Vault.
  • Roles control allowed users, extensions and TTLs.
  • OTP needs a helper and PAM on each host; certificates need one sshd_config line.
  • Keep clocks accurate and certificate lifetimes short.

Next: Authentication Methods Overview