Who Are You?
OpenID Connect (OIDC) Fundamentals

Last updated: April 27, 2025

Table of Contents

1. Introduction: OIDC and Identity

In the previous article, we explored OAuth 2.0, the standard framework for delegated authorization. OAuth 2.0 allows applications to request limited access to user resources without sharing passwords. However, OAuth 2.0 itself doesn't tell the application *who* the user is. That's where OpenID Connect (OIDC) comes in.

OpenID Connect is a simple identity layer built on top of the OAuth 2.0 protocol. Its primary purpose is authentication – verifying the identity of the end-user and obtaining basic profile information about them in an interoperable and REST-like manner. Think "Login with Google" or "Sign in with Facebook" – these commonly use OIDC.

Essentially, OIDC leverages the OAuth 2.0 flows but adds a crucial piece: the ID Token, which securely communicates the user's identity to the client application.

2. Key Concepts & Terminology

OIDC introduces some specific terms alongside the OAuth 2.0 roles:

  • OpenID Provider (OP): An entity capable of authenticating the end-user and providing claims (information) about them. This is equivalent to the Authorization Server in OAuth 2.0, but specifically handles identity. (e.g., Google, Okta, Auth0, Ping Identity).
  • Relying Party (RP): The OAuth 2.0 Client Application that requires end-user authentication and claims from the OP. (The application you are logging into).
  • ID Token: A JSON Web Token (JWT) containing claims about the authentication event and the end-user. This is the core addition OIDC brings to OAuth 2.0.
  • UserInfo Endpoint: An OAuth 2.0 protected resource that returns authorized claims about the authenticated end-user when presented with a valid Access Token.
  • Standard Scopes: In addition to OAuth scopes for resource access, OIDC defines standard scopes specifically for requesting identity information. The most important is openid, which signals an OIDC request. Other standard scopes include profile, email, address, and phone, which map to specific sets of user claims.

3. OIDC Flows

OIDC utilizes the existing OAuth 2.0 flows but modifies them slightly to include the request for and return of identity information.

  • Authorization Code Flow: This is the most common and recommended flow for OIDC, mirroring the OAuth 2.0 Authorization Code Flow with PKCE.
    • The key difference is the inclusion of the openid scope (and potentially others like profile or email) in the initial authorization request.
    • When the Relying Party exchanges the authorization code at the token endpoint, it receives not only an Access Token (and potentially a Refresh Token) but also an ID Token.
    • The RP can then validate the ID Token and extract user information directly from it.
  • Implicit Flow: Similar to the OAuth 2.0 Implicit flow, it returns the ID Token (and potentially an Access Token) directly to the client in the redirect URI fragment. Like its OAuth counterpart, this flow is generally discouraged due to security concerns and the inability to obtain a Refresh Token.
  • Hybrid Flow: Combines aspects of the Authorization Code and Implicit flows, returning some tokens directly via the redirect (like the ID Token) and an authorization code to be exchanged for other tokens (like the Access Token). This can provide quicker access to user identity information while still allowing the backend to securely obtain Access Tokens.

For modern web and native applications, the Authorization Code Flow with PKCE is the preferred and most secure method for OIDC.

4. The ID Token

The ID Token is the heart of OIDC authentication. It's a security token in JSON Web Token (JWT) format, signed by the OpenID Provider (OP). The Relying Party (RP) receives the ID Token and MUST validate its signature and certain claims to confirm the user's identity and the integrity of the authentication event.

4.1 Standard Claims

