OpenID Connect

For anything that already has a login concept of its own, or that needs claims rather than headers. No proxy required.

cardinal app register grafana -redirect https://grafana.internal/oauth/callback

PKCE is required, and private_key_jwt is available for confidential clients. The discovery document is at <public-url>/.well-known/openid-configuration.

What a relying party is told

With the groups scope, the groups and group_ids claims appear in the id_token, the access token and the userinfo response. Access tokens are JWTs deliberately, so a resource server can validate one against the JWKS without calling Cardinal on every request, which is what keeps a Cardinal outage from taking every downstream API with it.

Which groups appear is a setting.

Key on group_ids, not on names. A group's name is a mutable attribute, so permission logic written against the string breaks silently the day somebody renames it.

Rotating the signing key

cardinal oidc key list
cardinal oidc key rotate -grace 24h

The same key signs id_tokens, access tokens and security events. The grace period defaults to the longest token lifetime any registered client is configured with, so the default is measured rather than assumed: the previous key keeps verifying until every token it signed has expired.

Which to choose

Use forwardAuth when the application has no auth of its own and you want none added. Use OIDC when the application already speaks it, or when it needs to know who rather than just whether.

Neither gives an application permissions inside itself. Cardinal decides whether you may reach a thing; what you may do once inside it is the application's own model, deliberately (ADR 0019).

In the console

Integrations → Applications lists registered relying parties, their redirect URIs and their hostnames, and is where a client secret is rotated.