OpenBao: short-lived SSH certificates
Use OpenBao to sign an operator's SSH public key for the non-root Linux account deploy. The private key stays on the operator's workstation; the Debian target trusts the signing CA and checks the certificate locally. These are OpenSSH certificates, not X.509 certificates.
See installation, administration, and generic secrets for the surrounding setup. Commands below follow the official OpenBao 2.7.x documentation.
Machines and prerequisites
- Administrator workstation:
bao, an existing OpenBao administrator identity, and permission to configure this mount, role, policy, and userpass mapping. - Operator workstation:
bao, OpenSSH client tools, and the individual OpenBao useralice. Alice connects to Linux asdeploy; these are separate identities. - Debian target: OpenSSH server, an existing sudo-capable administrator, and a working recovery/console path. No OpenBao agent or CLI is needed here.
- OpenBao is initialized, unsealed, reachable over validated HTTPS, and already has userpass enabled. Clocks on OpenBao and the target are synchronized.
On both workstations, configure the actual OpenBao HTTPS address and, for a private TLS CA, its local certificate file:
Omit BAO_CACERT when the server certificate is already trusted by the system. Do not skip TLS verification. If BAO_TOKEN is exported, unset it before the userpass login so it does not override the cached login token.
1. Enable the signer and generate its CA
Administrator workstation: authenticate using your existing administrator account; substitute its actual username. The password is prompted, not supplied on the command line.
For a new mount:
bao secrets enable -path=ssh-client-signer ssh
bao write ssh-client-signer/config/ca \
generate_signing_key=true \
key_type=ssh-rsa \
key_bits=4096
Warning
Generate this CA once during provisioning. Do not blindly rerun these commands on an existing signer: changing its default CA can break authentication until hosts trust the new public key. Inspect existing configuration and plan CA rotation separately. Keep the CA private key inside OpenBao; never copy it to targets or operators.
Export the public CA and record its fingerprint through a trusted administrative channel:
bao read -field=public_key ssh-client-signer/config/ca \
> trusted-user-ca-keys.pub
ssh-keygen -lf trusted-user-ca-keys.pub
The public CA is not secret, but substituting it would let an attacker authorize their own certificates. Transfer it through authenticated configuration management or an existing SSH connection whose host key has already been verified.
2. Create a deploy-only signing role
Administrator workstation: use JSON stdin because extension and key-length settings are maps.
bao write ssh-client-signer/roles/deploy - <<'JSON'
{
"key_type": "ca",
"algorithm_signer": "rsa-sha2-256",
"allow_user_certificates": true,
"allow_host_certificates": false,
"allowed_users": "deploy",
"default_user": "deploy",
"allow_empty_principals": false,
"allow_user_key_ids": false,
"allowed_extensions": "permit-pty",
"default_extensions": {
"permit-pty": ""
},
"allowed_critical_options": "force-command,source-address",
"allowed_user_key_lengths": {
"rsa": [3072, 4096]
},
"ttl": "15m",
"max_ttl": "15m"
}
JSON
This allows only deploy, with at most 15 minutes of certificate validity. PTY allocation is permitted; agent, port, and X11 forwarding and user RC execution are not granted. For command-only deployments, use "allowed_extensions": "" and "default_extensions": {} instead.
The ssh-rsa CA key format does not mean SHA-1 signatures: the role explicitly uses rsa-sha2-256. Do not re-enable the obsolete SHA-1 ssh-rsa signing algorithm in sshd.
CA roles do not use cidr_list to restrict destination hosts. Limit where this CA is trusted and which principals each host accepts. A source-address critical option constrains the connecting client's address, not the destination.
3. Give the operator signing permission
Administrator workstation: create only the signing policy, not an administrator policy:
bao policy write ssh-deploy - <<'HCL'
path "ssh-client-signer/sign/deploy" {
capabilities = ["create", "update"]
}
HCL
The current SSH API documentation specifies both capabilities for signing. This policy grants no CA/issuer management, role modification, or access to issue/* for generating private keys.
Attach ssh-deploy through the operator's existing authentication mapping. For an existing userpass user alice, first inspect the current mapping:
If Alice should have exactly team-secrets from secrets.md plus this signing policy:
Warning
This replaces the userpass token-policy list; it does not append to it. Preserve any other intended policies, and do not grant team-secrets unless Alice needs that access. Updating the mapping affects newly issued tokens, so Alice must log in again. Existing tokens are not automatically revoked.
If Alice does not exist, provision her through your normal process in administration.md. Alternatively, this Bash snippet creates a signing-only user with a hidden password prompt. Run it without shell tracing or session recording; do not use it to overwrite an existing user's settings.
read -r -s -p 'New OpenBao password for alice: ' ALICE_PASSWORD
printf '\n'
printf '%s' "$ALICE_PASSWORD" | bao write auth/userpass/users/alice \
password=- token_policies=ssh-deploy token_ttl=30m token_max_ttl=1h
unset ALICE_PASSWORD
The shell builtin printf passes the password through stdin, not a bao argument or literal shell-history entry. Communicate it securely to Alice. Do not attach administrator permissions to this user.
4. Provision the Debian account and CA trust
Debian target, using the existing Linux administrator: inspect any existing deploy account before changing it. For a new account:
Give this account only the filesystem/application permissions it needs. Do not add it to sudo, docker, or other effectively root-capable groups merely to make deployment work.
Warning
--disabled-password avoids setting a Linux password, but key/certificate login still depends on PAM and account-access checks. Debian normally uses UsePAM yes; retain it. Some hardened configurations reject locked accounts even with valid certificates. If logs report a locked or expired account, review PAM, password/account expiry, and the login shell. Do not fix this by setting an empty password, disabling PAM, or blindly unlocking the account.
Transfer trusted-user-ca-keys.pub from step 1 to this administrator's home directory using the already trusted connection. On the target, compare its fingerprint with the trusted recorded value before installing it:
ssh-keygen -lf "$HOME/trusted-user-ca-keys.pub"
sudo install -o root -g root -m 0644 \
"$HOME/trusted-user-ca-keys.pub" /etc/ssh/trusted-user-ca-keys.pub
sudo install -d -o root -g root -m 0755 /etc/ssh/auth_principals
printf '%s\n' deploy | sudo tee /etc/ssh/auth_principals/deploy > /dev/null
sudo chown root:root /etc/ssh/auth_principals/deploy
sudo chmod 0644 /etc/ssh/auth_principals/deploy
The principals file contains the name deploy, not a public key. One certificate principal must match it. Do not put deploy in another account's principals file: that would map these certificates to that account too.
5. Configure and validate Debian sshd
Debian target: keep the existing administrator SSH session open and ensure console/recovery access works. Confirm /etc/ssh/sshd_config includes /etc/ssh/sshd_config.d/*.conf near its start, as Debian normally does. Inspect existing drop-ins before adding a new, root-owned file:
sudo install -d -o root -g root -m 0755 /etc/ssh/sshd_config.d
sudoedit /etc/ssh/sshd_config.d/00-openbao-user-ca.conf
Contents:
PubkeyAuthentication yes
TrustedUserCAKeys /etc/ssh/trusted-user-ca-keys.pub
AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u
PermitRootLogin no
LogLevel VERBOSE
These are global settings: root SSH login is disabled, and other certificate-authenticated accounts need their own principals files. Without an AuthorizedPrincipalsFile or command, sshd instead requires the login username in the certificate's principals list.
This does not disable ordinary authorized_keys, password, or other authentication methods. For certificate-only deploy access, separately restrict those alternatives under your host's access policy, including any AuthorizedKeysCommand. Do not copy the operator's plain public key into authorized_keys as a workaround: it would bypass certificate expiry.
Avoid introducing a Match block into this early Debian drop-in: its scope can carry into later included configuration. Review any existing Match, AllowUsers, or DenyUsers rules as well.
Validate syntax and inspect the effective settings; substitute the real client address and hostname when testing connection-specific rules:
sudo /usr/sbin/sshd -t
sudo /usr/sbin/sshd -T -C user=deploy,addr=192.0.2.10,host=operator.example.com \
| grep -E '^(pubkeyauthentication|trustedusercakeys|authorizedprincipalsfile|permitrootlogin|usepam|loglevel) '
Only after both checks succeed and the values are correct:
OpenSSH generally uses the first obtained setting; an earlier drop-in may win. Syntax validation is not proof that authentication works. Keep the administrator session open until a fresh deploy login succeeds.
6. Request a certificate and connect
Operator workstation: generate a dedicated RSA key once, choosing a strong passphrase when prompted. Do not overwrite an existing key.
mkdir -p "$HOME/.ssh"
chmod 0700 "$HOME/.ssh"
ssh-keygen -t rsa -b 3072 -f "$HOME/.ssh/deploy" -C 'alice deployment'
bao login -no-print -method=userpass username=alice
Request and save the certificate:
bao write -field=signed_key ssh-client-signer/sign/deploy \
public_key=@"$HOME/.ssh/deploy.pub" \
valid_principals=deploy cert_type=user ttl=15m \
> "$HOME/.ssh/deploy-cert.pub"
ssh-keygen -Lf "$HOME/.ssh/deploy-cert.pub"
Check that issuance succeeded, the principal is deploy, and the validity interval and extensions are expected. public_key=@... reads the public-key file's contents; never submit the private key. An @filename inside JSON is not expanded by the CLI.
Connect with the certificate and its matching private key:
ssh -o IdentitiesOnly=yes -o ControlPath=none \
-o CertificateFile="$HOME/.ssh/deploy-cert.pub" \
-i "$HOME/.ssh/deploy" [email protected]
ControlPath=none avoids reusing an already authenticated connection during testing. The deploy-cert.pub filename also supports automatic certificate discovery alongside deploy. Repeat the signing request when a new certificate is needed; OpenBao does not store the issued certificate for later retrieval.
Keep normal SSH host-key verification enabled. These user certificates authenticate Alice to the target; they do not authenticate the target to Alice. Verify unfamiliar host fingerprints through a trusted channel.
For failures, inspect ssh -vv on the workstation and sudo journalctl -u ssh --since '10 minutes ago' on Debian. Check the principal, CA fingerprint, file ownership/readability, clock, and PAM/account restrictions rather than weakening authentication.
Expiration, revocation, and private-key storage
Warning
Certificate expiry prevents new authentication; it does not disconnect existing sessions or prevent new channels on an already authenticated multiplexed connection. Revoking an OpenBao token, deleting a signing role, or deleting the CA inside OpenBao does not invalidate certificates already trusted by sshd.
Remove signing permission and revoke relevant OpenBao tokens to stop future issuance. For emergency rejection before expiry, distribute an OpenSSH KRL using sshd's RevokedKeys, or remove the compromised CA from host trust. Manage established sessions separately. An unreadable RevokedKeys file can deny all public-key authentication; deploy updates atomically and test them.
Keep session-duration enforcement separate from the certificate TTL. SSH keepalives detect unresponsive clients; they are not an absolute session deadline. Use reviewed host/session controls if deployment access must terminate at a specific time.
KV v2 secrets can store an existing SSH private key when centralized retrieval is genuinely required, but that is static secret storage, not this signing workflow. Readers can copy the key; KV deletion does not revoke it on remote hosts. Prefer individual, passphrase-protected local keys and short-lived certificates. Never store the signing CA private key in a team-readable KV path.
Official references
- OpenBao signed SSH certificates
- SSH API: roles, CA configuration, and signing
- Userpass API: users and policy mapping
- CLI write: file and stdin input
- OpenBao policies
- Debian sshd configuration
- Debian adduser and disabled passwords
- Debian sshd account checks
- OpenSSH client certificate configuration
- OpenSSH key revocation lists