Understanding OpenID Connect with diagrams
Here is what this post covers:
- Introduction
- What goes wrong when you log in with OAuth alone
- What OpenID Connect is
- ID tokens and access tokens
- The authorization code flow with OIDC
- Three single-use values
- Inside the ID token
- What the RP validates
- UserInfo and Discovery
- Wrapping up
- References
Introduction
In the post before last I walked through the OAuth authorization code flow, and in the previous post I covered PKCE, both with the example of a photo print service importing photos from Instagram. In both posts the question was “may the print service read my photos?”
This time, the same print service adds “Log in with Instagram”. Users can log in with their Instagram account without signing up, and their order history is tied to that account.
What the service needs here is not “what may I do” but “who just logged in”. OAuth was not designed to answer that, so OpenID Connect (OIDC) is layered on top of it. This post sorts out what OIDC adds to OAuth, using the same example and sequence diagrams as before.
The cast and the domains are the same as in the previous posts. Whether the real Instagram supports OIDC is beside the point; here, the authorization server (auth.example.net) is assumed to support it.
What goes wrong when you log in with OAuth alone
At the end of the flow from the previous posts, the print service holds an access token. An access token is like a building pass that says “you may read photos”. It does not say who its holder is, and the print service may not even be able to read what is inside it.
If you still want to know who the user is, the usual approach is to call a profile API with the access token and log the user in with the ID it returns. This approach has two problems.
First, the shape of the profile API differs from service to service. You need one implementation for Instagram, another for X, another for Google.
Second, the party that receives an access token cannot check whom the token was issued to. For example, if your service logs users in with an access token handed over from a browser or a mobile app, it cannot tell when someone brings in a token issued to a different app. Whoever brings it in gets logged in as the token’s owner.
OIDC solves both by defining a dedicated container that says who logged in, along with rules for passing it around.
What OpenID Connect is
OpenID Connect is a specification for authentication (checking who logged in) that sits on top of OAuth 2.0. It does not build a new flow from scratch. It adds a few parameters and a token to the authorization code flow from the previous posts.
PKCE and OIDC are both extensions to the same authorization code flow, and you can use them together. PKCE protects the handoff of the authorization code, while OIDC adds a way to say who the user is, so their roles do not overlap.
OIDC uses different names for the OAuth roles.
| Name in OIDC | Name in OAuth | In the photo print example |
|---|---|---|
| OP (OpenID Provider) | Authorization server | Instagram's authorization server (auth.example.net) |
| RP (Relying Party) | Client | The photo print service (print.example.com) |
| End user | Resource owner | You, logging in with Instagram |
The OP is the side that vouches for who the user is, and the RP is the side that relies on that and logs the user in. It is also called an IdP (Identity Provider), but this post sticks with OP.
ID tokens and access tokens
The biggest addition in OIDC is the ID token. When the RP exchanges the authorization code, the OP returns an ID token along with the access token. The RP now holds two tokens.
The two tokens have different readers and different destinations.
| ID token | Access token | |
|---|---|---|
| Like a | Photo ID | Building pass |
| Says | Who logged in | What the app may do |
| Read by | RP | API (resource server) |
| Audience | RP (its client_id is inside) | API |
| Format | Always a JWT | Up to the OP (not always a JWT) |
The RP reads the ID token, and that is where the ID token’s job ends. When calling an API, send only the access token, never the ID token. The reverse also holds: as “What goes wrong when you log in with OAuth alone” showed, do not use an access token as proof of who the user is.
The ID token names its audience (the RP’s client_id) and carries the OP’s signature. So the RP can check on its own that the token was issued by the right OP and addressed to itself. That solves the second problem from earlier, where a token issued to a different app is brought in.
The authorization code flow with OIDC
The big picture
In the diagram, the parts OIDC adds are green and the PKCE part from last time is purple. This time the print service is a web app, so the redirect URI is https://print.example.com/callback.
The steps are almost the same as in the previous posts. The differences are creating a nonce (2), adding scope=openid and the nonce to the authorization request (4), getting an ID token back (10), and the RP validating it to finish the login (11). UserInfo in step 12 is only for when you need attributes that are not in the ID token.
If all you need is login, you can skip the API call in step 13. If you also want to read photos, you can use the access token from the same flow as is.
The authorization request (step 4 in the diagram)
The request the browser sends to the OP looks like this (line breaks added for readability).
GET /authorize?response_type=code
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fprint.example.com%2Fcallback
&scope=openid%20profile%20email%20photos.read
&state=35ce
&nonce=n-0S6_WzA2Mj
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256 HTTP/1.1
Host: auth.example.net
Compared with the request from the post before last, this adds openid, profile and email to scope, the nonce, and the two PKCE parameters from last time.
| Parameter | Meaning |
|---|---|
scope=openid | The signal that this is an OIDC request. Without it the request is treated as plain OAuth and no ID token comes back |
profile, email | The attributes you want, such as name and email address. These scopes are defined by OIDC |
nonce | A single-use random value created by the RP. The OP puts it into the ID token as is (more on this below) |
photos.read is the scope for reading photos from the post before last. You do not need it if all you want is login.
The token response (step 10 in the diagram)
The request that exchanges the authorization code combines the ones from the two previous posts. Since this is a web app, it sends the client secret, and it also sends the PKCE code_verifier. What OIDC changes is the response.
{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"token_type": "Bearer",
"expires_in": 3600,
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.eyJpc3Mi...(truncated)"
}
The only change from the response in the post before last is the extra id_token. That string is the ID token, and we look inside it below.
Three single-use values
The RP now creates three single-use values in step 2. All of them are random, but who checks them, where, and what they prevent are different.
| Value | Checked by | Checked at | Prevents |
|---|---|---|---|
state (OAuth) | RP | Callback (step 8) | CSRF (being pulled into a flow the attacker started) |
code_verifier (PKCE) | OP | Token request (step 9) | Authorization code interception |
nonce (OIDC) | RP | Inside the ID token (step 11) | ID token replay |
The nonce travels much like state. The RP creates it, stores it in the session, and attaches it to the authorization request. The difference is where it comes back: state returns in the redirect URL, while nonce returns inside the ID token, which the OP has signed. The RP compares it with the value in the session and refuses the login if they do not match.
This way, if someone brings in an ID token that was issued earlier in a different context, its nonce will not match the current one and it gets rejected. Because the nonce is covered by the signature, it cannot be rewritten either.
Inside the ID token
The JWT format
An ID token is a JWT (JSON Web Token): a string made of three parts joined by ..
eyJhbGciOiJSUzI1NiIs... . eyJpc3MiOiJodHRwczov... . NHVaYe26MbtOYhSKkoKY...
header payload signature
The header holds the signing algorithm (alg) and the key ID (kid), and the payload holds information about the user. The signature is made with the OP’s private key, and the RP verifies it with the OP’s public key. The header and payload are only Base64URL-encoded, so anyone can read them. They are not the place for secrets.
The payload
Decoding the payload gives JSON like this. Each item in a JWT is called a claim.
{
"iss": "https://auth.example.net",
"sub": "248289761001",
"aud": "s6BhdRkqt3",
"exp": 1793581200,
"iat": 1793577600,
"nonce": "n-0S6_WzA2Mj",
"auth_time": 1793577590,
"amr": ["pwd", "otp"],
"name": "Hanako Yamada",
"email": "hanako@example.com",
"picture": "https://auth.example.net/p/248289761001.jpg"
}
| Claim | Meaning |
|---|---|
iss | The OP that issued the token. Required |
sub | The user's ID within the OP. Required |
aud | The audience. Holds the RP's client_id. Required |
exp, iat | Expiry time and issue time. Required |
nonce | The value the RP sent in the authorization request. Always present if the request included one |
auth_time, acr, amr | When the user logged in, how strong the authentication was, and which methods were used (password and one-time password in this example). Optional |
name, email, picture | User attributes requested with the profile and email scopes. Some OPs leave them out of the ID token and return them only from UserInfo |
To identify a user inside the RP, use the pair of iss and sub. sub is only unique within one OP, so without iss it could collide with the same sub from another OP. email can be changed by the user, so it is not a good key.
What the RP validates
When the RP receives an ID token, it checks the following before logging the user in (step 11).
| What | How |
|---|---|
| Signature | Verify it has not been tampered with, using the OP's public key (published at jwks_uri, covered below) |
iss | Matches the identifier of the OP you are talking to |
aud | Contains your own client_id |
exp | The expiry time is in the future |
nonce | Matches the value stored in the session in step 2 |
If any of them fails, the user is not logged in. The aud check is the answer to the problem from “What goes wrong when you log in with OAuth alone”, where a token issued to a different app is brought in.
Once everything passes, the RP looks up the user by iss and sub (creating one if needed), creates its own session, and the login is done. An ID token proves who the user was at the moment of login. It is not meant to be carried around as a session cookie.
In practice, an OIDC library does almost all of this, including verifying the signature. Still, knowing what it checks makes it easier to notice a missing setting.
UserInfo and Discovery
UserInfo
When you need attributes that are not in the ID token, call the UserInfo endpoint with the access token (step 12).
GET /userinfo HTTP/1.1
Host: auth.example.net
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
{
"sub": "248289761001",
"name": "Hanako Yamada",
"email": "hanako@example.com",
"email_verified": true
}
UserInfo is an API on the OP side that you call with the access token. The RP checks that the sub it returns matches the sub in the ID token, so it does not take in someone else’s information.
Discovery
To talk to an OP, the RP needs to know the authorization endpoint, the token endpoint, where the public keys are, and so on. In OIDC, the OP publishes these as JSON at a fixed URL. This is called Discovery.
The URL is the OP’s identifier (iss) followed by /.well-known/openid-configuration. Here is an excerpt from Google’s real one.
https://accounts.google.com/.well-known/openid-configuration
{
"issuer": "https://accounts.google.com",
"authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
"token_endpoint": "https://oauth2.googleapis.com/token",
"userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
"jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
"id_token_signing_alg_values_supported": ["RS256"],
"code_challenge_methods_supported": ["plain", "S256"]
}
| Field | Used for |
|---|---|
issuer | Compared with the ID token's iss |
authorization_endpoint | Where the authorization request goes (step 4) |
token_endpoint | Where the code is exchanged for tokens (step 9) |
userinfo_endpoint | Where extra attributes come from (step 12) |
jwks_uri | Where the public keys for verifying the ID token's signature live |
code_challenge_methods_supported | Supported PKCE methods. As covered last time, use S256 |
The usual setup is to configure only the OP’s identifier and the client ID and secret in the RP, and load the rest from Discovery. When the OP rotates its keys, the RP just fetches the new ones from jwks_uri, with no configuration change.
Wrapping up
- OAuth decides what an app may do; OIDC tells the app who logged in
- OIDC is not a new flow but the authorization code flow plus
scope=openid, anonceand an ID token, and it works together with PKCE - An ID token is a signed JWT addressed to the RP, and the RP checks the signature,
iss,aud,expandnoncebefore logging the user in - Identify users by the pair of
issandsub, and load endpoints and key locations from Discovery