OpenID Connect Introduction — Authentication Layer for Modern Applications

In this tutorial, you will learn about Openid Connect Introduction. We cover key concepts, practical examples, and best practices to help you master this topic.

OpenID Connect (OIDC) is an identity layer built on top of OAuth2 that verifies user identity through signed ID tokens and a UserInfo endpoint, providing authentication alongside OAuth2 authorization.

What You'll Learn

• What OIDC is and how it extends OAuth2 with authentication
• The difference between authentication and authorization
• Core components: ID tokens, UserInfo endpoint, discovery URL

Why It Matters

OAuth2 alone tells your application what the user can access, but not who the user is. OIDC solves this by returning a signed ID token containing user identity claims. Doda Browser uses OIDC for social login — the ID token provides user identity while OAuth2 handles API access.

Real-World Use

When a user clicks "Sign in with Google" on Doda Browser, the browser redirects to Google's OIDC provider. Google authenticates the user and returns an ID token (containing name, email, and avatar URL) plus an access token (for calling Google APIs).

flowchart LR
    Browser["Doda Browser"] -->|"Auth Request"| OP["OIDC Provider\n(Google)"]
    OP -->|"ID Token + Access Token"| Browser
    Browser -->|"ID Token"| Backend["Backend\nVerify Token"]
    Browser -->|"Access Token"| API["Google API"]
    style OP fill:#dbeafe,stroke:#2563eb

OIDC vs. OAuth2

Core Components

• ID Token: A JWT that contains user identity claims signed by the provider
• UserInfo Endpoint: Returns additional user claims via API
• Discovery URL: .well-known/openid-configuration with provider metadata
• Scopes: Request specific claims like profile, email, address

Simple OIDC Flow

import requests
from jose import jwt

# Step 1: Redirect user to OIDC provider (simplified)
auth_url = "https://accounts.google.com/o/oauth2/v2/auth"
params = {
    "client_id": "your-client-id",
    "redirect_uri": "https://yourapp.com/callback",
    "response_type": "code",
    "scope": "openid profile email",
}
print(f"Redirect user to: {auth_url}?{urllib.parse.urlencode(params)}")

# Step 2: Exchange authorization code for tokens
token_url = "https://oauth2.googleapis.com/token"
token_data = {
    "code": "authorization-code-from-callback",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "redirect_uri": "https://yourapp.com/callback",
    "grant_type": "authorization_code",
}
token_resp = requests.post(token_url, data=token_data)
tokens = token_resp.json()
id_token = tokens["id_token"]

# Step 3: Decode and verify the ID token
claims = jwt.decode(id_token, key, algorithms=["RS256"], audience="your-client-id")
print(f"Authenticated user: {claims.get('name')} ({claims.get('email')})")

Expected output:

Authenticated user: Alice Smith (alice@example.com)

Common Mistakes

1. Using Access Tokens for Authentication

Access tokens grant API access but do not identify the user. Always use the ID token or UserInfo endpoint for authentication.

2. Not Verifying the ID Token Signature

Without signature verification, any JWT can impersonate a user. Always validate the signature using the provider's JWKS endpoint.

3. Ignoring the aud Claim

The aud (audience) claim specifies which client the token was issued for. Verify it matches your client ID.

4. Forgetting the openid Scope

Without the openid scope, the provider does not return an ID token. You only get an access token.

5. Storing ID Tokens Long-Term

ID tokens expire quickly (typically 1 hour). Use them for initial authentication and rely on refresh tokens for session persistence.

Practice Questions

1. What is the primary difference between OAuth2 and OpenID Connect?
2. What information does an ID token contain?
3. Why must the ID token signature be verified?
4. What is the purpose of the openid scope?
5. When should you use the UserInfo endpoint vs. the ID token?

Answers:

1. OAuth2 handles authorization (what the app can do); OIDC adds authentication (who the user is) through ID tokens.
2. The ID token contains claims about the user's identity: issuer, subject, audience, expiration, and optionally name, email, picture.
3. Without signature verification, anyone can forge a JWT and impersonate any user on your application.
4. The openid scope is required for OIDC. It signals the provider to return an ID token in addition to the access token.
5. Use the ID token for standard claims (sub, name, email). Use UserInfo for additional claims not included in the ID token.

Challenge: Set up an OIDC login flow with a provider of your choice (Google, GitHub, Okta). Capture the ID token, verify it locally, and extract user claims.

FAQ

Mini Project

Create a Python Flask app that implements OIDC login with a provider of your choice. The app should redirect to the provider, handle the callback, verify the ID token, and display the user's name and email.

What's Next

Continue with OIDC vs OAuth2: Key Differences to understand when to use each protocol, or explore Understanding ID Tokens for a deep dive into token structure.