Command reference

oidc-ssh-ca is a single binary with subcommands:

oidc-ssh-ca serve --config policy.yaml [--listen :8080] [--ca-key-file PATH]
oidc-ssh-ca lambda [--config policy.yaml]
oidc-ssh-ca check-config policy.yaml
oidc-ssh-ca explain --policy policy.yaml --claims claims.json
oidc-ssh-ca print-ca-pub [--ca-key-file PATH]
oidc-ssh-ca version

serve

Runs the HTTP server.

--config (required) — path to the policy file. An invalid policy prevents startup.
--listen — listen address, default :8080. The server speaks plain HTTP; terminate TLS in front of it (see the deployment guides).
--ca-key-file — one of the three CA key sources (below).

SIGHUP reloads the policy; SIGTERM/SIGINT shut down gracefully.

lambda

Serves AWS Lambda Function URL events. Normally you never type this: when the process starts without arguments inside Lambda (deployed as bootstrap on provided.al2023, which sets AWS_LAMBDA_RUNTIME_API), lambda mode is selected automatically.

The policy is loaded once at cold start from --config, the OIDC_SSH_CA_CONFIG environment variable, or policy.yaml in the zip, in that order. There is no reload — deploy a new zip to change the policy.

check-config

Validates a policy file: strict YAML decoding, semantic validation, plus warnings for key_id_template variables that reference claims not pinned by the rule and for overly broad rules. Exits non-zero on error, so it slots into CI to lint policy changes before deployment.

explain

Evaluates a claim set against the policy without running a server:

oidc-ssh-ca explain --policy policy.yaml --claims claims.json

claims.json is a decoded JWT payload. On a match it prints the rule, principals, TTL, and the expanded key ID; otherwise it prints, for each rule, the first condition that failed. Use it to answer “why was this request denied?” from an audit event, or to dry-run a new rule.

print-ca-pub

Prints the CA public key in authorized_keys format — the line that goes into TrustedUserCAKeys on target servers. Reads the private key from the same sources as serve.

CA key sources

The CA private key is configured by exactly one of:

Source	Use
`--ca-key-file PATH`	flag, for interactive use
`OIDC_SSH_CA_KEY_FILE`	a path, e.g. a systemd credential or a mounted secret
`OIDC_SSH_CA_KEY`	the key itself, for environments without a filesystem (Lambda, Cloud Run secrets-as-env)

Zero or multiple configured sources is a startup error — the server never guesses which key you meant. Key files must be 0600 or stricter. Only ed25519 keys are accepted. The key is parsed in memory and the raw PEM is not retained; logs only ever contain the public key fingerprint.