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-agentloading andsshdlogin work end to end against Dex. See docs/status.md.
| 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.
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)
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.
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.
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.
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.
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.
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 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.
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.
The service runs as an ordinary HTTP server, so serverless platforms only need the right port and configuration source:
-
Listen address:
SSH_CASIGN_LISTEN, elseFUNCTIONS_CUSTOMHANDLER_PORT(Azure Functions, loopback), elsePORT(on0.0.0.0), elselistenfrom the config. -
Configuration:
SSH_CASIGN_CONFIG_TOML(the whole file's content), else the file. -
Audit: the
stdoutsink; 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.
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.
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.
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.
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.
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.
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.pubis signed, the certificate is written toid_ed25519-cert.pub, andssh-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-remainingleft (default: 5 minutes, or half the certificate's validity if that is shorter); - the request is plain: no
-V,-n,--extension,--critical-optionor-C(those always get a new certificate); - without
-k: it was added byloginfor the same application name (-I). The agent comment records it:ssh-casign:<app_name> <key_id>. - with
-k KEY:KEY-cert.pubis used. If the agent no longer holds it, it is loaded again withssh-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.
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.
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.
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, elseopen/xdg-open) and also prints the URL. It uses PKCE and receives the code onhttp://localhost:<random port>/callback, listening on both127.0.0.1and[::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.
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.