An ID Token contains several standard claims (key-value pairs) providing information about the user and the authentication itself. Some essential ones include:

  • iss (Issuer): URL identifying the OP that issued the token.
  • sub (Subject): A unique identifier for the end-user at the OP. This is usually the primary user ID.
  • aud (Audience): The client ID of the RP the token is intended for. The RP MUST verify this matches its own client ID.
  • exp (Expiration Time): The time after which the ID Token MUST NOT be accepted (Unix timestamp).
  • iat (Issued At): The time at which the ID Token was issued (Unix timestamp).
  • auth_time: The time when the end-user authentication occurred.
  • nonce: A string value used to associate a client session with an ID Token and to mitigate replay attacks. The RP generates a nonce, includes it in the authentication request, and MUST verify it matches the nonce claim in the received ID Token.
  • acr (Authentication Context Class Reference): Optional. Identifier for the authentication context class (e.g., level of assurance).
  • amr (Authentication Methods References): Optional. List of identifiers for the authentication methods used.

Depending on the requested scopes (like profile, email), the ID Token might also contain user profile claims such as:

  • name
  • given_name
  • family_name
  • nickname
  • picture
  • email
  • email_verified
  • ...and others defined in the OIDC specification.

A sample (decoded) ID Token payload might look like this:


{
  "iss": "https://auth.example.com",
  "sub": "user123",
  "aud": "YOUR_CLIENT_ID",
  "exp": 1678886400,
  "iat": 1678882800,
  "auth_time": 1678882790,
  "nonce": "n-0S6_WzA2Mj",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "picture": "https://example.com/janedoe.jpg"
}

5. UserInfo Endpoint

While the ID Token contains essential identity information, sometimes the Relying Party needs additional user claims that weren't included (perhaps due to token size constraints or configuration). The UserInfo Endpoint is an OAuth 2.0 protected resource provided by the OpenID Provider.

The RP can make an authenticated GET or POST request to this endpoint using the Access Token obtained during the OIDC flow. The UserInfo endpoint then returns the authorized claims about the user, typically as a JSON object. The claims returned are controlled by the scopes granted in the associated Access Token.

6. OIDC vs. OAuth 2.0 Recap

It's crucial to remember the distinction:

  • OAuth 2.0 = Authorization Framework: Deals with granting access to resources. Provides Access Tokens.
  • OpenID Connect = Identity Layer: Deals with verifying user identity (authentication). Built on OAuth 2.0. Provides ID Tokens (in addition to OAuth tokens).

You use OAuth 2.0 when you need to *authorize* one application to access data from another. You use OIDC when you need to *authenticate* a user (log them in) using an external identity provider. Often, applications need both, which is why OIDC builds directly on OAuth 2.0 flows.

7. Security Considerations

OIDC inherits security best practices from OAuth 2.0 (HTTPS, state parameter, PKCE, secure token storage) but adds specific considerations:

  • ID Token Validation: Relying Parties MUST meticulously validate received ID Tokens. This includes verifying the signature using the OP's public key, checking the iss (issuer), aud (audience), exp (expiration), and iat (issued at) claims, and crucially, validating the nonce claim against the value stored in the user's session to prevent replay attacks.
  • Nonce Usage: The nonce parameter is vital for mitigating replay attacks, especially in flows where tokens might be returned via the browser. Always generate a unique, unpredictable nonce for each authentication request, store it securely tied to the user's session, and validate it in the returned ID Token.
  • UserInfo Endpoint Protection: Access to the UserInfo endpoint must be protected and only granted upon presentation of a valid Access Token containing appropriate scopes.
  • Flow Selection: Avoid the Implicit flow due to inherent security risks. Use the Authorization Code flow with PKCE whenever possible.

8. Conclusion

OpenID Connect provides a standardized, secure, and interoperable way to perform user authentication on top of the OAuth 2.0 authorization framework. By introducing the ID Token (a JWT containing user claims) and standardizing endpoints like UserInfo, OIDC enables scenarios like Single Sign-On (SSO) and allows applications (Relying Parties) to verify user identity based on authentication performed by a trusted OpenID Provider. Understanding OIDC fundamentals, particularly the role of the ID Token and the importance of proper validation and security practices like using the nonce parameter, is essential for developers building secure login systems in modern applications.

9. Additional Resources

Related Articles

External Resources