Examples¶

Task-focused, copy-and-adapt recipes for common ways to run Secsy PKI. Each folder is self-contained: a minimal, heavily-commented server config plus the client-side glue (workflow YAML, sshd_config drop-ins, systemd units, verify scripts) needed to make that one use case work end to end.

These configs are deliberately small. They are the opposite of server/config.yaml, which is the exhaustive annotated reference listing every knob. Start from an example here, then reach for the reference (and the docs/ guides) when you need a setting an example does not show.

Every config.yaml under examples/ is loaded and strict-decoded by the config test suite, so they always parse against the current server and never reference a config key that does not exist.

Catalogue¶

Example	Use case	Highlights
`ssh-pki/`	SSH certificate authority — replace `authorized_keys` sprawl with a single HSM-backed trust anchor	User + host certificate profiles, `sshd_config` trust drop-ins, `@cert-authority` client trust, KRL revocation refreshed by a systemd timer
`github-oidc-signing/`	Keyless software signing from GitHub Actions through OIDC	GitHub's OIDC identity federated to the `signer` role — no long-lived secret in the repo; HSM-backed CMS signatures with RFC 3161 timestamps; a reusable release workflow and a downstream `openssl cms` verify script
`acme-tls/`	Automated internal TLS for services and ingress	RFC 8555 ACME server bound to an issuing CA; `certbot` / `acme.sh` / `lego` / Caddy / cert-manager clients; rate limiting for the public endpoint
`mtls-internal/`	Private CA for service-to-service mTLS	`server` / `client` leaf profiles, a scoped API-token service account for CI issuance, and machine mTLS operator auth
`pkcs11-uri-addressing/`	Naming tokens and keys with RFC 7512 `pkcs11:` URIs — for when a `CKA_LABEL` stops being a unique name	Two HSMs behind one deployment addressed by serial; keys addressed by `CKA_ID`; a role pinned to one device and failing closed elsewhere; portable `module-name=` resolution; the token-URI / key-URI split the loader enforces
`multi-oidc/`	Several identity providers at once — GitHub Actions for automated signing, Entra ID for the console, a partner IdP for their auditors	The machine-Bearer / console-login split; per-provider audiences and claim → role mappings so one issuer's grant is unclaimable by another; one sign-in button per IdP; a shared or per-provider callback URL
`role-mapping-cel/`	Group names that encode the tenant — one mapping per role instead of one per role × tenant	CEL `expression` / `tenant_expression` over the authenticated identity; `matches` + `replace` + `regex.extract` turning `pki-issuers-acme-corp` and `CN=PKI-Auditors-globex,OU=Groups,…` into tenant ids; a derived id fenced by the declared `tenants:`; `secsy-ca role-mapping test` dry-running it all offline
`delegated-ca-administration/`	Per-CA / per-key authorization — the platform team keeps the root CA while each product team administers only its own subordinate	`rbac.grants` delegating one CA (or one signing key) to a group; `self` vs `subtree` scope; least-privilege audit of a single authority; `secsy-ca grant` and the console Access page

Common prerequisites¶

All examples assume you have built the binaries and have a PKCS#11 token available (SoftHSM works for evaluation — see scripts/setup-softhsm.sh and docs/hsm/configuration.md):

# From the repo root — build the server and the CLIs (sqlite tag = embedded store)
$ cd server
$ go build -tags sqlite -o ../bin/secsy-pki-server ./cmd/server
$ go build -tags sqlite -o ../bin/secsy-ca         ./cmd/secsy-ca
$ go build              -o ../bin/secsy-agent       ./cmd/secsy-agent
$ cd ..

# Provision a SoftHSM evaluation token and export the SECSY_* env the tools read:
$ eval "$(scripts/setup-softhsm.sh --export-env)"

Then, for any example:

# 1. Copy the example config and edit the placeholders (labels, hostnames, PINs).
$ cp examples/ssh-pki/config.yaml /etc/secsy-pki/config.yaml

# 2. Run any one-time provisioning commands from that example's README
#    (init a CA, create a signing key, etc.).

# 3. Start the server.
$ secsy-pki-server -config /etc/secsy-pki/config.yaml

Every config carries root_user.password: "change-me-in-production" and example labels/hostnames (pki.example.com, ops-ssh-ca, …). Replace these before any real deployment, and source the HSM PIN from a secret rather than inline pkcs11.pin (see docs/hsm/configuration.md, "External PIN sourcing").

Examples¶

Catalogue¶

Common prerequisites¶

See also¶