What is OpenID Connect (OIDC)?

The question OAuth leaves open

OAuth 2.0 is about delegated access: “this app may call that API with these permissions.” The access token it produces is meant for the API and does not give the client a standard, verifiable statement of who the user is. For years, many apps nonetheless treated “I obtained a token” as “the user is logged in”, which opens the door to mistakes such as accepting a token that was issued to a completely different application.

OpenID Connect closes that gap with a standard answer. It also names the parties: the OpenID Provider (OP) authenticates the user, and the Relying Party (RP) is the application that relies on that result.

The flow: the openid scope and the ID token

OIDC does not invent a new protocol; it adds a few pieces to the OAuth flows. In the usual authorization code flow, the client includes openid in the scope when redirecting the user; without it, the request is plain OAuth. It may also ask for profile and email, and sends a nonce to bind the response to this login attempt. After the user signs in and consents, the client exchanges the code at the token endpoint and receives something like:

{
  "access_token": "SlAV32hkKG",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.eyJpc3Mi..."
}

Inside an ID token

An ID token is always a JWT. The spec requires iss (the issuing provider), sub (a stable identifier for the user at that provider), aud (the intended audience, which must contain the client's client_id), exp and iat. Depending on the request it may also carry auth_time (when the user actually authenticated), nonce, and acr and amr, which describe the authentication context and methods, for example password plus a one-time code.

One practical rule: link accounts in your own database on the pair of iss and sub, never on email. Email addresses change and can even be reassigned to someone else at the provider, whereas a sub is defined as never reassigned within its issuer.

Validating the token

1. Verify the signature against the provider's published keys (JWKS). Their location, along with every endpoint, is listed in the discovery document at /.well-known/openid-configuration.
2. Check that iss exactly matches the provider you expect.
3. Confirm that aud contains your own client_id.
4. Reject the token if exp has passed.
5. If you sent a nonce, compare the claim with the value stored in the user's pending login.

Once validation passes, the application starts its own session. Further profile details can be fetched from the UserInfo endpoint using the access token. The normative details are in OpenID Connect Core 1.0.

ID token versus access token

Using the ID token as a bearer credential for API calls is a common mistake; APIs should expect an access token issued for them. In enterprise single sign-on, the XML-based SAML 2.0 meets a similar need, but OIDC has become the default choice for new web and mobile projects.