OpenID Connect

OpenID Connect Core 1.0 (OIDC Core) is the identity layer on top of OAuth 2.1. Where OAuth tells you what a client can do, OIDC tells you who the user is. ThunderID implements OIDC Core as a thin layer over its OAuth 2.1 authorization code grant, adding the openid scope, the ID Token, the UserInfo endpoint, and a small set of authentication-context request parameters.

If your application needs the user's identity, request the openid scope. If it also needs to call APIs on the user's behalf, keep the access token. The two are complementary, not competing.

How It Works

The ID Token is a signed JWT delivered to the client at the token endpoint. It is never sent to a resource server: its audience is the client itself. Resource servers use the access token; clients use the ID Token to establish a local session.

How ThunderID Implements It

Aspect	Behavior
Activation	Include openid in the scope parameter of the authorization request
ID Token	Issued at the token endpoint alongside the access token
ID Token format	JWS by default; can be configured per app as JWE or NESTED_JWT (see Token Formats)
UserInfo	GET /oauth2/userinfo, see UserInfo
Standard scopes	openid, profile, email, phone, address, see Claims & Scopes
Subject types	public only: pairwise subject identifiers are not supported
Discovery	/.well-known/openid-configuration, see Server Metadata

ID Token Claims

Claim	Description
iss	Issuer: the ThunderID instance
sub	Stable identifier for the user within iss
aud	The requesting application's client_id
exp	Expiry as a Unix timestamp
iat	Issued-at as a Unix timestamp
auth_time	When the user actually authenticated, included when available
nonce	Echoed from the authorization request, clients must verify this
acr	Authentication Context Class Reference, which authentication flow ran

Additional user claims (e.g. name, email) are added based on the requested scopes, see Claims & Scopes.

Authentication Context Parameters

These parameters on the authorization request control how the user authenticates and what the ID Token reflects about that authentication.

Parameter	Purpose	Notes
nonce	Replay protection for the ID Token	Max 64 characters. Required for clients that accept the ID Token.
prompt	Control re-authentication	login, none, and consent are honored, see below
max_age	Limit how old the authentication may be	Seconds. An existing session older than this is not reused, so the user authenticates again.
id_token_hint	Name the user the request expects	An ID Token this ThunderID instance issued. Used with prompt=none to confirm the existing session belongs to that user.
acr_values	Request a specific authentication context	ThunderID selects an authentication flow that satisfies the requested ACR
claims	Request specific claims claim-by-claim	See Claims & Scopes

prompt, max_age, and id_token_hint are answered from the SSO session the authentication flow maintains, so they apply to applications whose flow includes a Check SSO Session node. See Single Sign-On for how a flow establishes one. The remaining parameters do not depend on a session.

note

prompt=none is answered by checking that a live session exists for the application's flow. A flow containing more than one Check SSO Session node, such as a step-up authentication flow, can therefore pass that check and still need to prompt at a later node, in which case the request fails rather than completing silently.

prompt Values

Value	Behavior
login	Forces the user to authenticate, even when a session exists. Supported.
none	Completes without any user interaction when a session satisfies the request. Returns login_required when no session exists, when id_token_hint names a different user, or when the authentication is older than max_age.
consent	Forces the user to re-grant consent for all required attributes, even if consent was previously granted.
select_account	Returns account_selection_required: account selection is not currently supported.

max_age and auth_time

max_age bounds how long ago the user authenticated. ThunderID compares it against the session's authentication time, not the time the authorization request arrived, so reusing a session does not make the authentication look fresher than it is.

The ID Token's auth_time claim reports that same moment. Two authorizations that reuse one session therefore carry the same auth_time, while an authorization that re-authenticated carries a later one.

Try It in ThunderID

OpenID Connect activates as soon as a client requests the openid scope. No deployment-level toggle is needed.

Agents typically use OIDC features only when running an authorization_code grant on a user's behalf; for pure machine-to-machine grants (client_credentials) there is no user identity to put in an ID Token.

Console

1. Open Applications or Agents in the ThunderID Console and select your client.
2. Open the Token tab and ensure openid is among the allowed scopes (it is by default).
3. Optionally configure ID Token format, encryption, and lifetime on the same tab (see Token Formats). Signing uses the deployment's signing key, unless the client selects an algorithm with id_token_signed_response_alg at registration.
4. Save.

Run an OIDC Sign-In

GET /oauth2/authorize
  ?response_type=code
  &client_id=$CLIENT_ID
  &redirect_uri=https://app.example.com/callback
  &scope=openid%20profile%20email
  &state=xyz
  &nonce=$NONCE
  &code_challenge=$CODE_CHALLENGE
  &code_challenge_method=S256

The token response will include both an access token and an ID Token:

{
  "access_token": "eyJhbGciOi...",
  "id_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOi...",
  "scope": "openid profile email"
}

Related Guides

• UserInfo, the endpoint that returns claims about the authenticated user
• Claims & Scopes, how scope requests map to claims in the ID Token and UserInfo
• Token Formats, JWS, JWE, and NESTED_JWT options for the ID Token
• Authorization Code, the underlying OAuth flow
• Server Metadata, the /.well-known/openid-configuration document