OpenID Connect

OAuth 2.0 answers what a client may do. It deliberately says nothing about who the user is, and for years people built their own answer on top of it, usually by calling some user-information endpoint and hoping the semantics matched.

OpenID Connect standardises that. It is an identity layer on top of OAuth 2.0, specified as OpenID Connect Core 1.0, and it adds three things to a flow you already know.

What OpenID Connect adds

An ID token. A JWT containing claims about the authentication event, addressed to the client that asked for it.

A standard openid scope. Requesting it is what turns an OAuth flow into an OpenID Connect flow, and further scopes such as profile and email ask for specific claim sets.

A discovery document and a key set. Published at well-known URLs, so a client configures itself and picks up rotated signing keys without a deployment.

Everything else is OAuth. The authorization code flow with PKCE is the same flow, the same redirect, the same code exchange. The token response carries an id_token alongside the access token.

The distinction that trips people up

An ID token and an access token are not interchangeable, and treating them as if they were is the most common OpenID Connect mistake.

	ID token	Access token
Answers	Who authenticated, and how	What the bearer may do
Audience	The client that requested it	The API it is meant for
Format	Always a JWT with defined claims	Whatever the authorization server chooses
Sent to an API	No	Yes
Validated by	The client	The resource server

The failure mode is sending the ID token to your API because it happens to be a JWT and it happens to contain the user's identifier. The API then validates a token whose audience is somebody else, which means the audience check either fails or was never implemented. If it was never implemented, the API will accept an ID token issued for any client at that provider.

The claims to check

An ID token is a JWT, so everything in bearer tokens and JWT applies. OpenID Connect adds a few requirements of its own.

Claim	What to check
iss	It matches the issuer you configured, exactly
aud	It contains your client identifier
exp	It has not passed
nonce	It matches the value you sent in the authorization request
azp	Where present, it is your client identifier
at_hash	Where present, it matches the access token you received

The nonce is the one people skip. It binds the ID token to the specific authentication request the client started, and it is what stops a token replayed from another session being accepted.

One more claim deserves a warning. The email claim is not proof of an email address unless email_verified is true. An application that links accounts on the email claim alone will link them to whatever address somebody typed at the provider.

Discovery, and why it matters more than it looks

The discovery document lives at a well-known path under the issuer and publishes the endpoints, the supported scopes and response types, and the location of the signing key set.

The convenience of not typing endpoint URLs is minor. The part that matters is the key set, because a client that reads it at runtime picks up a rotated signing key on its own. Without that, key rotation is a coordinated deployment across every client, which means it does not happen.

Two practical notes. Cache the key set with a sensible lifetime instead of fetching it per request, and refetch when you see a key identifier you do not recognise. And read the discovery document over TLS from the issuer you configured, because a client that discovers its issuer from user input can be pointed at somebody else's.

When plain OAuth is the better answer

OpenID Connect is not a strict upgrade. It asks for identity, which means consent screens that mention personal data, and it hands you personal data you then have to store and protect.

Use it when the identity is part of what you are building, so signing a user in, displaying their name, or linking a local account to an external one.

Skip it when you only need permission to call an API on somebody's behalf. A calendar integration that reads and writes events needs delegated access, and it does not need to know the user's name and email unless it displays them.

In Routebase

OpenID Connect appears in two places, and they serve different purposes.

In the specification. A security scheme component of type openIdConnect documents that an endpoint accepts OpenID Connect, and it carries the discovery URL so consumers and agents know where to configure themselves from. Schemes are created once per specification and attached to endpoints, and one action assigns a scheme across all endpoints, a folder, a tag or a hand-picked selection. That last part matters more than it sounds, because an endpoint nobody got around to securing looks exactly like one that is deliberately public.

In testing. An OpenID Connect deployment issues ordinary OAuth access tokens, so testing against it uses the OAuth 2.0 authentication type with the authorization code or client credentials grant. The Bearer type covers the case where a pipeline supplies the token. The ID token is a client-side concern and not something an API test sends.

See Components for security schemes in the designer and Project Auth for the test-side configuration. The chapter on designing authentication into your specification covers the documentation side in full.