learnings
Security
Authentication
OpenID Connect (OIDC)

OpenID Connect (OIDC)

What is OpenID Connect?

OpenID Connect (OIDC) is an authentication layer on top of the OAuth 2.0 protocol, which allows clients to verify the identity of the end-user based on the authentication performed by an authorization server, as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner. It is a widely used protocol for single sign-on (SSO) implementations across various web and mobile applications.

How does OpenID Connect work?

OpenID Connect extends OAuth 2.0. The core mechanism involves the client (such as a web application) requesting and receiving an identity assertion (a token) from the OpenID Provider (the server that handles user authentication). This token is called an ID Token, and it is a JSON Web Token (JWT) that contains claims about the authenticated user. The process typically follows these steps:

sequenceDiagram
    participant U as User
    participant C as Client
    participant OP as OpenID Provider

    U->>C: Access website
    C->>U: Redirect to OpenID Provider
    U->>OP: Enter credentials
    OP->>U: Authenticate and consent
    U->>C: Redirect back with auth code
    C->>OP: Exchange auth code for tokens
    OP->>C: ID Token and Access Token
    C->>U: User logged in
  1. Authentication Request: The client redirects the user to the OpenID provider to initiate an authentication session.
  2. Authentication and Consent: The user authenticates with the OpenID provider and grants consent for the client to access their information.
  3. Tokens Retrieval: Upon successful authentication, the provider returns an ID Token and, typically, an Access Token.
  4. Token Validation: The client validates the ID Token according to the OpenID Connect specification.
  5. User Info Request: Optionally, the client can use the Access Token to securely request additional user information from the UserInfo endpoint.

OIDC Endpoints & how it differs from OAuth 2.0

OIDC is built on top of OAuth 2.0. While OAuth 2.0 is primarily an authorization framework, OIDC adds an authentication layer to it. The key differences between the two protocols are:

  1. Discovery Endpoint: OIDC introduces a discovery endpoint that allows clients to retrieve metadata about the OpenID Provider, such as supported endpoints, algorithms, and scopes.
  2. ID Token: OIDC defines the ID Token, a JWT that contains claims about the authenticated user. This token is not part of the OAuth 2.0 specification.
  3. UserInfo Endpoint: OIDC introduces the UserInfo endpoint, which allows clients to retrieve additional user information after authentication.
  4. Standard Claims: OIDC defines a set of standard claims that can be included in the ID Token and UserInfo response. These claims provide information about the user, such as name, email, and profile picture.

For a comparison between OIDC and SAML, see SAML vs. OIDC.

ID Tokens

The ID Token is a JWT that contains claims about the authenticated user. It is signed by the OpenID Provider and can be used by the client to verify the user’s identity. The ID Token typically contains information such as:

{
  "iss": "https://openid-provider.com", // The issuer of the token.
  "sub": "1234567890", // The subject of the token (the user ID).
  "aud": "client_id", // The audience for which the token is intended.
  "exp": 1712929346,  // The expiration time of the token. This is a Unix timestamp.
  "iat": 1712929346,  // The time the token was issued. This is a Unix timestamp.
  "nonce": "n-0S6_WzA2Mj", // A random value used to prevent replay attacks.
  "acr": "urn:example:myapp:ex3", // The authentication context class reference.
  "auth_time": 1712929346, // The time of the user's authentication. This is a Unix timestamp.
  "amr": ["pwd"], // The authentication methods used.
  "name": "John Doe", // The user's full name.
  "email": "john.doe@example.com", // The user's email address.
  "email_verified": true, // Indicates whether the user's email address has been verified.
  "picture": "https://openid-provider.com/picture.jpg", // A URL to the user's profile picture.
  "locale": "en-US", // The user's preferred locale.
  "scp": ["openid", "profile", "email"] // The scopes granted to the client.
}

To objtain the ID Token, the client must include the openid scope in the authorization request. The ID Token is returned along with the Access Token after the user has authenticated and consented to the client’s request.

sequenceDiagram
    participant C as Client
    participant OP as OpenID Provider

    C->>OP: Authorization Request (scopes: openid, profile, email)
    OP->>C: Authorization Response
    C->>OP: Token Request 
    OP->>C: ID Token and Access Token

UserInfo Endpoint

The UserInfo endpoint is an API that allows clients to retrieve additional user information after authentication. The client can use the Access Token obtained during the authentication process to make a secure request to the UserInfo endpoint. The response typically contains claims about the user, such as name, email, and profile picture. e.g. a GET /userinfo request would yield the following response:

{
"sub": "1234567890",
"name": "John Doe",
"email": "john.doe@example.com",
"picture": "https://openid-provider.com/picture.jpg"
}
SAML 2.0Passkey