Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 39 ยท Tokens, JWT and OAuth

OpenID Connect: Logging In with OAuth

Learn how OpenID Connect adds identity to OAuth 2.0: ID tokens, discovery, JWKS, nonce and userinfo, and validate an ID token step by step in Node.js.

OAuth 2.0 tells an API what a client may do. It deliberately does not say who the user is, and many early "Log in with..." buttons misused access tokens as proof of identity. OpenID Connect (OIDC) is a thin identity layer on top of OAuth 2.0 that fixes this. It adds one new thing, the ID token, and a few standard endpoints and claims.

If you want "Sign in with Google" or single sign-on at work, you are using OIDC. If you are building an API, you usually consume OIDC tokens from an identity provider (Auth0, Keycloak, Entra ID, Okta, Google) instead of building the login pages yourself.

OAuth vs OIDC

OAuth 2.0 What may this app do?
OpenID Connect Who is this user?
Same flow OIDC adds scope openid.

The ID token is for the client. The access token is for the API.

1 / 2

What changes in the flow

You run the same authorization code flow with PKCE, with two additions:

  1. The scope list includes openid (and usually profile and email).
  2. The client also sends a random nonce.

The token response then contains an id_token next to the access_token. The nonce comes back inside the ID token, and the client compares it with the one it saved, which stops an attacker replaying a captured ID token into a new login.

The ID token

An ID token is a JWT (see JSON Web Tokens) signed by the identity provider. Its claims describe the authentication:

Claim Meaning
iss The provider's issuer URL
sub A stable, unique user ID at that provider
aud Must equal your client ID
exp, iat Expiry and issue time
nonce The value your client sent in the request
auth_time, acr, amr When and how the user authenticated (optional)
email, name, picture Profile claims, depending on scopes

Identify users by the pair (iss, sub), never by email. Emails can change, be reused by a different person, or be unverified. Check email_verified before trusting an email at all.

Discovery and JWKS

An OIDC provider publishes a discovery document at /.well-known/openid-configuration. It is JSON listing the issuer, the authorization, token and userinfo endpoints, supported scopes, and the jwks_uri. The JWKS (JSON Web Key Set) is the list of public keys the provider signs with, each marked by a kid. Your code reads the ID token's kid, finds that key in the JWKS (caching it), and verifies the signature. This is also how key rotation works without any change on your side.

JSON
{
  "issuer": "https://login.example.com",
  "authorization_endpoint": "https://login.example.com/authorize",
  "token_endpoint": "https://login.example.com/token",
  "userinfo_endpoint": "https://login.example.com/userinfo",
  "jwks_uri": "https://login.example.com/jwks.json",
  "id_token_signing_alg_values_supported": ["RS256"]
}

Validating an ID token

The simulator below plays both parties. A fake provider generates an RSA key pair, publishes its public key as a JWKS (exported as JWK by node:crypto), and signs an ID token. The client then runs every check in the order the specification requires.

Node.js Validate an ID token against a JWKS

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

In production use a maintained library (for example jose or openid-client) for these checks, and keep the same checklist in mind: signature with the key picked by kid, issuer, audience, expiry, nonce.

The userinfo endpoint and scopes

Scopes control which claims you may read:

Scope Claims
openid sub (required to get an ID token at all)
profile name, family_name, picture, locale...
email email, email_verified
offline_access A refresh token

Besides putting claims in the ID token, the provider offers a userinfo endpoint. The client calls it with the access token and receives a JSON object of the claims allowed by the granted scopes. Use it when you need fresh or large data and want to keep the ID token small.

Node.js Scopes decide which claims you get

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Using OIDC with your API

Your REST API normally accepts access tokens, not ID tokens. The ID token is addressed to the client application (its aud is the client ID). Sending it to your API as a bearer token is a common mistake. Instead:

  1. The client logs the user in via OIDC and gets an ID token (for its own UI) plus an access token with aud set to your API.
  2. The client calls your API with the access token.
  3. Your API verifies the access token's signature with the JWKS, then checks iss, aud, exp and the scopes.

Many providers issue JWT access tokens, others opaque ones, which you check by calling the provider's introspection endpoint (RFC 7662).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does OpenID Connect add to OAuth 2.0?

    OIDC adds authentication: the ID token, the openid scope, userinfo and discovery.
  2. 2. How should you uniquely identify a user from an ID token?

    sub is unique and stable only within one issuer, and emails can change or be reassigned.
  3. 3. What is the nonce for?

    The client sends a random nonce and rejects an ID token whose nonce claim differs.
  4. 4. Which token should your REST API normally accept as a bearer credential?

    ID tokens are meant for the client. APIs accept access tokens whose audience is the API.
  5. 5. How does a client find the key that signed an ID token?

    The discovery document points to a jwks_uri whose keys are identified by kid.

Summary

  • OIDC = OAuth 2.0 + identity: add the openid scope and get an ID token.
  • Validate an ID token: signature (key from JWKS by kid), iss, aud equals your client ID, exp, and nonce.
  • Identify users by (iss, sub), not by email.
  • Scopes control the claims; the userinfo endpoint returns them for an access token.
  • APIs check access tokens (audience = API), not ID tokens.

Next: API Keys