A new path from SSO to SSH

OPKSSH (OpenPubkey SSH) has been released as open source under the OpenPubkey project, after Cloudflare gifted the code — previously owned by BastionZero, which Cloudflare acquired — to the project. The tool lets users authenticate to SSH servers with OpenID Connect single sign-on, eliminating manual SSH key management without introducing any trusted party beyond the user's identity provider (IdP).

OpenPubkey itself became a Linux Foundation project in 2023, but its SSH support was previously only a prototype bundled with the main project. OPKSSH turns that into a complete, production-ready feature.

Why SSH key management is a problem

Traditional SSH relies on long-lived key pairs. Users generate a public and private key, then distribute the public key to any server they need to access. The private key must be stored securely; losing it means lockout, while copying it across machines or backups increases exposure. When a key is compromised or a user's access should be revoked, someone must manually remove the public key from every server that trusts it.

"In many organizations – even very security-conscious organizations – there are many times more obsolete authorized keys than they have employees. Worse, authorized keys generally grant command-line shell access, which in itself is often considered privileged. We have found that in many organizations about 10% of the authorized keys grant root or administrator access. SSH keys never expire." – Tatu Ylonen, inventor of SSH, in Challenges in Managing SSH Keys

OPKSSH addresses these issues by replacing long-lived keys with ephemeral ones tied to SSO identity:

  • Security: Keys are generated on demand and expire by default after 24 hours (configurable via a configuration file). This shrinks the window in which a compromised private key is usable.
  • Usability: Generating an SSH key is reduced to signing in to an OpenID Provider. Users can SSH from any machine with OPKSSH installed, no key copying required.
  • Visibility: Authorization shifts from public keys to email addresses. Adding a user to a server means adding their email to an authorized users file, and administrators can see exactly who has access.

No changes to SSH client or server software are needed. On the server side, two lines added to the SSH config file — typically done via an installation script — are sufficient.

From ID Tokens to PK Tokens

OpenID Connect (OIDC) is the standard protocol for SSO. A user authenticates to an OpenID Provider (OP) — Google, Azure, Okta, and others — and receives a digitally signed ID Token containing identity claims such as email address. The problem: ID Tokens contain no public key, so they cannot directly secure protocols like SSH.

OpenPubkey solves this by adding a user public key to the ID Token, producing what the project calls a PK Token — essentially a statement from the OP that a specific identity is using a specific public key. This works with any OIDC-compliant OP and requires no changes to existing SSO protocols. OPKSSH then packages that PK Token into the SSH authentication flow.

How OPKSSH works

Consider Alice ([email protected]) connecting to a server:

  1. Alice runs opkssh login, which generates an ephemeral key pair and opens a browser window for SSO with her provider, e.g., Google.
  2. Upon successful authentication, OPKSSH holds a PK Token binding Alice's identity to her ephemeral public key.
  3. The token is saved in Alice's .ssh directory — the public key file contains the PK Token, the private key is her ephemeral key.
  4. When Alice runs ssh, the client sends the public key file to the server.
  5. The server forwards it to the OpenPubkey verifier via the AuthorizedKeysCommand directive in sshd_config.
  6. The verifier checks the token is unexpired, valid, and signed by the OP; confirms the key in the token matches the key in the SSH public key field; extracts the email address; and checks that address against the server's authorized users list.

Three design decisions make this work without protocol changes:

  • Transporting the token: SSH public keys can be certificates with an extension field for arbitrary data. The PK Token is placed in that extension, so it travels to the server as a normal part of the SSH handshake.
  • Server-side verification: SSH servers support AuthorizedKeysCommand, which delegates authorization decisions to an external program. The OpenPubkey verifier plays that role via a two-line change to sshd_config.
  • Key binding: The verifier checks that the public key inside the PK Token is identical to the key in the SSH public key field — since that SSH key is what secures the session, a match proves the token belongs to the connecting user.

Open-sourcing OPKSSH

OPKSSH is available at openpubkey/opkssh under the Apache 2.0 license. Relative to the earlier OpenPubkey SSH prototype, it adds automated installation, improved configuration tooling, and production-ready SSH support. Cloudflare is donating the code, not endorsing the project. Documentation is in the OPKSSH readme, and contributions are welcome via the project's GitHub repositories, the monthly community meeting, or the #openpubkey channel on the OpenSSF Slack.