Architecture overview

Traditional SSH access relies on static, long-lived SSH keys, which can be difficult to manage, audit, and revoke across a large fleet of nodes. Short-lived token-based SSH access addresses these security challenges by replacing static keys with ephemeral, time-bound credentials.

Instead of distributing individual public keys to every server, this architecture uses SSH certificates. An operator’s public key is cryptographically signed by a central certificate authority (CA) that is HashiCorp Vault in this blueprint. The resulting certificate contains specific permissions, allowed target principals (user names), and a strict expiration time (TTL). Because target nodes are configured to trust the CA globally, they automatically accept any valid, unexpired certificate it issues, eliminating the need for per-node user key management.

Components and their roles

The following components are involved in this blueprint:

Keycloak

Central identity provider (IdP) and single sign-on (SSO) engine. Authenticates user identities, enforces multi-factor authentication (MFA), and emits OIDC tokens containing user claims and group memberships.

HashiCorp Vault

Trusted SSH certificate authority. Validates OIDC tokens issued by Keycloak, maps external OIDC groups to internal Vault policies, and cryptographically signs ephemeral SSH client public keys.

MOSK cluster nodes (SSH hosts)

Target Linux servers configured to trust the Vault SSH CA public key using the OpenSSH TrustedUserCAKeys option. Nodes validate incoming client certificates locally without querying Vault during login.

SSH client/operator CLI

Workstation used by administrators to authenticate to Keycloak through the Vault OIDC flow, obtain signed SSH certificates, and establish SSH sessions to MOSK nodes.

Authentication flow

  1. The operator initiates login using the Vault UI or CLI (vault login -method=oidc).

  2. Vault redirects the operator’s browser to the Keycloak OIDC authorization endpoint.

  3. Keycloak prompts for primary user credentials (user name and password) and enforces MFA (TOTP, WebAuthn/FIDO2) if configured for the realm or user role.

  4. Upon successful MFA verification, Keycloak issues an ID token containing the user’s identity and group claims, for example, ssh-operators.

  5. Vault validates the token signature against the Keycloak JWKS endpoint, maps the OIDC groups to internal identity groups, and grants an ephemeral Vault token bound to the assigned ACL policy (ssh-allow).

  6. The operator uses the Vault token to request a signed SSH certificate.