Learn OAuth2 & OIDC: From Zero to Identity Provider Master

Goal: Deeply understand the mechanics of digital identity and authorization by building a custom Identity Provider (IdP) from first principles. You will move past “using a library” to understanding the cryptographic signatures, state transitions, and security constraints that allow millions of users to safely log into applications across the internet without sharing their passwords.

Why OAuth2 & OIDC Matters

In the early days of the web, if you wanted a third-party app to access your data (like a printing service accessing your Flickr photos), you had to give that app your actual password. This was a security nightmare known as the “Password Anti-Pattern.”

OAuth2 (Authorization) and OpenID Connect (Authentication) were created to solve this. They are the plumbing of the modern web. Understanding them is the difference between a developer who “clicks buttons in a dashboard” and an engineer who can architect secure, scalable, and interoperable systems.

  • Historical Context: Created by a community effort (led by Google, Twitter, and others) to move away from proprietary protocols like AuthSub and OpenID 1.0/2.0 into a standardized, JSON-based framework.
  • Real-World Impact: Every “Login with Google/GitHub/Apple” button uses these protocols.
  • Why it’s relevant: As we move toward decentralized identity (DID) and more complex microservices, the fundamental concepts of “Claims,” “Scopes,” and “Grants” remain the bedrock of security.

Core Concept Analysis

The Four Roles of OAuth2

To understand OAuth2, you must visualize the players in the room.

┌───────────────────┐          ┌───────────────────┐
│  Resource Owner   │          │      Client       │
│     (The User)    │          │  (The Application)│
└─────────┬─────────┘          └─────────┬─────────┘
          │                              │
          ▼                              ▼
┌───────────────────┐          ┌───────────────────┐
│ Authorization Srv │          │  Resource Server  │
│      (The IdP)    │          │     (The API)     │
└───────────────────┘          └───────────────────┘
  1. Resource Owner: The person who owns the data and can grant access to it.
  2. Client: The application trying to access the data (e.g., a mobile app, a website).
  3. Authorization Server: The engine that authenticates the user and issues tokens. This is what you will build.
  4. Resource Server: The API that holds the user’s data and accepts tokens for access.

The Authorization Code Flow (The “Gold Standard”)

This is the flow you will master. It involves two different “channels”: the Front-Channel (Browser) and the Back-Channel (Server-to-Server).

