Hardened OIDC JWKS and discovery metadata

Relying parties fetch two public documents to verify tokens: the environment JWKS and the OpenID discovery document. If either document overshares — a private JWK member, a claim the environment never emits, an algorithm no key can sign — clients cache the wrong picture of what Authdog will actually serve.

Published JWKS now strip private key material, and discovery metadata advertises only claims and algorithms the environment can serve.

This is the longer note behind the July 31 changelog entry.

How it works

Every environment keeps its own signing keys. Private halves stay inside Authdog. Verifiers fetch public halves from the environment JWKS endpoint. Rotation depends on that split: the JWKS document publishes active and not-yet-revoked keys so tokens signed during a rotation still verify, while revoked keys drop out of the published set.

The public document is a JWKS, not a key dump. Private JWK members are removed before the response is served. A client that caches jwks_uri should see kty, use, alg, kid, and the public parameters for that key type — not material that belongs only on the signer.

Discovery is aligned the same way. claims_supported lists claim names the environment is configured to emit, including custom mappings from Authentication > JWT Claims. Scopes and advertised algorithms follow what the environment can actually issue, including EdDSA when an Ed25519 key is in use.

Set it up

No extra add-on. After you create or rotate keys under Authentication > Sessions:

1. Create a new signing key. It starts inactive: published for verification, not yet signing.
2. Wait for relying parties to refresh cached JWKS.
3. Activate the new key so it signs new tokens.
4. Leave the previous key unrevoked until tokens it signed have expired.
5. Revoke the old key. It leaves the published JWKS.

Then fetch the environment's OpenID discovery document and confirm jwks_uri, claims_supported, and advertised algorithms match the keys and claim mappings you configured. The JWKS inspector and OIDC discovery tools are useful for a visual check.

Trust boundaries

JWKS is a public verification document. Treat it as readable by anyone who can reach the identity host. That is why private members must not appear there. Publishing a not-yet-revoked key is required for rotation; it is not a grant. A client that accepts a token must still check signature, kid, issuer, audience, and expiry against the environment it expects.

Discovery is advertisement, not authorization. claims_supported tells a relying party which names may appear. It does not mean every token will carry every claim. Custom claim resolution is best-effort; a missing claim is "no grant." Keep server-side checks as the source of truth.

Do not cache JWKS forever. After a revoke, verifiers that never refresh will keep accepting signatures from a key Authdog no longer publishes.

Try it

Rotate a key in Authentication > Sessions, then inspect JWKS and discovery for that environment. Key and claim setup is in Sessions and JWT claims. The original release note is in the changelog.