Skip to content

About

SSH CA signing based on Open ID Connect authorizations

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

ssh-casign

An SSH certificate authority that issues short-lived SSH certificates to users who have authenticated with an OpenID Connect (OIDC) identity provider.

The user runs a client. The client authenticates the user against the IdP (the device flow, or the authorization code flow in a browser) and sends the user's SSH public key together with the token to the signing service. The service validates the token, maps the token's claims to a certificate profile and returns a signed certificate. The client writes the certificate to disk or loads it into ssh-agent.

Status: experimental. Sign-in (device flow and browser), certificate issuance, ssh-agent loading and sshd login work end to end against Dex. See docs/status.md.

Workspace layout

Path Contents
ssh-casign-service/ The service binary: config source, logging, TLS, which backends a build has
ssh-casign-core/ Service logic: OIDC, certificate policy, key IDs, audit, HTTP API
ssh-casign-ca/ Backend API, certificate encoding and verification, authorities
ssh-casign-ca-file/ Backend: OpenSSH private key file
ssh-casign-ca-pkcs11/ Backend: PKCS#11 tokens (YubiKey, smart cards, HSMs)
ssh-casign-ca-vault/ Backend: OpenBao / HashiCorp Vault transit
ssh-casign-ca-azure/ Backend: Azure Key Vault / Managed HSM, Entra ID credentials
ssh-casign-ca-aws/ Backend: AWS KMS, SigV4 and AWS credentials
ssh-casign-ca-gcp/ Backend: Google Cloud KMS and Google credentials
ssh-casign-ca-barbican/ Backend: OpenStack Barbican with Keystone authentication
ssh-casign-client/ CLI client (clap): discovery, sign-in, login, cert, logout
ssh-casign-proto/ Wire types shared by service and client
deploy/ Platform packages (Azure Functions, AWS Lambda, Cloud Run), static build
tests/e2e/ End-to-end suite: scenarios, fixtures, mocks; run.sh with podman
ci/ check.sh: the static checks and unit tests CI runs

Backend crates depend only on ssh-casign-ca; the core never depends on a backend. The service binary registers the backends its Cargo features (ca-*) select.

Flow

 ssh-casign-client                 OIDC IdP                  ssh-casign-service
 -----------------                 --------                  ------------------
 0. GET /.well-known/ssh-casign  ------------------------------------------>
    <---------------------------  issuer, client_id, scopes, sign endpoint, CAs
 1. device flow, or
    authorization code + PKCE  -->
                               <-- 2. token (JWT)
 3. POST /sign  { public_key, cert_type }
    Authorization: Bearer <token>  ---------------------------------------->
                                                             4. validate JWT (JWKS,
                                                                exp, nbf, iss, aud)
                                                             5. pick profile from claims
                                                             6. build options, sign
    <------------------------------------------------------ 7. { "certificate": ... }
 8. write <key>-cert.pub (later: add to ssh-agent)

Service

HTTP API

GET /.well-known/ssh-casign returns the discovery document. With it, a client needs only the service URL:

{
  "issuer": "https://idp.example.com/realms/ssh",
  "client_id": "ssh-casign",
  "scopes": ["openid", "profile"],
  "sign_endpoint": "../sign",
  "revocation_list": "../revoked.krl",
  "revocation_list_signatures": "../revoked.krl.sig",
  "trust": { "statement": "{\"id\":\"example\",...}", "signatures": ["-----BEGIN SSH SIGNATURE-----..."] },
  "authorities": {
    "default": { "public_key": "ssh-ed25519 AAAA...", "cert_types": ["user"] }
  }
}

sign_endpoint is relative to the discovery document's URL. It therefore still resolves correctly when the service is published under a path prefix. authorities lists the CA public keys, for TrustedUserCAKeys on servers or @cert-authority lines in known_hosts.

GET /revoked.krl returns the KRL (OpenSSH key revocation list) for RevokedKeys and RevokedHostKeys; see docs/revocation.md.

POST /sign, with header Authorization: Bearer <JWT>:

{ "cert_type": "user", "public_key": "ssh-ed25519 AAAA... comment" }

Optional requested values: validity (seconds), principals (list), extensions and critical_options (maps of name → value), app_name, comment, and ca_signature_algorithms (list).

Response on success (200):

{ "certificate": "ssh-ed25519-cert-v01@openssh.com AAAA..." }
Status Meaning
400 Request body is not a valid OpenSSH public key
401 Token missing or invalid (WWW-Authenticate: Bearer error=...)
403 No profile matched, request outside the policy limits, or no principals
500 CA from the profile is not configured, or signing failed