[ FRONT-CHANNEL ] (User's Browser)
1. User -> Client: "Login"
2. Client -> Browser: Redirect to IdP /authorize?client_id=...&scope=...
3. Browser -> IdP: Request login page
4. IdP -> Browser: "Enter credentials"
5. User -> IdP: Submit password
6. IdP -> Browser: Redirect back to Client /callback?code=XYZ123

[ BACK-CHANNEL ] (Secure Server-to-Server)
7. Client -> IdP: POST /token {code=XYZ123, client_secret=...}
8. IdP -> Client: {access_token: "...", id_token: "..."}

Authentication vs. Authorization

A common mistake is confusing these two:

  • OAuth2 (Authorization): “Is this application allowed to see my photos?” (Access Token / “The Valet Key”)
  • OIDC (Authentication): “Who is the person currently using this application?” (ID Token / “The Passport”)

OIDC is simply a thin layer of identity information (claims) on top of the OAuth2 framework.

The JWT (JSON Web Token) Anatomy

The “currency” of OIDC is the JWT. You must understand its three parts:

Header.Payload.Signature
[Base64].[Base64].[HMAC/RSA/ECDSA]
  1. Header: Algorithm and token type.
  2. Payload: The “Claims” (User ID, Expiration, Scopes).
  3. Signature: The cryptographic proof that the IdP issued this token and it hasn’t been tampered with.

Concept Summary Table

Concept Cluster What You Need to Internalize
OAuth2 Roles Identity is a relationship between four distinct parties, not just a login form.
Grants & Flows Different scenarios (Mobile vs. Server vs. IoT) require different “handshakes.”
JWT Mechanics Tokens are stateless, self-contained packages of truth that rely on math, not a database lookup.
Scopes & Claims Scopes are requested permissions; Claims are asserted facts about the user.
PKCE (Proof Key) Why the browser is “public” and cannot be trusted with secrets, and how to fix it with a dynamic secret.
OIDC Discovery How clients “find” your server’s configuration automatically via JSON metadata.

Deep Dive Reading by Concept

Foundational Security

Concept Book & Chapter
The OAuth2 Framework “OAuth 2 in Action” by Justin Richer — Ch. 1: “Introduction to OAuth 2.0”
Understanding Tokens “OAuth 2 in Action” by Justin Richer — Ch. 11: “Tokens”

OpenID Connect (OIDC)

Concept Book & Chapter
Identity Layer “OAuth 2 in Action” by Justin Richer — Ch. 13: “OpenID Connect”
JWT Structure “The JWT Handbook” by Sebastián Peyrott (Auth0) — Full Guide

Essential Reading Order

  1. The Core Framework (Week 1):
    • OAuth 2 in Action Ch. 1-3 (The roles and the Authorization Code flow)
    • RFC 6749 Sections 1-4 (The formal specification)
  2. The Security Layer (Week 2):
    • RFC 7636 (Proof Key for Code Exchange / PKCE)
    • OAuth 2 in Action Ch. 7 (Common Vulnerabilities)
  3. The Identity Layer (Week 3): —

Project List

Projects are ordered from fundamental understanding (tokens) to advanced infrastructure (discovery and security).

Project 1: The JWT Smith (Token Construction & Signing)

  • File: OAUTH2_OIDC_IDENTITY_PROVIDER_MASTERY.md
  • Main Programming Language: Node.js (with crypto module)
  • Alternative Programming Languages: Go, Python, Rust
  • Coolness Level: Level 3: Genuinely Clever
  • Business Potential: 1. The “Resume Gold”
  • Difficulty: Level 1: Beginner
  • Knowledge Area: Cryptography / Data Serialization
  • Software or Tool: OpenSSL / JWT.io
  • Main Book: “OAuth 2 in Action” by Justin Richer

What you’ll build: A CLI tool that can generate and verify JWTs (JSON Web Tokens) from scratch without using a high-level “JWT library.” You will use raw crypto primitives to sign payloads.

Why it teaches OAuth2: JWTs are the “currency” of modern identity. If you don’t understand how the signature prevents tampering, you don’t understand why OIDC is secure. This forces you to handle Base64URL encoding and HMAC/RSA signing manually.

Core challenges you’ll face:

  • Encoding Header and Payload → maps to Understanding Base64URL vs Standard Base64
  • Cryptographic Signing → maps to Understanding how private keys prove identity
  • Verification Logic → maps to How the Resource Server trusts the IdP

Key Concepts:

Difficulty: Beginner Time estimate: Weekend Prerequisites: Basic knowledge of JSON and how to run a terminal script.

Real World Outcome

Deliverables:

  • OAuth/OIDC server and client demo
  • Token validation output

Validation checklist:

  • State/nonce/PKCE are enforced
  • Scope checks deny missing permissions
  • Token expiration is respected

You will have a tool where you can input a user ID and a secret key, and it outputs a string that you can paste into JWT.io to see it successfully verified.

Example Output:

$ ./jwt_smith create --sub 123 --name "Alice" --secret "my-secret-key"
Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjMiLCJuYW1lIjoiQWxpY2UiLCJpYXQiOjE2MDk0NTkyMDB9.5vR...

$ ./jwt_smith verify --token <token> --secret "my-secret-key"
SUCCESS: Token is valid for Alice (ID: 123)

$ ./jwt_smith verify --token <token> --secret "wrong-key"
ERROR: Invalid Signature!

The Core Question You’re Answering

“How can I trust information sent by a user without asking my database for every single request?”

Before you write any code, sit with this question. If Alice sends you a piece of paper saying “I am an Admin,” how do you know she didn’t just write that herself? The signature is the wax seal on the envelope.

Concepts You Must Understand First

Stop and research these before coding:

  1. Hashing vs. Encryption
    • Can you reverse a hash?
    • What is the difference between SHA-256 and AES?
    • Book Reference: “Serious Cryptography” Ch. 2 - Jean-Philippe Aumasson
  2. Base64URL Encoding
    • Why do we remove =, +, and / from the encoding for JWTs?
    • Resource: RFC 4648 Section 5.

Questions to Guide Your Design

  1. The Header
    • What algorithm (typ) and type (alg) should be default?
    • How do you convert a JSON object into a URL-safe string?
  2. The Signature
    • How do you concatenate the header and payload before signing?
    • What happens if a single character in the payload is changed after signing?

Thinking Exercise

The Tamper Test

Look at this token: A.B.C If you change one byte in B (the payload), why does the signature C suddenly become invalid? Trace the math:

  1. C = HMAC(A + "." + B, secret)
  2. If B becomes B', then HMAC(A + "." + B', secret) will produce a different value than C.

