OpenID Connect

OpenID Connect (OIDC) is an identity layer built on top of OAuth 2.0 that enables applications to verify user identity and obtain basic profile information.

What is OpenID Connect?

OpenID Connect is a simple identity layer built on top of the OAuth 2.0 protocol. While OAuth 2.0 is designed for authorization (granting access to resources), OIDC adds authentication (verifying who the user is).

OIDC allows clients to verify the identity of an end-user based on the authentication performed by an authorization server, as well as to obtain basic profile information about the user in an interoperable and REST-like manner.

Key Concept

OIDC = OAuth 2.0 + Identity. Use OAuth 2.0 for authorization ("Can I access this?") and OIDC for authentication ("Who am I?").

Key Components

ID Token

A JWT (JSON Web Token) that contains claims about the authentication event and the user. This is the core addition that OIDC brings to OAuth 2.0.

{
  "iss": "https://auth.oauth42.com",
  "sub": "user_12345",
  "aud": "your_client_id",
  "exp": 1735689600,
  "iat": 1735686000,
  "auth_time": 1735686000,
  "nonce": "random_nonce",
  "email": "[email protected]",
  "email_verified": true,
  "name": "John Doe"
}

UserInfo Endpoint

An OAuth 2.0 protected resource that returns claims about the authenticated user. Access this endpoint using the access token to get additional user information beyond what's in the ID token.

Discovery Document

A well-known endpoint that provides metadata about the OpenID Provider's configuration, including endpoints, supported features, and public keys.

/.well-known/openid-configuration

Standard Claims

OIDC defines a set of standard claims that can be requested via scopes:

openidRequired

Required for OIDC. Returns sub (subject identifier) in the ID token.

profile

Returns profile information:

name, family_name, given_name
middle_name, nickname
picture, website, gender, birthdate

email

Returns email and email_verified claims.

address

Returns the user's physical mailing address.

phone

Returns phone_number and phone_number_verified.

offline_access

Requests a refresh token for offline access.

OIDC Authentication Flow

The OIDC flow is identical to OAuth 2.0 authorization code flow, but with OIDC-specific additions:

Authorization Request

Include openid in the scope parameter. Optionally include a nonce for replay protection.

GET /oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=openid+profile+email&
  state=random_state&
  nonce=random_nonce&
  code_challenge=CHALLENGE&
  code_challenge_method=S256

Token Response

The token endpoint returns an ID token in addition to the access token and refresh token.

{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbG...",
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ..."
}

Validate ID Token

Validate the ID token by verifying the signature, issuer, audience, expiration, and nonce.

Validation Steps:

Verify JWT signature using JWKS
Verify iss matches your OAuth42 issuer
Verify aud matches your client ID
Verify exp hasn't passed
Verify nonce matches your request

Get Additional Claims (Optional)

Call the UserInfo endpoint with the access token to get additional user information.

GET /oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

Response:
{
  "sub": "user_12345",
  "email": "[email protected]",
  "email_verified": true,
  "name": "John Doe",
  "picture": "https://..."
}

Discovery & JWKS

OpenID Configuration

OAuth42 provides a discovery document at the well-known endpoint:

https://auth.oauth42.com/.well-known/openid-configuration

This document contains metadata about the provider including supported endpoints, grant types, response types, scopes, and more.

JSON Web Key Set (JWKS)

Public keys for verifying ID token signatures are available at:

https://auth.oauth42.com/.well-known/jwks.json

Use these keys to verify the signature of ID tokens. Keys are rotated periodically for security.

Implementation Example

TypeScript with OAuth42 SDK

import { OAuth42Client } from '@oauth42/sdk';

const oauth42 = new OAuth42Client({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  redirectUri: 'http://localhost:3000/callback',
  issuer: 'https://auth.oauth42.com',
  scopes: ['openid', 'profile', 'email'],
});

// Start OIDC flow
const { codeVerifier, codeChallenge } = await oauth42.generatePKCE();
const nonce = generateRandomString(32);

// Store for validation
session.codeVerifier = codeVerifier;
session.nonce = nonce;

const authUrl = oauth42.getAuthorizationUrl({
  state: 'random_state',
  nonce,
  codeChallenge,
  codeChallengeMethod: 'S256',
});

// Handle callback
const tokens = await oauth42.exchangeCodeForTokens({
  code: req.query.code,
  codeVerifier: session.codeVerifier,
});

// Validate and decode ID token
const idToken = await oauth42.verifyIdToken(tokens.id_token, {
  nonce: session.nonce,
});

console.log('User:', idToken.email, idToken.name);

// Get additional claims from UserInfo
const userInfo = await oauth42.getUserInfo(tokens.access_token);

Best Practices

Always Validate ID Tokens

Never trust the ID token without validation. Verify the signature, issuer, audience, expiration, and nonce. Use the JWKS endpoint to get public keys for verification.

Use Nonce for Replay Protection

Always include a nonce in the authorization request and verify it in the ID token. This prevents token replay attacks.

Request Minimal Scopes

Only request the scopes you actually need. Users are more likely to grant consent when you request minimal permissions.

Use Discovery for Configuration

Use the OpenID discovery endpoint to dynamically configure your client. This ensures you always have the latest endpoints and capabilities.

Next Steps

OAuth 2.0 Overview

Learn about the OAuth 2.0 framework that OIDC builds upon

Tokens and Sessions

Deep dive into token types, lifecycle, and session management

Quick Start Guide

Get started with OAuth42 and OIDC in 5 minutes

Security Best Practices

Comprehensive security guidelines for your implementation