Single sign-on (OIDC)

curral accepts JWTs from any OIDC provider sent as Authorization: Bearer <JWT>.

curral serve ... \
  --oidc-issuer https://sso.example.com/realms/main \
  --oidc-audience curral \
  --oidc-user-claim preferred_username \
  --oidc-roles-claim realm_access.roles

• Startup: curral runs OIDC discovery and downloads the JWKS. If the provider is unreachable, startup fails. Keys refresh in the background.
• Validation: signature, iss, aud, exp and nbf, with --oidc-skew (30 s) of clock tolerance. Unsigned tokens (alg: none) and tokens signed by another key are rejected.
• Audience is mandatory.
• Claims: dotted paths work (realm_access.roles). The roles claim may be a list or a space-separated string such as scope.

Roles by identity

Some providers, such as Google, send no roles. The identities section of the users file assigns roles per user or per e-mail domain:

identities:
  - match: ana@example.com    # exact, case-insensitive
    roles: [analyst]
  - match: "*@example.com"    # any address in the domain (not subdomains)
    roles: [analyst]

Mapped roles are added to the roles in the token. A user who matches nothing has no roles, and gets nothing under a deny-by-default policy.

Google

curral serve ... \
  --oidc-issuer https://accounts.google.com \
  --oidc-audience <CLIENT_ID>.apps.googleusercontent.com \
  --oidc-user-claim email
  # Google Workspace only: --oidc-hosted-domain example.com

• Create an OAuth client in Google Cloud Console → APIs & Services → Credentials.
• Clients send the ID token. Google access tokens are not JWTs and do not work.
• With an “External” consent screen, any Google account can get a valid token for your client ID. Access comes only from identities, and email_verified is required (--oidc-require-email-verified).

Caution

gcloud auth print-identity-token is handy for local tests, but its audience is gcloud’s own client ID. Never use that audience in production: every gcloud user’s tokens would be accepted.

Flags

Flag	Default
--oidc-issuer	off	issuer URL
--oidc-audience		required aud
--oidc-user-claim	sub	claim used as the user name
--oidc-roles-claim	roles	claim with roles
--oidc-skew	30s	clock tolerance
--oidc-require-email-verified	true	with email as user claim
--oidc-hosted-domain	any	accepted hd claims, repeatable