The Interview Questions They’ll Ask

  1. “What is the difference between a JWT and a Session Cookie?”
  2. “Why should you never store sensitive data like passwords in a JWT payload?”
  3. “How does an RS256 (Public/Private key) signature differ from HS256 (Shared secret)?”
  4. “What is the ‘alg: none’ vulnerability and how do you prevent it?”
  5. “What are the three components of a JWT and what does each do?”

Hints in Layers

Hint 1: The String Format A JWT is just three Base64URL encoded strings separated by dots. encodedHeader.encodedPayload.signature.

Hint 2: Encoding Standard Base64 libraries often add padding (=) or characters like + which break in URLs. You need to replace + with -, / with _, and trim the =.

Hint 3: Signing Use your language’s crypto library (like crypto.createHmac in Node.js). The input to the HMAC function is the string encodedHeader + "." + encodedPayload.

Hint 4: Verification To verify, you don’t “decrypt” the signature. You re-calculate what the signature should be using the secret and the provided A.B, and check if it matches the provided C.

Books That Will Help

Topic Book Chapter
JWT Specification “RFC 7519” Full
Practical JWT “The JWT Handbook” by Auth0 Ch. 1-3

Project 2: The Client Registry (Metadata & Validation)

  • File: OAUTH2_OIDC_IDENTITY_PROVIDER_MASTERY.md
  • Main Programming Language: Node.js / Express
  • Alternative Programming Languages: Python (FastAPI), Go
  • Coolness Level: Level 2: Practical but Forgettable
  • Business Potential: 3. The “Service & Support” Model
  • Difficulty: Level 2: Intermediate
  • Knowledge Area: API Design / Database Modeling
  • Software or Tool: PostgreSQL / SQLite
  • Main Book: “OAuth 2 in Action” by Justin Richer

What you’ll build: A management system for “Clients” (the applications that will use your IdP). You’ll build the storage and validation logic that ensures only registered apps can start an OAuth flow.

Why it teaches OAuth2: You’ll learn that the “Client ID” is public, but the “Redirect URI” is a critical security boundary. You’ll implement strict validation rules that prevent attackers from stealing codes by redirecting them to malicious sites.

Core challenges you’ll face:

  • Storing Secrets Securely → maps to Hashing client secrets like passwords
  • Redirect URI Whitelisting → maps to Preventing ‘Open Redirector’ vulnerabilities
  • Client Metadata Management → maps to Handling Scopes and Grant Types allowed for a specific app

Key Concepts:

  • Client Registration: RFC 6749 Section 2
  • Open Redirectors: “OAuth 2 in Action” Ch. 7.2.1

Difficulty: Intermediate Time estimate: Weekend Prerequisites: Basic database knowledge (SQL) and building a simple REST API.

Real World Outcome

Deliverables:

  • OAuth/OIDC server and client demo
  • Token validation output

Validation checklist:

  • State/nonce/PKCE are enforced
  • Scope checks deny missing permissions
  • Token expiration is respected

You’ll have a database and an API that can answer: “Is my_app_123 allowed to use the authorization_code flow and redirect to https://myapp.com/callback?”

Example API Usage:

# Register a client
$ curl -X POST /clients -d '{"name": "My App", "redirect_uris": ["http://localhost:3000/cb"]}'
{"client_id": "client_abc", "client_secret": "secret_xyz"}

# Validate a request (Internal Logic)
validateRequest("client_abc", "http://attacker.com") 
>> Throw Error: Redirect URI not whitelisted!

The Core Question You’re Answering

“If anyone can say they are ‘The Login Button,’ how does the IdP know who is actually asking?”

