@andrewheberle/serverless-ssh-ca
v1.0.1
Published
A serverless SSH CA built for Cloudflare Workers that can also run on Node.js
Readme
@andrewheberle/serverless-ssh-ca
This is the package that implements the SSH CA functionality which can be deployed to Cloudflare as a working solution using the "Deploy to Cloudflare" button below:
To use the package in your own Worker manually (assuming you have the required
bindings in place), the following code in src/index.ts (your Worker's main
file) will work:
import app from "@andrewheberle/serverless-ssh-ca"
export default appThis package is built for Cloudflare Workers and can also run on Node.js 24 (see Running on Node.js). These are the only runtimes it is tested on, see Supported Platforms for the versions supported and what is best effort.
The package doesn't use any Workers-specific APIs and doesn't depend on
@cloudflare/workers-types. It needs:
- Web standard APIs (
Request,Responseand WebCrypto) - Node.js compatibility (
nodejs_compaton Workers), becausesshpkuses Node APIs - A database binding compatible with Cloudflare D1
- A secret binding with an async
get()method that returns the CA private key
Its exported types describe only these needs, so the Env generated by
wrangler types (with DB as a D1Database and PRIVATE_KEY as a
SecretsStoreSecret) can be passed directly as SshCaBindings.
Upgrading from a 0.x release? See Upgrading to 1.0 before you do: API v3 is removed, and some configurations 0.x accepted are refused.
Running on Node.js
Node.js 24 or later is required. Helpers for Node.js are imported from
@andrewheberle/serverless-ssh-ca/node:
| Helper | Purpose |
|---|---|
| fromNodeSqlite(db) | Uses a built-in node:sqlite database as the DB binding |
| secretFromFile(path) | Reads the CA private key from a file (re-read each time it is needed) |
| secretFromString(value) | Uses a string as the CA private key |
| cacheInMemory() | Uses an in-memory cache as the optional CACHE binding (see KRL Caching) |
| bindingsFromEnv({ DB, PRIVATE_KEY }) | Reads and validates the remaining configuration from process.env |
createSshCa(bindings) returns a fetch(request) handler that takes a
standard Request and returns a Response, and a cleanup() task that
replaces the Workers cron trigger.
The handler can be served by any server that works with Request and
Response. For example, with @hono/node-server
(installed separately with npm install @hono/node-server):
import { DatabaseSync } from "node:sqlite"
import { serve } from "@hono/node-server"
import { createSshCa } from "@andrewheberle/serverless-ssh-ca"
import { bindingsFromEnv, fromNodeSqlite, secretFromFile } from "@andrewheberle/serverless-ssh-ca/node"
const ca = createSshCa(bindingsFromEnv({
DB: fromNodeSqlite(new DatabaseSync("/var/lib/ssh-ca/ssh-ca.sqlite")),
PRIVATE_KEY: secretFromFile("/etc/ssh-ca/ca_key"),
}))
// remove expired certificates once a day
setInterval(() => void ca.cleanup(), 24 * 60 * 60 * 1000)
serve({ fetch: (req) => ca.fetch(req), port: 8787 })Notes:
- The configuration environment variables have the same names and formats
as the
varsin the Workerswrangler.jsonc.bindingsFromEnvvalidates them at start up with the same rules ascreateSshCaand the Workers default export (see Validation), and throws anInvalidConfigurationErrorthat lists every missing or invalid variable. It returns only the variables the CA reads, unchanged. - The database schema is created and migrated automatically on first use, as
on Workers (see Database). Use a file path for
DatabaseSync(not:memory:) so issued and revoked certificates survive restarts. - Only SQLite databases are supported. Other SQLite-compatible databases can
be used by implementing the
CaDatabaseinterface. - The CA private key has the same requirements as on Workers (see CA Private Key). Keep the key file readable only by the user running the CA.
cleanup()can also be run on a schedule outside the process (for example from a systemd timer or cron job) instead of usingsetInterval.- Put the CA behind a reverse proxy that terminates TLS, as clients send identity tokens to it.
See the following repositories for additional information:
| Repository | Details | |---|---| | https://github.com/andrewheberle/ssh-ca-client | Contains client code for issuing user and host certificates | | template/ | The Worker the "Deploy to Cloudflare" button deploys, which pins the CA to the latest release |
Architecture
The solution comprises of the CA running as a Worker, a Go based client (found here) and a third party OIDC IdP.
The IdP may be any OIDC compatible service that issues identity tokens as
JWTs, and access tokens that are either JWTs with an email claim or
accepted by its userinfo endpoint (see
Opaque Access Tokens). At this time only Cloudflare
Access has been tested.
User Certificates
The flow to obtain a User SSH certificate using the CLI version is as follows:
- The user initiates
ssh-ca-client-cli login - If required a new SSH key is generated and a browser is opened to
visit
http://localhost:3000/auth/login - The client redirects the user to the configured IdP
- The IdP returns the user to the callback URL (default
http://localhost:3000/auth/callback) - The client sends the access token from the IdP as
Authorization: Bearer <TOKEN>in aPOSTrequest to the CA's/api/v4/user/certificatesendpoint, with the user's SSH public key, the identity token, and a proof of possession of the key in theProof-Of-Possessionheader - The CA verifies both tokens and the proof of possession and, if they are valid, responds with a signed certificate for the provided public key
- The client saves the certificate and adds the SSH private key and certificate to the local SSH Agent.
This flow is shown below once the user executes ssh-ca-client-cli login:
sequenceDiagram
User->>Client: GET /auth/login
activate Client
Client-->>User: Redirect to IdP
deactivate Client
activate User
User->>IdP: OIDC authentication flow
deactivate User
activate IdP
IdP-->>User: Redirect to Client
deactivate IdP
activate User
User->>Client: Completes OIDC redirect
deactivate User
activate Client
activate Client
Client-->>User: Auth flow completed
deactivate Client
Client->>CA: POST /api/v4/user/certificates
deactivate Client
activate CA
CA-->>Client: Signed certificate
deactivate CA
activate Client
Client->>SSH Agent: Add key and certificate to Agent
deactivate ClientIf a refresh token is available, the process looks like this when running
ssh-ca-client-cli login:
sequenceDiagram
Client->>IdP: Request access and identity tokens
activate IdP
IdP-->>Client: Token returned
deactivate IdP
activate Client
Client->>CA: POST /api/v4/user/certificates
deactivate Client
activate CA
CA-->>Client: Signed certificate
deactivate CA
activate Client
Client->>SSH Agent: Add key and certificate to Agent
deactivate ClientIf refreshing the tokens with the refresh token fails, the standard authentication process is followed which requires user interaction.
The principals of a user certificate come from the identity token's
JWT_SSH_CERTIFICATE_PRINCIPALS_CLAIM (with spaces replaced by underscores),
SSH_CERTIFICATE_PRINCIPALS and the SSH_CERTIFICATE_INCLUDE_SELF* settings.
A request is refused with a 422 error if there are none, or if any of them
is empty or contains a
comma, whitespace, a control character or an OpenSSH pattern character (*,
? or !). A server that restricts certificates with the principals="..."
option in authorized_keys reads that option as a comma separated list, so,
depending on how it matches them, a principal such as alice,root might
otherwise be accepted for an account it was not meant for.
Host Certificates
Initial Request
The process to request an initial Host certificate is similar to obtaining
a User certificate once ssh-ca-client-cli host is run, however instead of
adding the obtained certificate to a SSH Agent, it is written to
<KEYPATH>-cert.pub instead:
sequenceDiagram
User->>Client: GET /auth/login
activate Client
Client-->>User: Redirect to IdP
deactivate Client
activate User
User->>IdP: OIDC authentication flow
deactivate User
activate IdP
IdP-->>User: Redirect to Client
deactivate IdP
activate User
User->>Client: Completes OIDC redirect
deactivate User
activate Client
activate Client
Client-->>User: Auth flow completed
deactivate Client
Client->>CA: POST /api/v4/host/certificates
deactivate Client
activate CA
CA-->>Client: Signed certificate
deactivate CA
activate Client
Client->>Writes Certificate: Certificate written to disk
deactivate ClientHost certificate principals may be IP addresses, bare host names or fully
qualified domain names. As OpenSSH matches the principals of a host
certificate as patterns, principals containing wildcard or pattern characters
(*, ?, ! or ,), whitespace or control characters are refused, as a
principal such as * would make the certificate valid for every host.
Renewals
Renewals are done using the existing certificate and will succeed if:
- The certificate is not expired
- It was issued by the CA
- The public key used to obtain the certificate is the same as the one currently presented
- It has not been revoked, or already renewed
The certificate that was renewed is revoked and added to the host KRL, so it
cannot be used to renew again, and SSH clients that check the host KRL will no
longer accept it. From OpenSSH 9.8, sshd only reads host certificates when
it starts or is reloaded, so it must be reloaded to present the renewed
certificate once it has been written to disk; until then it keeps presenting
the revoked one. OpenSSH 9.7 and earlier read the certificate for each
connection, so present the renewed certificate without a reload. The client's
host --renew --reload-command option reloads sshd only when a certificate
was renewed.
This means the OIDC authentication flow is not required in this case as shown
below when ssh-ca-client-cli host --renew is run:
sequenceDiagram
Client->>CA: POST /api/v4/host/certificates/{serial}/renew
activate CA
CA-->>Client: Signed certificate
deactivate CA
activate Client
Client->>Writes Certificate: Certificate written to disk
deactivate ClientAPI
The CA's API is documented in OpenAPI format at /docs and in
openapi.json:
| Action | Endpoint |
|--------------------------|-------------------------------------------------|
| Get the CA public key | GET /api/v4/ca |
| Request user certificate | POST /api/v4/user/certificates |
| Revoke user certificate | DELETE /api/v4/user/certificates/{serial} |
| Get user KRL | GET /api/v4/user/krl |
| Request host certificate | POST /api/v4/host/certificates |
| Renew host certificate | POST /api/v4/host/certificates/{serial}/renew |
| Revoke host certificate | DELETE /api/v4/host/certificates/{serial} |
| Get host KRL | GET /api/v4/host/krl |
API v3 was removed in 1.0.0, because its proofs of possession were not bound
to the request they were sent with (see
ADR 0006).
Every request under /api/v3 is answered with 410 Gone, so clients must be
ssh-ca-client 0.24.0 or later.
Certificates are issued for Ed25519, ECDSA and RSA keys. RSA keys must be at
least 2048 bits; a request for a smaller key is refused with a 400 error,
and a certificate for a smaller key cannot be renewed. Certificates for
smaller keys can still be revoked.
Proof of Possession
Requests that use an SSH key prove possession of its private key by including
a proof of the form ${timestamp}.${fingerprint}.${signature}, where
timestamp is the time in milliseconds since the Unix epoch, fingerprint is
the SHA256 fingerprint of the public key (for example
SHA256:79mq0wtpQMTvS4+Of8VzLN0qmYWNUyTXYmqKwhEgSLs) and signature is the
BASE64 encoded armored SSHSIG signature (as produced by ssh-keygen -Y sign)
of the signed data. The proof is rejected if the timestamp is outside of
CERTIFICATE_REQUEST_TIME_SKEW_MAX of the time on the CA.
The proof is sent in the Proof-Of-Possession header and is bound to the
request it is made for. The signed data is
${timestamp}.${fingerprint}.${METHOD} ${path} using the
request-proof-of-possession@com.github.serverless-ssh-ca.andrewheberle
namespace, where ${METHOD} ${path} is the request as documented in the
OpenAPI schema with any parameters filled in, for example:
1765696780805.SHA256:79mq0wtpQMTvS4+Of8VzLN0qmYWNUyTXYmqKwhEgSLs.DELETE /api/v4/user/certificates/12345678901234567890Only ${timestamp}.${fingerprint}.${signature} is sent, as the CA rebuilds
the request part from the request it receives. The path does not change if
the CA is served behind a proxy under another path, and serials in the path
are written in decimal without leading zeros.
The timestamp is written in decimal without a sign or leading zeros, and the signature is standard base64 with padding. A proof in any other form is refused.
The public key for a revocation or renewal is taken from the proof and the certificate respectively, so it is not sent separately.
Configuration
Validation
The configuration is validated on every runtime before the CA serves anything with it:
| Setting | Accepted values |
|---|---|
| CERTIFICATE_REQUEST_TIME_SKEW_MAX | A positive duration of at most 5 minutes, such as "90 seconds". A proof of possession is accepted this long either side of the CA's clock |
| SSH_CERTIFICATE_LIFETIME | A duration of at least 5 minutes, in whole seconds, such as "24 hours". The longest lifetime of a user certificate |
| SSH_HOST_CERTIFICATE_LIFETIME | A duration of at least 24 hours, in whole seconds, such as "30 days". The longest lifetime of a host certificate |
| DB_CERTIFICATE_RETENTION | "infinite", or a positive period such as "1 year" or "90 days" |
| JWT_ISSUER, ISSUER_DN, JWT_SSH_CERTIFICATE_PRINCIPALS_CLAIM | Must be set |
| JWT_AUD | A list with at least one audience. Must be set |
| JWT_ALGORITHMS | A list with at least one of RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, EdDSA or Ed25519. Symmetric algorithms and none are refused, as the keys come from a public JWKS |
| JWT_JWKS_URL | An https URL, or an http URL for localhost, 127.0.0.0/8 or [::1] (such as a test identity provider) |
| OIDC_USERINFO_URL | As JWT_JWKS_URL, or unset (an empty string is treated as unset) |
| JWT_ACCESS_TOKEN_AUD, SSH_HOST_CERTIFICATE_ALLOWED_EMAILS, SSH_HOST_CERTIFICATE_ALLOWED_ROLES | A list, or unset (an empty string is an empty list) |
| SSH_CERTIFICATE_EXTENSIONS | A list of extension names, each without whitespace, or unset. These are the extensions user certificates get by default and the only ones a requester may ask for; when unset, user certificates have no extensions (so no permit-pty) |
| SSH_CERTIFICATE_PRINCIPALS | A list of principals, each of which contains no whitespace, control characters or *, ?, !, or unset |
| SSH_CERTIFICATE_INCLUDE_SELF, SSH_CERTIFICATE_INCLUDE_SELF_EMAIL | "true" or "false" (or a boolean), or unset |
| LOG_LEVEL | none, error, warning, info or debug, or unset |
| LANDING_PAGE | "true" or "false" (or a boolean), or unset. See Landing Page |
| ADMIN_* | See Admin UI. Each may be unset, but must be valid when set |
A list is a comma separated string, or an array of strings where bindings
can be arrays. Each entry is trimmed, so "a, b" is the same as "a,b", and
an empty entry, such as in "a,,b" or "a,", is refused.
SSH_HOST_CERTIFICATE_ALLOWED_EMAILS is compared with the requester's email
address case-insensitively. SSH_HOST_CERTIFICATE_ALLOWED_ROLES is compared
exactly with the values of the JWT_SSH_CERTIFICATE_PRINCIPALS_CLAIM claim of
the identity token. Spaces are replaced with underscores in both, so a group
ops team is allowed by the role ops team or ops_team.
A duration is a number and one of the units second, minute, hour,
day, week, month or year (singular or plural), separated by a space. A
unit is required, so a bare number or an abbreviation such as "90 secs" is
refused. A retention period uses the same format without week, as it is
passed to SQLite as a date modifier.
How an invalid configuration is reported depends on the runtime:
- On Cloudflare Workers the default export logs the problems once, at error
level, and then answers every request with a
500error whose body does not describe the configuration. The scheduled database cleanup is skipped until the configuration is fixed. createSshCathrows anInvalidConfigurationErrorlisting every missing or invalid setting, as doesbindingsFromEnvon Node.js. The error is exported from both@andrewheberle/serverless-ssh-caand@andrewheberle/serverless-ssh-ca/node.
The scheduled cleanup removes certificates that expired longer ago than
DB_CERTIFICATE_RETENTION. A revoked certificate stays in the KRL until 24
hours after it expires, so it is not removed before then, however short the
retention period is.
Database
The CA keeps the certificates it has issued, and the version of each KRL, in
a SQLite database: D1 on Cloudflare Workers, or node:sqlite (or another
CaDatabase) on Node.js. The CA's tables are created in the database on first use, and after an
upgrade any new migrations are applied automatically the first time the
database is used. Upgrading from any earlier release migrates the database,
as migrations are never removed.
The schema is internal to the CA and can change in any release, including a minor or patch release, so it is not part of what semver covers. Reading the tables, writing to them or adding your own tables, indexes or views is not supported, and may break on any upgrade. Use the admin UI and the API instead.
Running an older release against a database that a newer release has migrated is not supported. To roll back after an upgrade, restore a backup of the database taken before it, such as a D1 Time Travel restore point or a copy of the SQLite file, along with the older release.
CA Private Key
The CA private key is read from the PRIVATE_KEY Secrets Store binding and
must be an unencrypted Ed25519 or ECDSA (nistp256, nistp384 or
nistp521) key in OpenSSH format, which is what ssh-keygen creates by
default:
ssh-keygen -t ed25519 -N "" -C "" -f ssh-caUnencrypted keys in PKCS#8 format (starting with -----BEGIN PRIVATE KEY-----),
such as those created by ssh-keygen -m PKCS8 or openssl genpkey, are also
accepted.
RSA CA keys are not supported. With an RSA CA key
configured, every request that uses the CA key (including /api/v4/ca and
the KRL endpoints) returns a 500 error, and the reason is logged:
CA key type rsa is not supported, the CA key must be Ed25519 or ECDSAIdentity Provider
This example shows the configuration in Cloudflare Access, however other OIDC IdP's should be generally equivalent:

The Redirect URL must match the configured value in the client.
Transfer the IdP settings as follows:

Copy the Client ID to JWT_AUD on the CA and to client_id in the
client, the Issuer to JWT_ISSUER on the CA and to issuer in the
client, and the Key endpoint to JWT_JWKS_URL on the CA.
The openid and email scopes are required, with enabling of refresh tokens
(the offline_access scope) being optional, but recommended.
JWT_AUD must be set to the audience the IdP issues tokens for this
application with (for Cloudflare Access, the application's client ID). Both
the access token and the identity token must be issued for this audience, so
tokens the IdP issues for other applications are not accepted. If the IdP
issues access tokens with a different audience to identity tokens, set
JWT_ACCESS_TOKEN_AUD to the audience of the access token. Either value may
be a comma separated list. JWT_AUD must be set (see Validation).
When JWT_ACCESS_TOKEN_AUD is not set, both tokens are checked against the
same audience, issuer and keys, so the access token adds little beyond the
identity token. The CA refuses a request whose access token is the identity
token itself, so a single leaked identity token is not enough, but where the
IdP can issue access tokens with their own audience, setting
JWT_ACCESS_TOKEN_AUD keeps the two tokens apart.
Cloudflare Access issues access tokens for the client's redirect URL (for
example http://localhost:3000/auth/callback), so set JWT_ACCESS_TOKEN_AUD
to it. This is safe because the issuer of an Access application includes its
client ID, so tokens for other applications fail the JWT_ISSUER check. With
IdPs where every application shares an issuer, JWT_ACCESS_TOKEN_AUD must be
an audience that only tokens for this application are issued for.
Opaque Access Tokens
Some IdPs (such as Google) issue access tokens that are not JWTs, so they
cannot be verified by the CA itself. For these IdPs set OIDC_USERINFO_URL to
the IdP's OIDC userinfo endpoint (the userinfo_endpoint of its
/.well-known/openid-configuration). Every access token is then sent to this
endpoint, which returns the claims of the user the token was issued to,
instead of being verified as a JWT, and JWT_ACCESS_TOKEN_AUD is not used.
The userinfo endpoint does not say which application an access token was
issued to, so with this method an access token is bound to the CA only by its
sub claim matching that of the identity token, which is still verified as a
JWT issued for JWT_AUD. Each certificate request makes a request to the
userinfo endpoint. A token the endpoint does not accept is refused with a
400 error, and if the endpoint cannot be reached or does not respond with a
JSON object the request fails with a 500 error and the cause is logged.
The email claim of the access token (or of the userinfo response) must be an
email address. It is used as
the key ID of user certificates, and with SSH_CERTIFICATE_INCLUDE_SELF its
local part (before the @) is added as a principal. If the IdP includes the
email_verified claim it must be true, so tokens for an address the IdP has
not verified are refused.
As the local part does not include the domain, [email protected] and
[email protected] are given the same principal with
SSH_CERTIFICATE_INCLUDE_SELF. Only enable it when the IdP only allows users
from domains you control.
Rate Limiting
Requests to issue, renew and revoke certificates can be rate limited by
adding a rate limit binding
named RATE_LIMITER to wrangler.jsonc:
"ratelimits": [
{
"name": "RATE_LIMITER",
"namespace_id": "1001",
"simple": { "limit": 10, "period": 60 }
}
]On Workers, requests are counted by the client IP address in the
CF-Connecting-IP header, which Cloudflare sets, and requests over the limit
receive a 429 response. Requests to get the CA public key and the KRLs are
not limited, as many hosts may fetch them from the same address. When no
RATE_LIMITER binding is configured, requests are not limited. If the rate
limiter fails, the request is allowed and the error is logged, so
certificates can still be issued and revoked.
With createSshCa, for example on Node.js, pass any limiter with the same
shape (a limit({ key }) method returning { success }, see
CaRateLimiter) as RATE_LIMITER. The rateLimitKey option, which chooses
the key requests are counted by, must then be set too, and createSshCa
throws an InvalidConfigurationError without it. Choose a value the client
cannot set itself: a client can send any CF-Connecting-IP, X-Real-IP or
X-Forwarded-For header it likes, so a header can only be trusted when a
proxy you control overwrites or appends to it. Behind a single trusted
reverse proxy that appends the client address to X-Forwarded-For, use the
last entry, as any earlier ones came from the client:
const ca = createSshCa(bindingsFromEnv({
DB: fromNodeSqlite(new DatabaseSync("/var/lib/ssh-ca/ssh-ca.sqlite")),
PRIVATE_KEY: secretFromFile("/etc/ssh-ca/ca_key"),
RATE_LIMITER: myLimiter,
}), {
// the address appended by the one trusted proxy in front of the CA
rateLimitKey: (req) => req.headers.get("X-Forwarded-For")?.split(",").at(-1)?.trim() || undefined,
})When createSshCa runs behind Cloudflare, pass rateLimitKey:
cloudflareClientIp (exported by this package) to count requests as the
Workers default export does.
Requests for which rateLimitKey returns undefined are not limited, and the
first such request is logged as a warning.
Client Addresses
The CA records the client address (the IP address a request came from) of
each request that issues or renews a certificate, and of each request a key
holder revokes a certificate with. A renewal records the same address as the
request address of the new certificate and the revocation address of the
certificate it renewed. Revocations by an admin record no address, as the
admin is recorded by their email. The addresses are shown on the certificate's
page in the admin UI, included as client_address in the log
lines for issuing and revoking certificates, and kept for as long as the
certificate is (see DB_CERTIFICATE_RETENTION).
On Workers, the address is read from the CF-Connecting-IP header, which
Cloudflare sets.
With createSshCa, no address is recorded unless the clientAddress option
is set. It is a function from the request to its address, and the same
warning applies as for rateLimitKey: a client can send any header it likes,
so only read a header that a proxy you control overwrites or appends to.
Behind the single trusted reverse proxy from the example above:
const ca = createSshCa(bindings, {
// the address appended by the one trusted proxy in front of the CA
clientAddress: (req) => req.headers.get("X-Forwarded-For")?.split(",").at(-1)?.trim() || undefined,
})When createSshCa runs behind Cloudflare, pass clientAddress:
cloudflareClientIp to record addresses as the Workers default export does.
Only IPv4 and IPv6 addresses are recorded. A value that is not one is left out, and the first such value is logged as a warning, but the certificate is still issued, renewed or revoked.
KRL Caching
Generating and signing a KRL reads every revoked certificate from the
database, so the KRLs can be cached by adding an optional CACHE binding. On
Workers this is a KV namespace:
"kv_namespaces": [
{
"binding": "CACHE",
"id": "<kv namespace id>"
}
]On Node.js an in-memory cache can be passed to bindingsFromEnv, or any
other cache that implements the CaCache interface:
const ca = createSshCa(bindingsFromEnv({
DB: fromNodeSqlite(new DatabaseSync("/var/lib/ssh-ca/ssh-ca.sqlite")),
PRIVATE_KEY: secretFromFile("/etc/ssh-ca/ca_key"),
CACHE: cacheInMemory(),
}))A cached KRL is never served after it is out of date. Each certificate type has a revision in the database that is incremented whenever a certificate of that type is revoked (including the previous certificate on a host renewal), or when expired certificates are removed. The cache key includes this revision and the fingerprint of the CA key, so a revocation or a new CA key immediately uses a new key rather than relying on cache entries being deleted or the cache being consistent. Entries are left to expire after 7 days.
A KRL keeps the same version and generation date until its contents change, so a regenerated KRL is identical to the one that was cached. If the cache cannot be read or written the KRL is generated as it is without a cache.
Landing Page
The CA can serve a landing page at /, on Workers and with createSshCa,
that shows public information about the CA. It is off unless
LANDING_PAGE is set to "true"; while it is off, / answers with 404.
Like the admin UI, it is not part of the OpenAPI schema.
The page shows:
- the CA public key, its SHA256 fingerprint and a link to
/api/v4/ca; - generic instructions for trusting user certificates on a host
(
TrustedUserCAKeys), trusting host certificates in SSH clients (@cert-authority), and refusing revoked certificates with the KRLs (RevokedKeysandRevokedHostKeys), with the CA's URL and public key filled in; - a pointer to ssh-ca-client for requesting certificates;
- links to the API documentation (
/docs), the user and host KRLs, ssh-ca-client and its releases, and the admin UI.
It shows only what the CA already publishes. In particular it does not show
a configuration for ssh-ca-client: the CA cannot know the client ID or the
redirect URL for certain (JWT_AUD may be a list, or an audience that is not
the client ID), and a page that shows a wrong value is worse than none, so
users are told to get the client's settings from their administrator. It
never shows the identity provider's settings, certificate lifetimes, the
version of the CA or any allowlist.
The link to the admin UI is only shown while the admin UI is turned on (see
Admin UI). It is to /admin, or to
https://<ADMIN_HOSTNAME>/admin when ADMIN_HOSTNAME is set, as the landing
page answers on every host name. Every visitor sees the link, as the CA cannot
tell who is an admin outside /admin.
The page has no client-side JavaScript or forms and loads only its own
stylesheet, and is sent with the same security headers as the admin UI,
except that its Content-Security-Policy allows no scripts. The stylesheet
is served at /style-<hash>.css, named after its content as described in
Stylesheet and script, and as the page is public
it is sent with Cache-Control: public, max-age=31536000, immutable.
The CA's URL in the instructions is the origin the page was requested on. On
Workers this is always the public URL. On Node.js, behind a reverse proxy that
terminates TLS, it is only the public URL if the server builds the Request
from the public URL, otherwise the instructions show http:// and the
internal host name. Links on the page are relative, so they work either way.
Admin UI
The CA can serve an admin UI under /admin, on Workers and with
createSshCa, where admins can see every certificate the CA has issued and
revoke any that are still valid. It is not part of the OpenAPI schema.
Pages
| Path | Page |
|---|---|
| /admin | Redirects to /admin/user/certificates |
| /admin/user/certificates, /admin/host/certificates | The user or host certificates, newest first, 50 at a time |
| /admin/user/certificates/<serial>, /admin/host/certificates/<serial> | Everything recorded about one certificate, and a form to revoke it while it is valid |
| POST /admin/user/certificates/<serial>/revoke, POST /admin/host/certificates/<serial>/revoke | Revokes the certificate, sent by the revoke form |
| /admin/user/certificates/revoke, /admin/host/certificates/revoke | Confirms revoking the valid certificates that match a list's filters, see Revoking several certificates |
| POST /admin/user/certificates/revoke, POST /admin/host/certificates/revoke | Revokes the certificates ticked on that page |
The lists are filtered by query parameters, which the filter form on the page sets, so a filtered view can be bookmarked:
| Parameter | Filter |
|---|---|
| status | valid (the default), expired, revoked or all. A revoked certificate is revoked even once it has expired, and expired only lists certificates that were not revoked |
| principal | Certificates with this principal, matched exactly and case-sensitively against each principal, so root does not find rootless |
| key_id | Certificates whose key ID contains this, case-insensitively, so alice finds [email protected]. % and _ are matched literally |
| serial | The certificate with this serial, in decimal |
| before | Set by the "Next page" link, which keeps the other filters. Pages follow on from the last certificate shown, so they neither skip nor repeat certificates issued while paging |
An invalid parameter gets a 400 page. A serial that does not exist, or is
for the other certificate type, gets a 404 page.
The detail page shows the serial, type, key ID, principals, extensions, validity, status, the SHA256 fingerprint of the certificate's public key, who requested it and the client address it was requested from. For a revoked certificate it also shows when, by whom and why it was revoked, and for a revocation by the key holder the client address it was revoked from. Values that were not recorded, such as the requester of a certificate issued before they were recorded, or the reason for a revocation by the key holder, are shown as "unknown".
Times
Times are recorded in UTC, and the server always renders them in UTC, such
as 2026-11-04 21:10 UTC, to the minute in the lists and to the second on
the detail page.
The admin UI's script then shows them in the browser's time zone, in the same
layout with the UTC offset of each time in place of UTC, such as
2026-11-05 05:10 UTC+8, UTC+5:30, UTC-3:30 or UTC+0. Each time has
its own offset, so the two ends of a certificate's validity can show
different offsets either side of a change to or from daylight saving time.
Hovering over a time shows it the other way.
The header has a Times: Local | UTC switch to show times in UTC instead.
The choice is remembered by the browser (in localStorage, under
admin-time-zone), and times are shown in local time until a choice is made,
or when the browser does not allow it to be remembered.
The script only changes how times are displayed. Without it, times are shown in UTC, the switch is hidden, and everything else works the same. See ADR-0004.
Revoking certificates
The detail page of a valid certificate has a form to revoke it. The admin must give a reason, of 1 to 500 characters once surrounding whitespace is trimmed, and tick a box to confirm. A revoked certificate is added to the KRL for its type, just as when its key holder revokes it, and the detail page then shows when, by whom and why it was revoked. The admin's email is recorded exactly as the proxy's JWT gives it, and the revocation is logged at info level with the serial, type, email and reason.
Revocations are permanent. Nobody can undo one, including an admin. Access is restored by issuing a new certificate.
| Response | When |
|---|---|
| 303 to the detail page | The certificate was revoked |
| 422 with the form again | The reason is missing, empty or too long, or the box was not ticked. Nothing is revoked |
| 422 | The certificate has expired. Expired certificates are no longer trusted, so they are read-only and have no revoke form. A key holder can still revoke one through the API |
| 409 | The certificate was already revoked |
| 404 | There is no certificate of that type with the serial |
Revocations are POST requests, so they must come from the admin UI itself
and are rate limited, as described in the security model.
Whether a certificate has expired or was already revoked is checked again as
it is revoked, so concurrent revocations revoke it once, keeping the first,
and a revocation cannot race with the certificate expiring.
Revoking several certificates
To revoke every valid certificate of a person, such as when they leave,
filter the user certificates by their email as the key ID (user certificates
are issued with the requester's email as their key ID) or by their principal.
A list filtered to Valid certificates by principal or key ID has a
Revoke these certificates… button, which opens a page listing the
matching certificates, newest first, each with a ticked box. The key ID
filter matches any key ID that contains it, so [email protected] also finds
[email protected]: check the list, and untick any certificate that should
not be revoked. A list that is unfiltered, filtered by serial alone, or shows
other statuses has no button, and its filters are refused by the page with a
400.
At most 50 certificates are listed. When more match, the page says so; revoke those shown, then open the page again for the rest.
Only the ticked certificates are sent, with one reason for them all and the confirmation box, so what is revoked is what the admin saw, not whatever matches the filters by then. Each certificate is recorded and logged as if it had been revoked on its own, with the same reason. They are revoked in one transaction, and the KRL revision for the type is incremented once.
| Response | When |
|---|---|
| 200 with what happened to each certificate | The request was valid. Each certificate is shown as revoked, or as already revoked, expired or not found when it changed since the page was shown, and the others are still revoked |
| 422 with the page again | The reason is missing, empty or too long, the box was not ticked, no certificates were ticked, a serial is not valid, or more than 50 were sent. The page lists only the certificates that were sent, and nothing is revoked |
Reloading the result page may send the form again, which revokes nothing more and shows each certificate as already revoked. See ADR-0005.
Security model
The CA has no login of its own for admins. Instead an identity-aware proxy,
such as Cloudflare Access,
sits in front of /admin, signs in the admin, and adds a signed JWT to every
request it passes on. The CA verifies that JWT on every request against the
proxy's JWKS, issuer and audience, and decides who is an admin from an
allowlist of emails or roles. See
ADR-0002
for why.
- A request without a JWT, or with one that does not verify, gets
401. - A request with a valid JWT that has no
emailclaim, or whose email and roles are not in the allowlist, gets403. - Requests that change state (anything other than
GET,HEADorOPTIONS) must come from the admin UI itself: theirOriginmust be the admin UI's origin (https://<ADMIN_HOSTNAME>when it is set) and theirSec-Fetch-Siteheader must besame-origin, or they get403. The proxy keeps the admin's session in a cookie, so does not protect against cross-site requests itself. A refused request is logged at warning level with theOriginandSec-Fetch-Siteit had and the origin that was expected. - When a
RATE_LIMITERis configured, requests that change state are rate limited with the keyadmin:<email>, using the verified email, so they never share a key with the client API. TherateLimitKeyoption is not used for them.GETrequests are not limited. - Every response has a strict
Content-Security-Policy,Cache-Control: no-store,Referrer-Policy: same-originandX-Content-Type-Options: nosniff. The policy allows scripts and styles from the admin UI itself only, and no inline scripts. The only script is the one that shows times in the browser's time zone, and pages work without it. The stylesheet and script are the only responses that may be cached, see Stylesheet and script. Other sites are never sent a referrer.no-referreris not used because browsers then sendOrigin: nullon the admin UI's own forms, which would be refused. - Every request is logged at info level with the admin's email, the method, the path and the response status. The JWT is never logged.
Make sure the proxy protects every hostname the CA answers on, or set
ADMIN_HOSTNAME to the one it protects. On Workers this includes the
workers.dev hostname unless workers_dev is false.
When ADMIN_HOSTNAME is not set, the admin UI's origin is the origin of the
URL the CA receives. On Node.js behind a reverse proxy that terminates TLS,
that is usually http:// and an internal host name, while the browser sends
Origin: https://<public host>, so every revocation gets 403. Set
ADMIN_HOSTNAME to the public host name in that case. The origin it gives is
https://<ADMIN_HOSTNAME> on the default port, so the admin UI must be
reached on port 443.
Stylesheet and script
The admin UI's stylesheet and script are served at
/admin/style-<hash>.css and /admin/time-<hash>.js, where <hash> is the
first 8 hex characters of the SHA-256 of the file's content. The name changes
whenever the content does, so browsers can keep them for a year
(Cache-Control: private, max-age=31536000, immutable) and are never given
an old copy after the CA is updated. They are private as they are only
served to admins, behind the proxy.
Only the current name of each file is served. Any other name, such as
/admin/style.css or the name of an earlier version, gets a 404 that is not
cached. Pages are never cached, so they always link the current names.
Settings
| Setting | Meaning |
|---|---|
| ADMIN_JWT_HEADER | The request header holding the proxy's JWT |
| ADMIN_JWKS_URL | The https URL of the proxy's JWKS |
| ADMIN_JWT_ISSUER | The issuer (iss) the JWT must have |
| ADMIN_JWT_AUD | The audience (aud) the JWT must be issued for, or a comma separated list of them |
| ADMIN_JWT_ALGORITHMS | Optional. A comma separated list of the algorithms the JWT may be signed with, from RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, EdDSA and Ed25519. RS256 when unset |
| ADMIN_ALLOWED_EMAILS | A comma separated list of the emails of admins, compared case-insensitively with the JWT's email claim |
| ADMIN_ALLOWED_ROLES | A comma separated list of roles that make someone an admin, compared exactly |
| ADMIN_JWT_ROLES_CLAIM | The claim of the JWT holding the roles, as a string or an array of strings. A claim of any other type is ignored with a warning |
| ADMIN_HOSTNAME | Optional. The only host name the admin UI answers on, such as ssh-ca.example.com. Every other host name gets 404 for /admin |
The admin UI is turned on when ADMIN_JWT_HEADER, ADMIN_JWKS_URL,
ADMIN_JWT_ISSUER and ADMIN_JWT_AUD are set, along with
ADMIN_ALLOWED_EMAILS or both ADMIN_ALLOWED_ROLES and
ADMIN_JWT_ROLES_CLAIM. Roles are only used when both are set.
- When none of the
ADMIN_*settings are set, the admin UI is off and every/adminpath gets404. - When only some are set, the admin UI is also off, and a warning naming the missing settings is logged once. The rest of the CA keeps working.
- A setting that is set but not valid, such as an
httpJWKS URL or an audience list with an empty entry, makes the whole configuration invalid, as described under Validation.
An empty string counts as not set. List entries are trimmed, so
"[email protected], [email protected]" is accepted, but an empty entry is refused.
Cloudflare Access example
Create a self-hosted Access application for ssh-ca.example.com/admin with a
policy that allows your admins, then set:
"vars": {
"ADMIN_JWT_HEADER": "Cf-Access-Jwt-Assertion",
"ADMIN_JWKS_URL": "https://<team>.cloudflareaccess.com/cdn-cgi/access/certs",
"ADMIN_JWT_ISSUER": "https://<team>.cloudflareaccess.com",
"ADMIN_JWT_AUD": "<the Access application's AUD tag>",
"ADMIN_ALLOWED_EMAILS": "[email protected]",
"ADMIN_HOSTNAME": "ssh-ca.example.com"
}<team> is your Zero Trust team name. The AUD tag is shown in the Access
application's settings.
Client
Please visit the ssh-ca-client repository for further information:
https://github.com/andrewheberle/ssh-ca-client
SSH Endpoints
Host Configuration
For systems to allow SSH login using certificates the following configuration changes must be made:
PubkeyAuthentication yes
TrustedUserCAKeys /etc/ssh/ca.pub
AuthorizedPrincipalsFile /etc/ssh/principals.d/%u
# Uncomment the following lines to enable host certificates
# HostCertificate /etc/ssh/ssh_host_rsa_key-cert.pub
# HostCertificate /etc/ssh/ssh_host_ecdsa_key-cert.pub
# HostCertificate /etc/ssh/ssh_host_ed25519_key-cert.pubThe contents of /etc/ssh/ca.pub is the public key of the SSH CA, which can be
retrieved as follows:
curl https://ssh-ca.example.com/api/v4/ca | sudo tee /etc/ssh/ca.pubThe /etc/ssh/principals.d directory should contain a file corresponding to
a local user that contains a list of principals that should be allowed
login.
For example, with SSH_CERTIFICATE_PRINCIPALS set to ssh-admin (as in the
example wrangler.jsonc), the
following file named /etc/ssh/principals.d/admin would allow login
as the SSH user admin for the bearer of an issued (and valid) certificate:
ssh-adminTo refuse revoked user certificates, sshd also needs the user KRL.
ssh-ca-client downloads it
from /api/v4/user/krl, checks its signature with the CA public key and
writes it where OpenSSH can read it:
sudo ssh-ca-client-cli krl --out /etc/ssh/revocation_listThen add RevokedKeys /etc/ssh/revocation_list to sshd_config. Write the
KRL before setting RevokedKeys, as sshd refuses all public key
authentication when it cannot read the file, and refresh it regularly, as
certificates can be revoked at any time.
Client Configuration
In order for a client to trust a certificate presented by a host the following
configuration must be added to /etc/ssh/ssh_known_hosts (system wide) or
~/.ssh/known_hosts (user specific):
@cert-authority *.example.com ecdsa-sha2-nistp256 ....The format of the above file is documented in the ssh(1) man page however
the important item of note is that the *.example.com above tells ssh that the
CA public key (ie ecdsa-sha2-nistp256 ....) is trusted for all hosts, that
match *.example.com.
This will need adjusting depending on your environment along with the actual SSH CA public key which can be retrieved as follows:
curl https://ssh-ca.example.com/api/v4/caOnce the above configuration is completed and host certificates are in place clients will not require "trust on first use" (TOFU) as the certificate will be verified as being signed by the configured SSH CA.
SSH clients refuse revoked host certificates with the host KRL: run
ssh-ca-client-cli krl --host --out ~/.ssh/revocation_list and add
RevokedHostKeys ~/.ssh/revocation_list to ~/.ssh/config.
