Realm keys¶
Every realm signs its tokens and its SAML assertions with its own key. You can let HelixIAM generate keys, bring your own key and certificate, or have HelixIAM create a key and a certificate signing request (CSR) for your CA — and roll over to a new key without downtime.
What it is¶
Each realm owns its own signing keys and publishes the public half in its JWKS and its SAML metadata. Relying parties verify the realm's tokens and assertions with those, so realms are isolated: one realm can never verify another's tokens.
- An active RS256 key, always — plus optional ES256 and EdDSA keys. OpenID Connect requires RS256, so every realm keeps exactly one ACTIVE RSA key (RS256, with PS256 published alongside for FAPI clients). A realm may add one ACTIVE EC P-256 key (ES256) and one ACTIVE Ed25519 key (EdDSA) beside it; these can only be activated while an ACTIVE RSA key exists.
- New realms sign with ES256. A realm created in the console, through the admin API or by an import, and the master
realm of a fresh install, gets an ACTIVE ES256 key beside its RS256 key, and signs access tokens, ID tokens (of
clients without their own algorithm), logout, delegation and workload-identity tokens with ES256. SAML keeps signing
with RSA. Set
HELIX_DEFAULT_SIGNING_ALG=RS256(helix.keys.default-signing-alg) to give new realms RS256 only. Existing realms are never changed. - Who signs what. ID tokens use the client's ID-token algorithm (
id_token_signed_response_alg), or the realm's ID-token default for clients without one. Access tokens, logout tokens, delegation and workload-identity tokens and JARM responses use the realm's default signing algorithm. SAML signs with the ACTIVE RSA key unless the realm chooses ES256 for SAML. See Signing settings. - Staged rollover. A new key starts as PENDING: it is published (JWKS and SAML metadata) but does not sign
until every cache of the JWKS can have it (the publish window: the JWKS cache lifetime plus the replica refresh, at
least
helix.keys.min-staging). Then it signs; the previous key becomes retained (statusROTATED) and stays published until the tokens it signed have expired, so they keep verifying. - Where keys live. In PostgreSQL (
realm_key), the private key encrypted withDB_ENCRYPTION. Imported and CSR keys are refused whenDB_ENCRYPTIONis not set (outside the dev profile). The private key is never returned by the API, shown in the console, logged or written to the audit log.
| Status | Published in JWKS and SAML metadata | Signs |
|---|---|---|
PENDING |
yes | no |
ACTIVE (one RSA, at most one EC) |
yes (listed first) | yes |
ROTATED (console: Retained) |
yes | no |
RETIRED |
no | no |
Where relying parties get the keys¶
| What | Where |
|---|---|
| OIDC/OAuth2 token signing keys (JWKS) | /realms/<realm>/oauth2/jwks, also advertised as jwks_uri in /realms/<realm>/.well-known/openid-configuration |
| Signing algorithms | id_token_signing_alg_values_supported in the discovery document: exactly the algorithms of the ACTIVE keys (RS256, PS256, and ES256 while an EC key is active); PENDING and retained keys are not advertised |
| SAML signing certificates | /realms/<realm>/saml/idp/metadata, one <KeyDescriptor use="signing"> per published key (ACTIVE first) |
Every JWK carries kid, alg and use: sig. A key with a certificate chain also carries x5c (standard Base64
DER, leaf first, without a trailing self-signed root) and x5t#S256. The kid of an RSA key is derived from its
modulus (as in earlier releases, so existing tokens keep verifying); the kid of an EC key is its RFC 7638
thumbprint. The console shows the kid of every key.
SAML assertion signing¶
The realm signs SAML with its ACTIVE RSA key — or with its ACTIVE EC key when the realm's SAML signing algorithm is ES256 (see Signing settings) — and publishes that key's certificate first in the IdP metadata:
- With a certificate (imported, or CA-signed after a CSR): the metadata and the signatures'
KeyInfocarry that leaf certificate. - Without a certificate (generated keys, or a CSR key before its certificate comes back): HelixIAM publishes a
deterministic self-signed certificate around the key (subject
CN=helix-idp-<realm>, valid 2000-01-01 to 2099-12-31), exactly as before. A PENDING key without a certificate is published with such a self-signed certificate too, so a metadata-reading SP can roll over to it either way. - PENDING and retained keys are published as additional
<KeyDescriptor use="signing">elements, so service providers that re-read the metadata trust the next key before it signs. - The
<KeyDescriptor use="encryption">is published only while SAML signs with an RSA certificate whose keyUsage allows keyEncipherment (or has no keyUsage extension).
Service providers should read live metadata — not pin the certificate
An SP that consumes the realm's metadata URL and re-reads it picks up a staged key before you activate it. An SP configured with a pinned copy of the certificate rejects assertions as soon as you activate a different key (or attach a renewed certificate to the active key): give it the new certificate first. See SAML clients.
EC keys and SAML
With the SAML signing algorithm set to ES256, SAML messages are signed with
http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256, whatever RSA algorithm a SAML client's options name. Many
service providers accept RSA signatures only: check every connected SP first. The default stays RSA. HelixIAM's
own sandbox relying party (a test harness) verifies RSA SAML signatures only.
In the console¶
Open Realm keys (under Manage). Changing keys needs the realm-admin permission (whoever controls the
signing key can issue any token of the realm); admins with manage-realm only see the keys, read-only. Each key shows its status (Pending / Active / Retained / Retired), algorithm,
certificate subject and issuer, expiry (with a warning chip when it expires within 30 days and a red chip when it has
expired), and SHA-256 fingerprint; the kid and key id are in the muted line under its name. From here you can:
- Import key and certificate — paste a PEM private key and its PEM certificate chain.
- Create CSR — choose RS256 or ES256, enter the subject (and DNS names); copy or download the CSR.
- Upload signed certificate — attach the chain your CA returned (pending or active keys).
- Rotate (generate) — opens Schedule a key rotation? with a choice of algorithm. The new key is generated and published at once and shows as Pending; it starts signing when the publish window has passed (the dialog shows how long, for example 1 hour), and the current active key of that algorithm becomes Retained. Tick Emergency: the current key is compromised, replace it now only for a compromised key: the new key signs at once and the old key is removed from the JWKS and metadata at once, so every token it signed stops verifying.
- Activate — a pending key starts signing now; a confirmation explains the effect, including the SAML note above. It shows how long the key has been published. Before the publish window has passed it warns that relying parties may not have the key yet, and you must tick Activate now anyway (recorded as a forced activation).
- Retire — drop a pending or retained key (or the active ES256 or EdDSA key) from the JWKS and metadata. A retained key can be retired only once the tokens it signed have expired (by default about 24 hours after it stopped signing); before that it is refused, unless you tick Emergency: this key is compromised, remove it now. The active RS256 key cannot be retired.
- Switch to EdDSA — give the realm an Ed25519 key with the same staged rollover, and sign its tokens with EdDSA. Many libraries cannot verify EdDSA yet; SAML never signs with it.
Back up the database and keep DB_ENCRYPTION
Realm keys live in PostgreSQL, encrypted with DB_ENCRYPTION. Losing the database, or the DB_ENCRYPTION value,
loses the keys: every issued token and every cached JWKS stops validating, and SAML service providers must re-read
metadata. Back up both. See the security checklist and backup guide.
Bring your own key and certificate¶
POST /admin/realms/{realm}/keys/import takes {privateKeyPem, certificateChainPem}.
- Private key: exactly one unencrypted PEM key, with nothing before or after it — PKCS#8 (
BEGIN PRIVATE KEY), PKCS#1 (BEGIN RSA PRIVATE KEY) or SEC1 (BEGIN EC PRIVATE KEY). RSA must be 2048 to 4096 bits with a public exponent of at least 65537 (odd, at most 32 bits); EC must be P-256. Encrypted PEM is refused (decrypt it first, for exampleopenssl pkey -in key.pem -out plain.pem). - Certificate chain: PEM certificates, leaf first, each certificate issued by the next one. The leaf must be
for this private key, must not be a CA certificate (
CA:true), and must havedigitalSignatureif it has a keyUsage extension. Every following certificate must be a CA (CA:true, andkeyCertSignif it has a keyUsage). Every certificate of the chain must be valid now (an expired or not-yet-valid certificate is refused). A single self-signed certificate is accepted. - A key that is already stored (in this realm or any other) is refused: every realm needs its own key.
Refusals are 400 {message, fieldErrors} on privateKeyPem or certificateChainPem. The examples below assume you
have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.
# Refresh CSRF after any GET, then POST (see the auth guide for the helper)
curl -s -b cookies.txt -c cookies.txt "$HELIX_URL/admin/realms/$REALM/keys" >/dev/null
CSRF=$(awk '($6=="__Host-XSRF-TOKEN"||$6=="XSRF-TOKEN")&&$7~/^r1\./{t=$7} END{print t}' cookies.txt)
jq -n --rawfile key key.pem --rawfile chain chain.pem \
'{privateKeyPem: $key, certificateChainPem: $chain}' |
curl -s -b cookies.txt -X POST -H "X-XSRF-TOKEN: $CSRF" -H "Content-Type: application/json" \
--data-binary @- "$HELIX_URL/admin/realms/$REALM/keys/import"
{
"keyId": "3f2c9a10-6b1e-4d8f-9c55-1a7e0b2d4c61",
"algorithm": "RS256",
"status": "PENDING",
"publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwV1W…AB",
"createdAt": 1792164099009,
"rotatedAt": null,
"kid": "tnydxwrdKX5Vlb6cLmgx1zTxt/GRcLtjNpJlR+jaqeU=",
"source": "IMPORTED",
"activatedAt": null,
"hasCsr": false,
"publicKeyFingerprint": "41:D1:C6:A4:…:9F:2F",
"certificate": {
"subject": "CN=idp.example.com,O=Example",
"issuer": "CN=Example Issuing CA",
"serialNumber": "1a1454db2d3",
"notBefore": 1792077698000,
"notAfter": 1823613698000,
"sha256Fingerprint": "66:A8:B6:40:…:3B:B6",
"selfSigned": false,
"chainLength": 2,
"expiry": "OK"
}
}
certificate.expiry is OK, EXPIRING (within 30 days) or EXPIRED.
Have HelixIAM create the key and a CSR¶
The private key never leaves the server: HelixIAM generates it (RSA-2048 for RS256, P-256 for ES256), stores it as
PENDING and returns a PKCS#10 CSR (signed with SHA256withRSA / SHA256withECDSA, with a keyUsage=digitalSignature
request and the DNS names as subjectAltName). The subject may use the attributes CN, O, OU, C, L, ST,
emailAddress, SERIALNUMBER, DC and UID (no raw OIDs, no #hex values); C must be a two-letter country code.
curl -s -b cookies.txt -X POST -H "X-XSRF-TOKEN: $CSRF" -H "Content-Type: application/json" \
-d '{"algorithm":"RS256","subject":"CN=idp.example.com, O=Example, C=NL","dnsNames":["idp.example.com"]}' \
"$HELIX_URL/admin/realms/$REALM/keys/csr" | tee csr-response.json | jq -r .csrPem > idp.csr
KEY_ID=$(jq -r .key.keyId csr-response.json)
Send idp.csr to your CA. You can download the CSR again later:
When the signed certificate comes back, attach it (leaf first, then the issuing CA certificates). The leaf must be for this key; the same chain rules as for an import apply:
jq -n --rawfile chain signed-chain.pem '{certificateChainPem: $chain}' |
curl -s -b cookies.txt -X PUT -H "X-XSRF-TOKEN: $CSRF" -H "Content-Type: application/json" \
--data-binary @- "$HELIX_URL/admin/realms/$REALM/keys/$KEY_ID/certificate"
You can also attach a renewed certificate to the active key (same key, new certificate). Tokens do not change; the SAML metadata and signatures switch to the new certificate at once.
Activate a staged key¶
Wait until your relying parties have picked up the PENDING key (OIDC verifiers that read the live JWKS do so within their cache time; SAML SPs when they re-read metadata), then:
curl -s -b cookies.txt -X POST -H "X-XSRF-TOKEN: $CSRF" \
"$HELIX_URL/admin/realms/$REALM/keys/$KEY_ID/activate"
The key becomes ACTIVE; the previous ACTIVE key of the same algorithm (RSA or EC) becomes ROTATED and stays
published. Only a PENDING key can be activated, and an ES256 key only while an RS256 key is active (anything else is
409 with the reason). Activations, rotations and retirements of one realm are serialised, so two concurrent
activations never leave two active keys. With several replicas, each replica switches within its 30-second key
cache; because the new key was already published, verifiers accept tokens from either replica.
Publish window. A key must have been published for the publish window before it can be activated: the JWKS cache
lifetime (max-age plus stale-while-revalidate) plus the replica refresh, and at least helix.keys.min-staging
(default 5 minutes, HELIX_KEYS_MIN_STAGING, an ISO-8601 duration such as PT10M). GET /keys/access returns it as
publishWindowSeconds. Earlier is 409 with "error": "staging". To activate anyway, add ?force=true; the audit event then records forced=true:
curl -s -b cookies.txt -X POST -H "X-XSRF-TOKEN: $CSRF" \
"$HELIX_URL/admin/realms/$REALM/keys/$KEY_ID/activate?force=true"
Rotate (scheduled)¶
curl -s -b cookies.txt -X POST -H "X-XSRF-TOKEN: $CSRF" -H "Content-Type: application/json" \
-d '{"algorithm":"RS256"}' \
"$HELIX_URL/admin/realms/$REALM/keys/rotate"
The body is optional (RS256 by default; ES256 generates an EC P-256 key, which needs an active RS256 key). The new
key is published at once as PENDING and signs once the publish window has passed; the active key of that algorithm
then becomes ROTATED. While a rotation is scheduled, another one is refused. For a compromised key, send
{"algorithm":"RS256","emergency":true}: the new key signs at once and the old key is removed at once, so verifiers
with a cached JWKS reject the new tokens until they refetch it, and a SAML SP that pinned the certificate breaks.
HELIX_ROTATE_REALM=<realm> still forces one RS256 rotation at startup; clear it afterwards.
Retire an old key¶
A retained key stays published for the retain window: the longest lifetime of a token it can have signed, at least
helix.keys.verification-overlap (default PT24H), plus the replica refresh and the JWKS cache window. After that,
retire it:
# Returns 204 No Content; the ACTIVE RS256 key is refused with 409
curl -s -b cookies.txt -X DELETE -H "X-XSRF-TOKEN: $CSRF" \
"$HELIX_URL/admin/realms/$REALM/keys/$KEY_ID"
Retiring a retained key earlier is 409 with "error": "retained" and retirableAt (epoch milliseconds). For a
compromised key, add ?emergency=true: it is removed at once and every token it signed stops verifying. A PENDING key
can be retired too (to discard a staged key), and so can the ACTIVE ES256 key unless the realm's
signing settings choose ES256 (then 409). While clients are registered for ES256 ID tokens, retiring the ACTIVE
ES256 key is 409 with their number and names; add ?force=true to retire it anyway (those clients then get RS256
ID tokens; the audit event records forced=true). The ACTIVE RS256 key is never retired: OpenID Connect requires RS256. Key
ids are scoped to the realm: a key id of another realm is 404 on every key route.
ES256 alongside RS256¶
ES256 is offered alongside RS256, never instead of it:
- Discovery lists exactly the algorithms of the ACTIVE keys:
RS256andPS256always, plusES256while an EC key is active. - A client gets ES256 ID tokens only when it is registered for them (
idTokenSignatureAlg: "ES256"on the client, the console's ID token signature algorithm). Choosing an algorithm the realm has no ACTIVE key for is refused with400onidTokenSignatureAlg. If the key goes away later, ID tokens fall back to RS256 and the server logs a WARN. - Access tokens and the other realm-signed JWTs follow the realm's default signing algorithm.
Signing settings¶
GET / PUT /admin/realms/{realm}/settings/signing (console: Realm settings → Tokens & sessions → Signing):
| Setting | Values | Applies to |
|---|---|---|
defaultAlg |
RS256, PS256, ES256, EdDSA (new realms: ES256) |
access tokens, logout tokens, delegation and workload-identity tokens, JARM |
samlAlg |
RS256 (default), ES256 |
SAML assertions, responses and logout messages |
Changing them needs realm-admin (reading needs manage-realm). ES256 needs an ACTIVE EC key (400 on the field
otherwise). The response also lists activeAlgorithms:
curl -s -b cookies.txt -X PUT -H "X-XSRF-TOKEN: $CSRF" -H "Content-Type: application/json" \
-d '{"defaultAlg":"ES256","samlAlg":"RS256"}' \
"$HELIX_URL/admin/realms/$REALM/settings/signing"
Realm exports do not include the signing settings yet; set them again on the target.
Certificate expiry¶
- Import and attach refuse expired or not-yet-valid certificates.
- HelixIAM checks ACTIVE and PENDING keys with a certificate one minute after start-up and every 6 hours
(
HELIX_KEYS_EXPIRY_CHECK_INTERVAL_HOURS;HELIX_KEYS_EXPIRY_CHECK_ENABLED=falseswitches it off). While a certificate expires within 30 days, or has expired, it writes one audit event per key per day —REALM_KEY_CERTIFICATE_EXPIRINGorREALM_KEY_CERTIFICATE_EXPIRED, actorsystem, with key id, algorithm, fingerprint,notAfterand days left — and a WARN log line. With several replicas only one of them warns. - The
realmSigningKeyshealth indicator (part of/actuator/health/readiness) reports the counts as details. It is alwaysUP: certificate expiry never takes a pod out of rotation. - An expired ACTIVE certificate does not stop signing. Token signatures do not depend on certificate validity, and stopping would take every login down. The realm keeps signing, warns daily and shows a red banner in the console. SAML SPs that check certificate validity reject the realm's assertions until you attach a renewed certificate or activate a new key.
Audit¶
Every key write is audited with the key id, algorithm and SHA-256 fingerprint (of the certificate, or of the public
key when there is none) — never key material: REALM_KEY_IMPORT, REALM_KEY_CSR, REALM_KEY_CERTIFICATE_ATTACH,
REALM_KEY_ACTIVATE (with forced=true for a forced activation), REALM_KEY_ROTATE, REALM_KEY_RETIRE. Should a
realm ever have two ACTIVE keys of one algorithm (for example after manual SQL), HelixIAM signs with the newest,
publishes the other for verification only, logs an ERROR and writes REALM_KEY_DUPLICATE_ACTIVE — it never stops
signing.
Realm export and import¶
Realm exports contain no signing keys and no certificates: private keys never leave the server, and a certificate without its key is useless on the target. An imported realm generates a fresh key on first use. To use your own key on the target, import the key and certificate there again (with its own key — the same key cannot be stored twice).
What you cannot do today¶
- HSM and KMS are opt-in per realm. By default (the Standard profile) keys are software keys in the database,
encrypted with
DB_ENCRYPTION. To keep a realm's keys in a PKCS#11 HSM or in Vault / OpenBao Transit, see Key custody. - No periodic rotation. Rotations are started by an administrator (console or API); only the switch-over is scheduled.
- No ACME or other automatic certificate renewal.
- Algorithms: RS256 (with its PS256 twin), ES256 and EdDSA (Ed25519) only; RSA keys up to 4096 bits; no RSA-PSS-only keys, no P-384/P-521. SAML never signs with EdDSA.
- No encrypted private-key PEM on import.
- Rolling upgrade: activate an ES256 key only after every replica runs this release; an older replica cannot load an EC key.
Full endpoint set¶
Method & path (under /admin/realms/{realm}) |
Purpose |
|---|---|
GET /keys |
List keys with status, algorithm, kid and certificate facts |
GET /keys/access |
{"canManage": true|false}: whether the signed-in admin holds realm-admin |
POST /keys/import |
Import a private key + certificate chain as PENDING |
POST /keys/csr |
Generate a PENDING key and return a PKCS#10 CSR; optional purpose (all, access, id, saml) for a custody realm |
GET /keys/{keyId}/csr |
Download the stored CSR again |
PUT /keys/{keyId}/certificate |
Attach a certificate chain to a PENDING or ACTIVE key |
POST /keys/{keyId}/activate |
Activate a PENDING key (the ACTIVE key of its algorithm becomes ROTATED); ?force=true skips the staging time |
POST /keys/rotate |
Generate and activate a new key at once (optional {"algorithm"}) |
DELETE /keys/{keyId} |
Retire a PENDING or ROTATED key, or the ACTIVE ES256 key |
GET /settings/signing · PUT /settings/signing |
The realm's signing algorithms |
Every write under /keys, and PUT /settings/signing, needs realm-admin; reads need manage-realm.