Identity is a trust relationship. The Client Registry is your IdP’s “Guest List.” If you aren’t on the list, you don’t get a handshake.

Concepts You Must Understand First

Stop and research these before coding:

  1. Public vs. Confidential Clients
    • Why can a Server-side app (Node/Python) keep a secret, but a Mobile app or React app cannot?
    • Book Reference: “OAuth 2 in Action” Ch. 2.
  2. Redirect URI Safety
    • Why must we match redirect URIs exactly (or by strict prefix)?
    • What happens if we allow *.myapp.com?
    • Book Reference: “OAuth 2 in Action” Ch. 7.

Project 3: The Login Gate (Auth & Session Management)

  • File: OAUTH2_OIDC_IDENTITY_PROVIDER_MASTERY.md
  • Main Programming Language: Node.js / Express (with Sessions)
  • Alternative Programming Languages: Go (Gorilla Sessions), Python (Flask)
  • Coolness Level: Level 2: Practical but Forgettable
  • Business Potential: 1. The “Resume Gold”
  • Difficulty: Level 2: Intermediate
  • Knowledge Area: Web Security / Session Management
  • Software or Tool: Redis (Optional for sessions)
  • Main Book: “The Linux Programming Interface” (for the concept of identity/sessions)

What you’ll build: A login interface for your IdP. This isn’t just a form; it’s a stateful gate that verifies a user’s identity and maintains a session so they don’t have to log in for every single app.

Why it teaches OAuth2: OAuth2 assumes the user is already authenticated at the IdP. This project bridges the gap between “I entered my password” and “The IdP knows who I am during the OAuth flow.”

Core challenges you’ll face:

  • Secure Password Storage → maps to Using Argon2 or BCrypt
  • Session Persistence → maps to Secure/HttpOnly cookies
  • Flow State Persistence → maps to Carrying the OAuth query params (client_id, scope) through the login process

Difficulty: Intermediate Time estimate: 1 week Prerequisites: Understanding of HTTP cookies and basic form handling.

Real World Outcome

Deliverables:

  • OAuth/OIDC server and client demo
  • Token validation output

Validation checklist:

  • State/nonce/PKCE are enforced
  • Scope checks deny missing permissions
  • Token expiration is respected

A browser-based UI where a user can log in. After login, they are “remembered.” Crucially, if they visit /authorize?client_id=..., the server knows who they are.

Example Flow:

  1. User goes to /authorize (not logged in)
  2. Server redirects to /login but saves the authorize request details.

  3. User logs in.

Project 4: The Code Grant (The Logic of Authorization)

  • File: OAUTH2_OIDC_IDENTITY_PROVIDER_MASTERY.md
  • Main Programming Language: Node.js / Express
  • Alternative Programming Languages: Go, Python
  • Coolness Level: Level 3: Genuinely Clever
  • Business Potential: 1. The “Resume Gold”
  • Difficulty: Level 3: Advanced
  • Knowledge Area: State Machines / Web Security
  • Software or Tool: Redis / In-Memory Store
  • Main Book: “OAuth 2 in Action” by Justin Richer

What you’ll build: The core logic of the /authorize endpoint. You will generate a short-lived “Authorization Code,” tie it to a user and a client, and redirect the user back to the application.

Why it teaches OAuth2: This is the most critical step in the protocol. You’ll learn why the code is sent through the browser (front-channel) but the tokens are not. You’ll handle the “State” parameter and ensure that codes can only be used once.

Core challenges you’ll face:

  • Generating Secure Codes → maps to Using cryptographically strong random strings
  • Managing Code Expiry → maps to Ensuring codes last < 10 minutes
  • Single-Use Enforcement → maps to Deleting the code immediately after it’s exchanged
  • Preventing CSRF with ‘State’ → maps to Echoing back the state parameter exactly as received

Key Concepts:

Difficulty: Advanced Time estimate: 1-2 weeks Prerequisites: Project 2 (Client Registry) and Project 3 (Login Gate).

Real World Outcome

Deliverables:

  • OAuth/OIDC server and client demo
  • Token validation output

Validation checklist:

  • State/nonce/PKCE are enforced
  • Scope checks deny missing permissions
  • Token expiration is respected