Error bodies are { "error": "<message>" }. A 401 has no body; the reason is in the WWW-Authenticate header.

Token validation

The token must be a JWT signed by a key in the IdP's JWKS. It must contain exp, iss and aud. iss must equal oidc_provider.issuer, and aud must contain one of oidc_provider.audience (default: the client_id, which is what ID tokens carry). nbf is checked when present.

Machine identities (client credentials, GitHub Actions, Google and Azure workload identity, Kubernetes) can come from further issuers, [issuers.<name>], each with its own required audience. Only profile selectors that name such an issuer match its tokens.

Host certificates

Profiles with cert_types = ["host"] issue host certificates: to hosts signing in as machines (names from their token's claims), to administrators, or to an orchestrator that signs for the hosts it manages (names requested, limited by matching_principals). The client's host command renews a machine's certificates from a timer, and ca-keys prints the @cert-authority lines for known_hosts. See docs/hosts.md.

Trusting the authorities

The discovery document carries a signed trust statement: the CA keys, signed by the authorities themselves (automatic) or by offline trust keys, e.g. 2 of 3 YubiKeys. The client pins it (trust pin); ca-keys and krl then only accept a changed set of CAs, or a KRL, that the pinned keys signed. Authorities can be retired for rotation and carry a known_hosts_pattern. See docs/trust.md.

Weak keys

The service refuses keys whose private key may be known or computable: ROCA (Infineon) and Fermat-factorable RSA keys, broken RSA parameters, invalid or low-order curve points, keys on configured blocklists (e.g. Debian's OpenSSL keys), and optionally one key certified for several owners. The same checks apply to the CA keys at startup. See docs/key-checks.md.

Revocation

Revoked certificates (by serial or key ID) and keys (by fingerprint) are listed in a revocation file, which the service reloads when it changes. It serves them as a KRL, refuses to sign revoked keys, and the client's krl command keeps /etc/ssh/revoked.krl up to date from a timer.

With optional shared storage ([store]: a directory, S3, GCS or Azure Blob), there is also a revocation API: key holders revoke their keys by proving possession, users revoke their own certificates (from any device), and administrators revoke anything, including everything a search of the issuance index matches (every issued certificate is recorded there). See docs/revocation.md.

CA key backends

CA keys can be in a file, on a PKCS#11 token (YubiKey, smart card, HSM), in OpenBao/Vault's transit engine, in Azure Key Vault, in AWS KMS, in Google Cloud KMS or in OpenStack Barbican. Each backend is a Cargo feature (ca-file, ca-pkcs11, ca-vault, ca-azure-keyvault, ca-aws-kms, ca-gcp-kms, ca-barbican), so builds only contain what their platform needs. See docs/backends.md.

Behind a proxy or CDN

The service needs no public URL setting (the discovery document's sign endpoint is relative, so path prefixes work). For the client address in the audit log, set client_address_header and trusted_proxies; Cloudflare's CF-Ray can be recorded as a correlation ID. See docs/audit.md for Cloudflare (proxy or tunnel) and nginx examples.

Serverless

The service runs as an ordinary HTTP server, so serverless platforms only need the right port and configuration source:

  • Listen address: SSH_CASIGN_LISTEN, else FUNCTIONS_CUSTOMHANDLER_PORT (Azure Functions, loopback), else PORT (on 0.0.0.0), else listen from the config.

  • Configuration: SSH_CASIGN_CONFIG_TOML (the whole file's content), else the file.

  • Audit: the stdout sink; the service's own log goes to stderr.

  • Azure Functions: deploy/azure-functions (custom handler).

  • AWS Lambda: deploy/aws-lambda (container image with the Lambda Web Adapter).

  • Google Cloud Run: deploy/gcp-cloud-run (container image on distroless; Cloud Run functions can't run Rust binaries).

deploy/build-static.sh builds the static Linux binaries (musl, rustls) for these, for x86-64 or arm64, in a rust container: natively with musl-gcc when the target is the build machine's architecture, otherwise cross-compiled with cargo-zigbuild (Zig provides the C compiler and linker; it is downloaded once and checked against its published SHA-256). BUILD_METHOD=native|zig overrides the choice.

Signature algorithms

A certificate carries one CA signature, so what a server can verify depends on the signature algorithm. A profile therefore lists one or more authorities (ssh_ca), and every authority offers the signature algorithms its key supports:

CA key Algorithms offered by default Also possible
Ed25519 ssh-ed25519
ECDSA ecdsa-sha2-nistp256 (/384/521)
RSA rsa-sha2-512, rsa-sha2-256 ssh-rsa (SHA-1), only if listed

The client may say which algorithms its target servers accept (--ca-signature-algorithm, or ca_signature_algorithms in a client profile). The service takes the first authority in the profile's order that offers one of them, using that authority's preferred algorithm among the accepted ones. Without a list, the first authority and its first algorithm are used. If nothing matches, the request is refused with a list of what is available. Discovery lists each authority's algorithms.

ssh-rsa (RSA with SHA-1) is for systems that will never support anything else, such as older switches. OpenSSH refuses it by default since 8.2. Enable it with signature_algorithms = ["ssh-rsa"] on an authority. To keep it away from other profiles, configure the same key file a second time as a separate authority with only ssh-rsa, and list that authority only in the profiles that need it.

Such old systems usually also need an RSA user key (use login -k with an RSA key, or cert), and modern OpenSSH clients only offer RSA certificates with SHA-1 when told to, e.g. in ~/.ssh/config for those hosts:

Host switch-*
    PubkeyAcceptedAlgorithms +ssh-rsa-cert-v01@openssh.com
    HostKeyAlgorithms +ssh-rsa

Ordering also handles CA rotation: list the new authority first and keep the old one until every server trusts the new key.

Servers verify the CA signature against TrustedUserCAKeys, so every authority a profile can select must be trusted by the servers its users log into.

Certificate policy

Each value (validity, principals, extensions, critical options, comment) is taken from the client's request, else the token's claims, else the profile. The token and the profile can both set limits (min_*/max_*, required_*/allowed_*, matching_*), and both always apply. A request that breaks a limit is rejected; defaults are fitted to the limits. See docs/policy.md for the full rules.

Key ID

The service builds the key ID from the profile's key_id template. The default is {{server_id}}:{{profile}}:{{oidc_id}}:{{app_name}}, for example ca1:ops:alice@example.com:ansible. It records which service instance issued the certificate, under which profile, for which IdP identity, and for which client workload. See docs/policy.md.

Audit log

Every issued certificate and every denied request of an authenticated client is recorded in Common Event Format (CEF), to a file, stdout (for AWS Lambda, Azure Functions, GCP), and/or syslog (local socket, TCP or UDP). A certificate is only returned once its record has been written. See docs/audit.md.

Configuration

The service reads the file named by its first argument, or by SSH_CASIGN_CONFIG, or ./config.toml. Unknown keys are an error. Set log verbosity with RUST_LOG (default info).

server_id = "ca1"                            # in key IDs; default: hostname
listen = "0.0.0.0:3000"                      # default

[oidc_provider]
issuer = "https://idp.example.com/realms/ssh" # must equal the tokens' `iss`
client_id = "ssh-casign"                      # public client the CLI signs in as
scopes = ["openid", "profile"]                # default ["openid"]
# audience = ["ssh-casign"]                   # accepted `aud`; default [client_id]
id_claim = "sub"                              # unique, traceable ID for the key ID

# Profile selectors: the first match wins. A selector matches when the claim is
# a string equal to `value` or an array that contains `value`.
[[profiles.map]]
name = "ops"                   # used in the key ID; default "roles=ops"
claim = "roles"
value = "ops"
settings = { ssh_ca = "ed25519", validity = 3600, max_validity = 86400 }

# Used when no selector matches. Without it, unmatched users get a 403.
# Any key from docs/policy.md can be used here (defaults and limits).
[profiles.default]
ssh_ca = ["ed25519", "rsa"]    # authorities, in order of preference (or one name)
# key_id = "{{server_id}}:{{profile}}:{{oidc_id}}:{{app_name}}"   # default
validity = 300                 # default, unless the client or token says otherwise
max_validity = 28800
comment = "default profile"
matching_principals = "[a-z][a-z0-9_-]*"
required_extensions = ["permit-pty"]

# Named signing authorities, referenced by `ssh_ca` in a profile. The provider is
# the key backend: file, pkcs11 or vault (see docs/backends.md).
[authorities.ed25519]
provider = "file"              # OpenSSH private key on disk
private_key_file = "ssh-ca"
cert_types = ["user"]          # "user" and/or "host"

[authorities.rsa]
provider = "file"
private_key_file = "ssh-ca-rsa"
cert_types = ["user"]
# signature_algorithms = ["rsa-sha2-512", "rsa-sha2-256"]   # default for RSA keys

# Audit log (CEF), see docs/audit.md.
[audit]
[[audit.sink]]
type = "file"
path = "/var/log/ssh-casign/audit.cef"

The service logs to stderr; stdout is reserved for the audit log's stdout sink.

Client

ssh-casign-client [OPTIONS] login [-k KEY] [--new] [--min-remaining DURATION] [REQUEST OPTIONS]
ssh-casign-client [OPTIONS] logout [--keep-agent]
ssh-casign-client [OPTIONS] cert [-t user|host] [-o FILE] [REQUEST OPTIONS] [PUBLIC_KEY_FILE]
ssh-casign-client [OPTIONS] host [-n NAME] [--renew-before DURATION] [--on-change CMD] [KEY.pub ...]
ssh-casign-client [OPTIONS] ca-keys [-t user|host] [--hosts PATTERN] [-o FILE] [--on-change CMD]
ssh-casign-client [OPTIONS] krl -o FILE [--on-change CMD]
ssh-casign-client [OPTIONS] trust pin|show|statement|sign|verify
ssh-casign-client [OPTIONS] revoke --key FILE | --all | --serial N --authority A | --where FIELD=VALUE ...
ssh-casign-client [OPTIONS] certificates [--where FIELD=VALUE]

trust pins the service's signed trust statement and signs statements offline (docs/trust.md). krl fetches the revocation list (docs/revocation.md). host and ca-keys are described in docs/hosts.md, together with the non-interactive sign-in methods for machines (client-credentials, token-file, gcp-metadata, azure-managed-identity, github-actions).

login signs in and loads a certificate into ssh-agent ($SSH_AUTH_SOCK). The agent forgets the key when the certificate expires, so there is nothing to clean up:

  • Without -k, a new Ed25519 key is generated in memory and added to the agent with its certificate. The private key never touches the disk.
  • With -k ~/.ssh/id_ed25519, the existing key is used: id_ed25519.pub is signed, the certificate is written to id_ed25519-cert.pub, and ssh-add -t <lifetime> loads both (and asks for the passphrase if the key has one).
$ ssh-casign-client login -I laptop
Added certificate to ssh-agent
  key ID:     ca1:default:alice@example.com:laptop
  principals: alice
  expires in: 1h00m

$ ssh-casign-client login -I laptop        # again: no sign-in needed
Reusing certificate in ssh-agent
  ...

login reuses a still-valid certificate instead of signing in again when:

  • it was signed by one of the service's authorities (from the discovery document);
  • it has at least --min-remaining left (default: 5 minutes, or half the certificate's validity if that is shorter);
  • the request is plain: no -V, -n, --extension, --critical-option or -C (those always get a new certificate);
  • without -k: it was added by login for the same application name (-I). The agent comment records it: ssh-casign:<app_name> <key_id>.
  • with -k KEY: KEY-cert.pub is used. If the agent no longer holds it, it is loaded again with ssh-add, still without signing in.

--new always signs in. When login adds a new in-memory key, it removes the keys it added earlier for the same application name, so the agent doesn't collect keys (servers give up after MaxAuthTries attempts).

logout forgets the cached sign-in (see below) and removes the keys login added to the agent for this service; --keep-agent only forgets the sign-in. To sign in as another user, logout first: otherwise the cached sign-in is used.

cert only requests a certificate for a public key and writes it out.

Staying signed in

When the IdP returns a refresh token, the client stores it, and the next cert or login that needs a new certificate uses it instead of the browser or device flow. Rotated refresh tokens replace the stored one. If the IdP rejects the refresh token, or the service rejects the refreshed token, the client forgets it and signs in normally.

Most IdPs only issue refresh tokens for the offline_access scope; add it to oidc_provider.scopes in the service config (or scopes in a client profile).

token_store Where
keyring OS credential store: macOS Keychain, Windows Credential Manager, Linux kernel keyring (until logout or reboot)
file refresh-tokens.json in the cache directory, readable only by the user
none not stored; every new certificate needs a sign-in

Tokens are stored per IdP issuer and client ID, so profiles on the same IdP share the sign-in. Set token_store at the top of the client config or per profile.

Platforms

The client runs on Linux, macOS and Windows. On Windows, login talks to the OpenSSH agent's named pipe (\\.\pipe\openssh-ssh-agent, or the pipe in SSH_AUTH_SOCK), and the browser is opened through the shell's URL handler. TLS uses each platform's own TLS stack and certificate store, so internal CAs that the OS trusts work.

Request options; anything not requested falls back to the token's and then the profile's defaults:

Option Requests
-V, --validity DURATION validity: 300, 30m, 8h, 1d, 1h30m
-n, --principal NAME[,NAME] principals (repeatable)
--extension NAME[=VALUE] extensions, replacing the defaults (repeatable)
--no-extensions no extensions (required ones are still added)
--critical-option NAME=VALUE critical options, replacing the defaults
--no-critical-options no critical options (except required ones)
-I, --app-name NAME workload name for the key ID (see below)
-C, --comment TEXT comment
--ca-signature-algorithm ALG CA signature algorithms the servers accept

Global options:

Option Environment Meaning
-f, --config-file SSH_CASIGN_CONFIG Config file
-p, --profile SSH_CASIGN_PROFILE Profile from the config file
-u, --url SSH_CASIGN_URL Service base URL; overrides the profile's URL
--sign-in SSH_CASIGN_SIGN_IN device, authorization-code (browser), …
--token-store SSH_CASIGN_TOKEN_STORE keyring (default), file or none
SSH_CASIGN_CACHE_DIR Directory for the file token store
SSH_CASIGN_TOKEN Use this bearer token, skip sign-in (testing)
SSH_CASIGN_CLIENT_SECRET Client secret for client-credentials
RUST_LOG Log verbosity (default warn)

--sign-in also takes the machine methods from docs/hosts.md.

cert reads the public key from PUBLIC_KEY_FILE, or from stdin when that is omitted or -. It writes the certificate to -o FILE. Without -o, it follows OpenSSH's naming convention (id_ed25519.pub → id_ed25519-cert.pub), or writes to stdout when the key came from stdin.

Configuration

The default config file is <config dir>/ssh-casign-client/config.toml. On macOS that is ~/Library/Application Support/ssh-casign-client/config.toml. The file is optional when --url is given.

default_profile = "default"    # default
sign_in = "device"             # default for all profiles; "device" if omitted
app_name = "laptop"            # default for all profiles; "ssh-casign-client" if omitted
token_store = "keyring"        # where refresh tokens are kept: keyring, file or none

[profiles.default]
url = "https://ssh-ca.example.com/"

[profiles.workstation]
url = "https://ssh-ca.example.com/"
sign_in = "authorization-code"   # this profile prefers the browser
app_name = "workstation"
# client_id = "..."              # override what the service publishes
# scopes = ["openid", "groups"]

The application name (-I) goes into the certificate's key ID, so concurrent workloads (ssh, ansible, terraform, vs code, ...) can be told apart. It is chosen in this order: --app-name / SSH_CASIGN_APP_NAME, then the profile's app_name, then the top-level app_name, then ssh-casign-client.

  • device: the client prints a URL and a code on stderr. Open the URL on any device, enter the code and sign in; the client continues once the sign-in is approved.
  • authorization-code (browser): the client opens the IdP's sign-in page in a browser on this machine ($BROWSER, else open/xdg-open) and also prints the URL. It uses PKCE and receives the code on http://localhost:<random port>/callback, listening on both 127.0.0.1 and [::1]. Register the client at the IdP as a public client that allows loopback redirects. The client waits up to five minutes.

Both send the ID token to the service when the IdP returns one, otherwise the access token.

The sign-in method is chosen in this order: --sign-in / SSH_CASIGN_SIGN_IN, then the profile's sign_in, then the top-level sign_in, then device. The client checks that the IdP advertises the endpoint for the chosen method, and otherwise suggests the other one.

Testing

ci/check.sh                       # fmt, clippy (all feature combinations), unit tests, Windows build
tests/e2e/run.sh                  # end-to-end: service, client, sshd, IdPs, emulators (podman)
tests/e2e/run.sh login hosts      # selected scenarios
tests/e2e/run.sh --tier packages  # the serverless images and podman secrets (on the host)

The end-to-end suite runs the real service and client against Dex, a mock IdP, OpenBao, LocalStack, Azurite, fake-gcs-server, Lowkey Vault, SoftHSM and sshd, each in a container on one network. The same scripts run in Woodpecker CI (.woodpecker/), with the dependencies as services; ci/woodpecker-local.sh runs those workflows on the local podman, without a Woodpecker server. See tests/e2e/README.md.

About

SSH CA signing based on Open ID Connect authorizations

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages