OpenID Connect (OIDC) Authentication Guide#

A comprehensive guide to understanding OpenID Connect and how it builds on OAuth 2.0 to provide standardized authentication.

Table of Contents#

1. What is OpenID Connect?
2. OAuth 2.0 vs OpenID Connect
3. How OpenID Connect Works
4. ID Tokens Explained
5. OIDC Scopes
6. OIDC Endpoints
7. Implementation Guide
8. UserInfo Endpoint
9. Token Validation
10. Discovery & Configuration
11. Security Considerations
12. Common Providers
13. Best Practices
14. Troubleshooting

What is OpenID Connect?#

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

The Problem OIDC Solves#

Before OIDC, every OAuth provider had their own way of providing user identity:

With OIDC, there's a standardized way:

Key Benefits#

• Standardization: Same flow for all OIDC-compliant providers
• Built-in user info: ID tokens contain user claims (no extra API call needed)
• Better security: Cryptographically signed tokens
• Industry standard: Widely adopted (Google, Microsoft, Apple, Okta, Auth0, etc.)
• Interoperability: Use any OIDC-certified library

OAuth 2.0 vs OpenID Connect#

Visual Comparison#

Side-by-Side Comparison#

Use Case Examples#

Use OAuth 2.0 when:

• Accessing a user's Google Drive files
• Posting to a user's Twitter account
• Reading a user's GitHub repositories
• Sending emails via Gmail API

Use OpenID Connect when:

• Logging users into your application
• Implementing Single Sign-On (SSO)
• Verifying user identity
• Getting user profile information

Use Both when:

• Sign in with Google AND access their calendar
• Sign in with GitHub AND read their repositories
• Sign in with Microsoft AND access OneDrive

How OpenID Connect Works#

The Complete OIDC Flow#

Step-by-Step Breakdown#

1. Authorization Request#

Key OIDC additions:

• scope includes openid (required for OIDC)
• nonce parameter for replay attack prevention

2. Token Exchange#

3. Decode & Verify ID Token#

ID Tokens Explained#

The ID token is the heart of OpenID Connect. It's a JSON Web Token (JWT) that contains identity information about the authenticated user.

Anatomy of an ID Token#

An ID token consists of three parts separated by dots:

Header#

Payload (Claims)#

Signature#

The signature ensures the token hasn't been tampered with:

Standard Claims#

Profile Claims#

Requested with scope=profile:

Email Claims#

Requested with scope=email:

Address Claims#

Requested with scope=address:

OIDC Scopes#

OpenID Connect defines standard scopes that request specific sets of claims.

Required Scope#

Without openid scope, it's just OAuth 2.0 (no ID token returned).

Standard Scopes#

Combining with OAuth Scopes#

You can mix OIDC scopes with provider-specific OAuth scopes:

Offline Access#

Request refresh token:

OIDC Endpoints#

OpenID Connect providers expose standard endpoints.

Discovery Endpoint#

The .well-known/openid-configuration endpoint returns all OIDC metadata:

Core Endpoints#

1. Authorization Endpoint#

Parameters:

• client_id - Your application's client ID
• redirect_uri - Where to send user after authorization
• response_type - Usually code
• scope - Must include openid + other scopes
• state - Random value for CSRF protection
• nonce - Random value for token replay prevention

2. Token Endpoint#

Parameters:

• code - Authorization code from callback
• client_id - Your application's client ID
• client_secret - Your application's client secret
• redirect_uri - Must match authorization request
• grant_type - authorization_code

Response:

3. UserInfo Endpoint#

Response:

4. JWKs Endpoint#

Response:

Implementation Guide#

Basic OIDC Implementation#

Handling Callback#

Manual Implementation (Without Library)#

UserInfo Endpoint#

The UserInfo endpoint provides additional claims not included in the ID token.

When to Use UserInfo#

Use ID token when:

• You only need standard claims (sub, email, name)
• You want to minimize API calls
• Token size is acceptable
• Claims don't change frequently

Use UserInfo endpoint when:

• You need claims not in ID token
• You want the latest user information
• Token size is a concern
• You need custom claims specific to the provider

Making UserInfo Requests#

Comparing ID Token vs UserInfo#

Token Validation#

Proper ID token validation is critical for security.

Validation Checklist#

Using a Library#

Discovery & Configuration#

OIDC providers publish their configuration at a well-known endpoint.

Discovery Document#

Common Provider Discovery URLs#

Caching Discovery Documents#

Security Considerations#

1. Always Validate ID Tokens#

2. Use Nonce for Replay Prevention#

3. Use State for CSRF Protection#

4. Implement Token Expiration#

5. Secure Token Storage#

6. Validate Issuer#

7. Use PKCE for Public Clients#

For mobile apps or SPAs:

Common Providers#

Google#

Microsoft / Azure AD#

Apple#

Okta#

Auth0#

Best Practices#

1. Use Discovery for Configuration#

2. Request Minimal Scopes#

3. Handle Token Refresh#

4. Implement Logout#

5. Validate All Claims#

Troubleshooting#

Common Issues#

Issue: "Invalid nonce"

Issue: "Invalid signature"

Issue: "Token expired"

Issue: "Invalid issuer"

Issue: No email in claims

Debugging Tools#

Resources#

Official Specifications#

• OpenID Connect Core 1.0
• OpenID Connect Discovery 1.0
• OpenID Connect Session Management

Libraries#

• Node.js: openid-client
• Python: PyJWT, Authlib
• Java: Nimbus JOSE+JWT
• C#: IdentityModel
• Go: coreos/go-oidc

Testing Tools#

• jwt.io - Decode and verify JWT tokens
• OpenID Connect Debugger - Test OIDC flows
• OAuth2 Debugger - Debug OAuth/OIDC flows

Certification#

• OpenID Certified Implementations - List of certified libraries and providers

Summary#

OpenID Connect provides:

1. Standardization: Common protocol across all providers
2. ID Tokens: Cryptographically signed JWTs with user identity
3. UserInfo Endpoint: Standardized API for user information
4. Discovery: Auto-configuration via well-known endpoints
5. Security: Built-in protections (nonce, state, signature verification)

Key Differences from OAuth 2.0#

• ✅ Includes openid scope → triggers OIDC flow
• ✅ Returns ID token (JWT) → contains user claims
• ✅ Standardized endpoints → same across providers
• ✅ Built-in identity verification → no custom userinfo endpoints

When to Use OIDC#

• User authentication / login
• Single Sign-On (SSO)
• Identity verification
• Getting user profile information

OpenID Connect = OAuth 2.0 + Identity Layer 🔐

Happy authenticating! 🎉