You can visit a URL like http://localhost:3000/authorize?client_id=my_app&redirect_uri=http://localhost:4000/cb&response_type=code in your browser. After logging in, you are automatically redirected to http://localhost:4000/cb?code=ABC123XYZ.

Example Logic Check:

  1. Is client_id valid? (Project 2)
  2. Is redirect_uri whitelisted? (Project 2)
  3. Is User logged in? (Project 3)
  4. If yes, generate random code, store {code: "ABC...", user_id: 1, client_id: "my_app"}, redirect.

Project 5: The Token Exchange (The Back-Channel Handshake)

  • File: OAUTH2_OIDC_IDENTITY_PROVIDER_MASTERY.md
  • Main Programming Language: Node.js / Express
  • Alternative Programming Languages: Go, Python
  • Coolness Level: Level 3: Genuinely Clever
  • Business Potential: 4. The “Open Core” Infrastructure
  • Difficulty: Level 3: Advanced
  • Knowledge Area: Secure Communications / API Design
  • Software or Tool: Project 1 (JWT Smith)
  • Main Book: “OAuth 2 in Action” by Justin Richer

What you’ll build: The /token endpoint. This is a secure server-to-server API where the Client exchanges the “Authorization Code” for a real “Access Token” (JWT).

Why it teaches OAuth2: This project connects the front-channel to the back-channel. You’ll learn how to authenticate the Client itself (using client_id and client_secret) and how to issue the final JWT that represents the user’s permission.

Core challenges you’ll face:

  • Client Authentication → maps to Verifying Basic Auth or POST body secrets
  • Grant Validation → maps to Ensuring the code belongs to the client asking for the token
  • JWT Issuance → maps to Integrating Project 1 logic into the response

Key Concepts:

Difficulty: Advanced Time estimate: 1 week Prerequisites: Project 1 (JWT Smith) and Project 4 (Code Grant).

Real World Outcome

Deliverables:

  • OAuth/OIDC server and client demo
  • Token validation output

Validation checklist:

  • State/nonce/PKCE are enforced
  • Scope checks deny missing permissions
  • Token expiration is respected

An application can call your API and get back a JSON object containing a valid JWT.

Example Token Exchange:

$ curl -X POST /token \
    -u my_app:secret_xyz \
    -d "grant_type=authorization_code" \
    -d "code=ABC123XYZ" \
    -d "redirect_uri=http://localhost:4000/cb"

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

Project 6: The Proof (PKCE Implementation)

  • File: OAUTH2_OIDC_IDENTITY_PROVIDER_MASTERY.md
  • Main Programming Language: Node.js
  • Alternative Programming Languages: Go, Rust, Python
  • Coolness Level: Level 4: Hardcore Tech Flex
  • Business Potential: 1. The “Resume Gold”
  • Difficulty: Level 4: Expert
  • Knowledge Area: Cryptography / Protocol Security
  • Software or Tool: SHA-256
  • Main Book: “OAuth 2 in Action” by Justin Richer

What you’ll build: Implementation of PKCE (Proof Key for Code Exchange). You will add the ability to verify a code_challenge during authorization and a code_verifier during token exchange.

Why it teaches OAuth2: PKCE is mandatory for modern web and mobile apps. It teaches you how to solve the “Code Interception” attack in environments where a client secret cannot be kept safe (like a browser).

Core challenges you’ll face:

  • S256 Logic → maps to Calculating Base64URL(SHA256(verifier))
  • State Management → maps to Storing the challenge with the auth code
  • Security Logic → maps to Ensuring the exchange fails if the verifier doesn’t match the challenge

Key Concepts:

Difficulty: Expert Time estimate: 1-2 weeks Prerequisites: Project 4 and Project 5.

The Core Question You’re Answering

“If my mobile app’s ‘secret’ can be stolen by anyone who downloads the app, how can I ever safely authenticate it?”

Before you write any code, sit with this question. PKCE is like a “Disposable Secret” created on the fly for every single login.

Thinking Exercise

The Man-in-the-Browser Attack

Imagine an attacker can read the URLs redirected to your browser. They steal the code=XYZ.

Project 7: The Identity Passport (OIDC & ID Tokens)

  • File: OAUTH2_OIDC_IDENTITY_PROVIDER_MASTERY.md
  • Main Programming Language: Node.js
  • Alternative Programming Languages: Go, Python
  • Coolness Level: Level 3: Genuinely Clever
  • Business Potential: 1. The “Resume Gold”
  • Difficulty: Level 3: Advanced
  • Knowledge Area: Identity Protocols / JWT
  • Software or Tool: Project 1 (JWT Smith)
  • Main Book: “OAuth 2 in Action” by Justin Richer

What you’ll build: The transition to OpenID Connect. You will implement the id_token issuance, ensuring it contains standard OIDC claims like sub (subject), iss (issuer), aud (audience), and iat (issued at).

Why it teaches OAuth2: You’ll understand that an “Access Token” is for an API, but an “ID Token” is for the Client App. You’ll learn how to handle the openid scope and how the ID token provides a structured way to say “This is who the user is.”

Core challenges you’ll face:

  • Claim Mapping → maps to Translating database user fields to OIDC standard claims
  • Scope-based Issuance → maps to Only including email/profile claims if the scopes were requested
  • RSA Signing (RS256) → maps to Moving from shared secrets (HS256) to public/private keys (RS256) so clients can verify tokens themselves

Key Concepts:

Difficulty: Advanced Time estimate: 1 week Prerequisites: Project 1 and Project 5.

Real World Outcome

Deliverables:

  • OAuth/OIDC server and client demo
  • Token validation output

Validation checklist:

  • State/nonce/PKCE are enforced
  • Scope checks deny missing permissions
  • Token expiration is respected

When a client requests scope=openid profile, your /token endpoint returns two tokens. One is the access token (valet key), and the other is the id_token (passport).

Example Output:

{
  "access_token": "access_xyz_123",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer"
}

Project 8: The Discovery Document (Auto-Configuration)

  • File: OAUTH2_OIDC_IDENTITY_PROVIDER_MASTERY.md
  • Main Programming Language: Node.js / Express
  • Alternative Programming Languages: Any
  • Coolness Level: Level 2: Practical but Forgettable
  • Business Potential: 2. The “Micro-SaaS / Pro Tool”
  • Difficulty: Level 1: Beginner
  • Knowledge Area: System Interoperability
  • Software or Tool: JSON
  • Main Book: “OAuth 2 in Action” by Justin Richer

What you’ll build: The .well-known/openid-configuration endpoint and the jwks.json (JSON Web Key Set) endpoint.

Why it teaches OAuth2: This is how libraries like passport.js or oidc-client automatically “know” how to talk to your server. You’ll learn about public key infrastructure—how to share your public key so others can verify your signatures without knowing your secrets.

Core challenges you’ll face:

  • Formatting the Discovery JSON → maps to Exposing all supported endpoints and algorithms
  • JWKS Generation → maps to Converting RSA public keys into the JWK format

Key Concepts:

Difficulty: Beginner Time estimate: 2 days Prerequisites: Project 7 (RSA Signing).

Real World Outcome

Deliverables:

  • OAuth/OIDC server and client demo
  • Token validation output

Validation checklist:

  • State/nonce/PKCE are enforced
  • Scope checks deny missing permissions
  • Token expiration is respected

A public URL at /.well-known/openid-configuration that any OIDC-compliant library can use to “auto-configure” itself to use your IdP.

Project 9: The UserInfo API (The Final Detail)

  • File: OAUTH2_OIDC_IDENTITY_PROVIDER_MASTERY.md
  • Main Programming Language: Node.js / Express
  • Alternative Programming Languages: Go, Python
  • Coolness Level: Level 2: Practical but Forgettable
  • Business Potential: 3. The “Service & Support” Model
  • Difficulty: Level 2: Intermediate
  • Knowledge Area: API Design / Bearer Authentication
  • Software or Tool: Access Tokens
  • Main Book: “OAuth 2 in Action” by Justin Richer

What you’ll build: A protected endpoint /userinfo that returns user details when presented with a valid Access Token.

Why it teaches OAuth2: You’ll learn how to “consume” the tokens you issued. This forces you to implement a “Resource Server” logic within your IdP—parsing the Authorization: Bearer <token> header, validating the token, and returning the appropriate data.

Core challenges you’ll face:

  • Bearer Token Validation → maps to Ensuring the token isn’t expired or revoked
  • Scope Enforcement → maps to Only returning the email if the token has the ‘email’ scope

Key Concepts:

Difficulty: Intermediate Time estimate: 3 days Prerequisites: Project 5 and Project 7.

Real World Outcome

Deliverables:

  • OAuth/OIDC server and client demo
  • Token validation output

Validation checklist:

  • State/nonce/PKCE are enforced
  • Scope checks deny missing permissions
  • Token expiration is respected

A client application can call your API using the token it received, and get back the user’s profile information in JSON format.

Example Output:

$ curl -H "Authorization: Bearer access_xyz_123" https://your-idp.com/userinfo
{
  "sub": "123",
  "name": "Alice Smith",
  "email": "alice@example.com",
  "email_verified": true
}

The Core Question You’re Answering

“If the Access Token is just a string, how does an API know who the user is without asking the browser?”

The token is a signed proof. The UserInfo API is the first “customer” of that proof. It trusts the token because it can verify the signature (Project 1 logic).

Hints in Layers

Hint 1: Extracting the Token Look for the Authorization header. It usually looks like Bearer <token>. You’ll need to split the string to get just the token part.

Hint 2: Validation Use the same logic you built in Project 1 (or the public key logic from Project 7) to verify that the token is yours and hasn’t expired.

Hint 3: Mapping Scopes Your database might have 20 fields for a user. If the token only has the email scope, you must not return the phone_number field.

Project 10: Refresh Tokens & Revocation (Lifetime Management)

  • File: OAUTH2_OIDC_IDENTITY_PROVIDER_MASTERY.md
  • Main Programming Language: Node.js
  • Alternative Programming Languages: Go, Python
  • Coolness Level: Level 3: Genuinely Clever
  • Business Potential: 4. The “Open Core” Infrastructure
  • Difficulty: Level 3: Advanced
  • Knowledge Area: State Management / Security Lifecycle
  • Software or Tool: Redis / Database
  • Main Book: “OAuth 2 in Action” by Justin Richer

What you’ll build: The ability to issue refresh_tokens so users don’t have to log in every hour. You’ll also implement a revocation endpoint (/revoke) to invalidate tokens immediately.

Why it teaches OAuth2: You’ll learn the difference between “Stateless” (Access Tokens) and “Stateful” (Refresh Tokens) security. You’ll understand why refresh tokens must be stored in a database and the security implications of “Refresh Token Rotation.”

Core challenges you’ll face:

  • Token Rotation → maps to Issuing a new refresh token every time one is used
  • Revocation Propagation → maps to How to immediately “kill” a session across all devices

Key Concepts:

Difficulty: Advanced Time estimate: 1 week Prerequisites: Project 5 (Token Exchange).

Project 11: The Multi-Tenant IdP (SaaS Architecture)

  • File: OAUTH2_OIDC_IDENTITY_PROVIDER_MASTERY.md
  • Main Programming Language: Node.js / Express
  • Alternative Programming Languages: Go, Java (Spring)
  • Coolness Level: Level 4: Hardcore Tech Flex
  • Business Potential: 5. The “Industry Disruptor”
  • Difficulty: Level 4: Expert
  • Knowledge Area: Software Architecture / Database Design
  • Software or Tool: PostgreSQL (Schemas/Row Level Security)
  • Main Book: “Software Architecture in Practice” by Len Bass

What you’ll build: Transform your IdP into a multi-tenant system. Different “Organizations” can have their own sets of users, clients, and branding, all running on the same codebase.

Why it teaches OAuth2: This project moves you from “protocol understanding” to “infrastructure engineering.” You’ll learn how the iss (Issuer) claim in the JWT changes based on the tenant, and how to isolate data so Tenant A cannot authenticate for Tenant B.

Core challenges you’ll face:

  • Dynamic Issuer URLs → maps to Handling https://idp.com/{org_id}/authorize
  • Data Isolation → maps to Ensuring client_id is unique only within a tenant

Difficulty: Expert Time estimate: 2-3 weeks Prerequisites: All previous projects.

Project Comparison Table

Project Difficulty Time Depth of Understanding Fun Factor
1. JWT Smith Level 1 2 Days ⭐⭐ 🛠️🛠️🛠️
2. Client Registry Level 2 2 Days ⭐⭐ 🛠️
3. Login Gate Level 2 1 Week ⭐⭐⭐ 🛠️🛠️
4. Code Grant Level 3 1 Week ⭐⭐⭐⭐⭐ 🛠️🛠️🛠️🛠️
5. Token Exchange Level 3 1 Week ⭐⭐⭐⭐ 🛠️🛠️🛠️
6. PKCE Implementation Level 4 1 Week ⭐⭐⭐⭐⭐ 🛠️🛠️🛠️🛠️🛠️
7. Identity Passport Level 3 1 Week ⭐⭐⭐⭐ 🛠️🛠️🛠️
8. Discovery Doc Level 1 2 Days ⭐⭐⭐ 🛠️🛠️
9. UserInfo API Level 2 3 Days ⭐⭐ 🛠️🛠️
10. Refresh & Revoke Level 3 1 Week ⭐⭐⭐⭐ 🛠️🛠️🛠️
11. Multi-Tenant Level 4 3 Weeks ⭐⭐⭐⭐⭐ 🛠️🛠️🛠️🛠️
12. Security Hardening Level 4 1 Week ⭐⭐⭐⭐⭐ 🕵️‍♂️🕵️‍♂️🕵️‍♂️🕵️‍♂️🕵️‍♂️

Recommendation

If you are a total beginner: Start with Project 1 (JWT Smith). It removes the “magic” from tokens immediately. Then skip to Project 8 (Discovery) to see how the metadata looks.

If you want the “Aha!” moment: Focus on Projects 4, 5, and 6. These three projects are the core of the Authorization Code flow with PKCE. Once you build these, you will understand 90% of the internet’s security.

If you want a high-paying job: Complete Project 11 (Multi-Tenant). Building a multi-tenant IdP is a task usually reserved for senior security engineers at companies like Okta, Auth0, or Microsoft.

Final Overall Project: “The Sovereign Identity Engine”

The Challenge: Combine all 12 projects into a production-grade Identity Provider.

Requirements:

  1. Support for Authorization Code + PKCE (Confidential and Public clients).
  2. Full OIDC Compliance (Discovery, JWKS, UserInfo, ID Tokens).
  3. Security First: Must pass an automated OIDC certification suite test (like the OIDC Conformance Suite).
  4. Branding: Dynamic login pages per tenant.
  5. Monitoring: An audit log showing every token issued, refreshed, and revoked.

This project isn’t just a learning exercise; it’s a piece of infrastructure you can use to secure all your future side projects.

Summary

This learning path covers OAuth2 & OIDC through 12 hands-on projects. Here’s the complete list:

# Project Name Main Language Difficulty Time Estimate
1 The JWT Smith Node.js Level 1 Weekend
2 The Client Registry Node.js Level 2 Weekend
3 The Login Gate Node.js Level 2 1 Week
4 The Code Grant Node.js Level 3 1 Week
5 The Token Exchange Node.js Level 3 1 Week
6 The Proof (PKCE) Node.js Level 4 1 Week
7 The Identity Passport Node.js Level 3 1 Week
8 The Discovery Doc Node.js Level 1 2 Days
9 The UserInfo API Node.js Level 2 3 Days
10 Refresh & Revoke Node.js Level 3 1 Week
11 Multi-Tenant IdP Node.js Level 4 3 Weeks
12 Security Hardening N/A Level 4 1 Week

For beginners: Start with projects #1, #2, #8 For intermediate: Jump to projects #4, #5, #7 For advanced: Focus on projects #6, #11, #12

Expected Outcomes

After completing these projects, you will:

  • Understand every byte of a JWT and how signatures protect them.
  • Master the Authorization Code flow and why the browser is an “untrusted” medium.
  • Be able to implement PKCE from scratch in any language.
  • Know how to architect multi-tenant security systems.
  • Be capable of auditing existing OAuth2 implementations for critical flaws.

You’ll have built a fully functional OIDC Identity Provider that demonstrates deep understanding of identity from first principles.