Audience: Security practitioners, cloud engineers, and developers studying IAM, SC-200, or modern authentication protocols.
Goal: After reading this document, you should be able to explain OAuth 2.0 end-to-end, implement it securely, identify attack vectors, and make informed design decisions.

Table of Contents

1. Introduction
2. Core Components
3. OAuth 2.0 Flows (Grant Types)
4. Protocol Internals
5. End-to-End Example
6. Practical Exercises
7. Security Deep Dive
8. Best Practices

1. Introduction

1.1 What Is OAuth 2.0?

OAuth 2.0 is an authorization framework defined in RFC 6749. It enables a third-party application to obtain limited access to a service on behalf of a user — without ever seeing that user’s credentials.

The key word is authorization (what you’re allowed to do), not authentication (who you are). OAuth 2.0 does not, by itself, tell an application who the user is — that’s the job of OpenID Connect (OIDC), which is a thin identity layer built on top of OAuth 2.0.

1.2 Why Does OAuth 2.0 Exist?

The Problem: Credential Sharing

Before OAuth, if you wanted App A to access your data on Service B (e.g., a photo printing service accessing your Google Photos), the only option was to give App A your Google username and password.

This is catastrophically insecure:

• App A now has full access to your Google account — not just photos
• You cannot revoke access without changing your password (which affects all apps)
• App A could store, leak, or misuse your credentials
• If App A is breached, your Google account is compromised

The Solution: Delegated Authorization

OAuth 2.0 replaces credential sharing with tokens. Instead of your password, App A receives a short-lived, scoped access token that only grants access to what you explicitly approved (e.g., read-only access to photos).

WITHOUT OAuth:   User → gives password to App → App acts as User (unlimited access)
WITH OAuth:      User → approves limited scope → Auth Server issues token → App uses token (scoped access)

1.3 Authorization vs. Authentication

This distinction is critical and frequently confused:

OAuth 2.0 answers: “Is this token allowed to read the user’s calendar?”
OIDC answers: “Which user does this token belong to?”

Important: OAuth 2.0 access tokens are not proof of identity. Never use the presence of a valid access token to conclude you know who the user is.

1.4 Real-World Use Cases

• “Login with Google” / “Login with GitHub” — Technically OpenID Connect (OAuth 2.0 + identity layer)
• Spotify accessing your Facebook friends list — Classic OAuth 2.0 delegated authorization
• A CI/CD pipeline pushing to GitHub — Client Credentials Flow (no user involved)
• Smart TV apps — Device Code Flow (limited input capability)
• Microsoft 365 integrations — Azure AD as the Authorization Server, various flows depending on client type

2. Core Components

2.1 Resource Owner

The Resource Owner is the entity that owns the data or resource being accessed — almost always a human user.

When you click “Allow” on a permission consent screen, you are acting as the Resource Owner, granting permission to a third-party application to access your data.

2.2 Client

The Client is the application requesting access to a protected resource on behalf of the Resource Owner. Clients come in two types based on their ability to keep secrets:

Confidential Clients

Can securely store a client_secret (a password for the application itself). These run on servers the developer controls.

• Examples: Backend web servers, server-side APIs, daemon services
• Can use: Authorization Code Flow, Client Credentials Flow
• Key characteristic: The client_secret never leaves the server

Public Clients

Cannot securely store secrets because the code is exposed to the user’s device or environment.

• Examples: Single Page Applications (SPAs), mobile apps, desktop apps
• Cannot use: Flows requiring client_secret
• Must use: PKCE (Proof Key for Code Exchange) to compensate
• Key characteristic: Any secret embedded in the code can be extracted

2.3 Authorization Server (AS)

The Authorization Server is the trusted party that:

1. Authenticates the Resource Owner (the user logs in here)
2. Presents the consent screen
3. Issues tokens (access tokens, refresh tokens, ID tokens)
4. Validates token requests

Examples: Google Identity Platform, Microsoft Entra ID (Azure AD), Okta, Auth0, Keycloak.

Key endpoints exposed by the AS:

• GET /authorize — starts the authorization flow
• POST /token — exchanges codes/credentials for tokens
• GET /.well-known/openid-configuration — discovery document

2.4 Resource Server (RS)

The Resource Server hosts the protected resources (APIs, data). It:

1. Accepts requests containing access tokens (usually in the Authorization: Bearer <token> header)
2. Validates the token (checks signature, expiry, scope)
3. Returns the resource if the token is valid and has the right scope

The Resource Server and Authorization Server are often operated by the same company but are logically separate components.

2.5 Tokens

Access Token

• Short-lived credential that grants access to specific resources
• Typically expires in 15 minutes to 1 hour
• Sent with every API request: Authorization: Bearer <token>
• Should be treated like a password — never log it, never expose it in URLs

Refresh Token

• Long-lived credential used to obtain new access tokens without re-authenticating
• Expires in days to weeks (or never, depending on configuration)
• Stored securely (httpOnly cookie or secure server-side storage)
• Can be revoked by the Authorization Server
• Only issued in flows where the user is present (not Client Credentials)

ID Token (OIDC)

• A JWT (JSON Web Token) containing claims about the authenticated user
• Only issued when the openid scope is requested
• Not intended to be sent to APIs — it’s for the client application to learn about the user
• Contains: sub (user ID), email, name, iat (issued at), exp (expiry), iss (issuer), aud (audience)

3. OAuth 2.0 Flows (Grant Types)

Different scenarios require different flows. The right flow depends on:

• Who/what is the client? (user present? server-side? IoT device?)
• Can the client keep a secret?
• What level of trust is acceptable?

3.1 Authorization Code Flow

Best for: Confidential clients (server-side web apps) with a user present.

This is the most secure and widely used flow. It never exposes tokens in the browser URL bar.

How It Works (Step by Step)

```text
User          Browser/Client          Authorization Server          Resource Server
  |                  |                         |                          |
  |-- clicks login -->|                         |                          |
  |                  |-- GET /authorize ------->|                          |
  |                  |                         |                          |
  |<--- redirected to AS login page -----------|                          |
  |-- enters credentials --------------------->|                          |
  |<--- consent screen shown ------------------|                          |
  |-- approves ------------------------------->|                          |
  |                  |<-- redirect with code ---|                          |
  |                  |                         |                          |
  |                  |-- POST /token (code) --->|                          |
  |                  |<-- access_token,        |                          |
  |                  |    refresh_token -------|                          |
  |                  |                         |                          |
  |                  |-- API request + Bearer token ---------------------->|
  |                  |<-- protected resource --------------------------------|

#### Step 1: Authorization Request

The client redirects the user's browser to the AS:

```http
GET /authorize?
  response_type=code
  &client_id=myapp-client-id
  &redirect_uri=https://myapp.com/callback
  &scope=read:profile read:email
  &state=xK9mP2qR7vL4nJ1w
HTTP/1.1
Host: auth.example.com

Step 2: Authorization Response

After the user logs in and approves, the AS redirects back:

HTTP/1.1 302 Found
Location: https://myapp.com/callback?
  code=SplxlOBeZQQYbYS6WxSbIA
  &state=xK9mP2qR7vL4nJ1w

The code is short-lived (typically 60 seconds) and single-use.

One thing I really thought about here was: Why don’t we just return the access token here instead of auth code? Seemed redundant. (AS) does not give the access token directly to the browser because the browser is a high-risk environment.

Step 3: Token Exchange

The server-side client exchanges the code for tokens — this is a back-channel request (browser never sees it):

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https://myapp.com/callback

Step 4: Token Response

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8xLOxBtZp8",
  "scope": "read:profile read:email"
}

This token is a Bearer token, and whoever holds it can use it to access the resource server

3.2 Authorization Code Flow with PKCE

Best for: Public clients (SPAs, mobile apps) where a client_secret cannot be kept safe.

PKCE (Proof Key for Code Exchange, pronounced “pixie”) — defined in RFC 7636 — adds a cryptographic challenge to the Authorization Code Flow, preventing code interception attacks.

How PKCE Works

Before starting the flow, the client:

1. Generates a random code_verifier (43–128 character random string)
2. Computes: code_challenge = BASE64URL(SHA256(code_verifier))
3. Sends code_challenge with the authorization request
4. Sends code_verifier with the token request (proves it made the original request)

Even if an attacker intercepts the authorization code, they cannot use it without the code_verifier, which was never sent over the network in plaintext.

Step 1: Generate PKCE Values

// Generate a cryptographically random code_verifier
const code_verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));

// Compute code_challenge
const code_challenge = base64url(await crypto.subtle.digest(
  'SHA-256',
  new TextEncoder().encode(code_verifier)
));

Step 2: Authorization Request (with PKCE)

GET /authorize?
  response_type=code
  &client_id=myapp-spa-client
  &redirect_uri=https://myapp.com/callback
  &scope=read:profile
  &state=xK9mP2qR7vL4nJ1w
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
HTTP/1.1
Host: auth.example.com

Step 3: Token Exchange (with PKCE)

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https://myapp.com/callback
&client_id=myapp-spa-client
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Note: No client_secret — the code_verifier serves as proof of ownership.

The AS recomputes SHA256(code_verifier) and compares it to the stored code_challenge. If they match, it issues tokens.

This flow describes it properly, where client is our server side application.

+--------+          +----------+          +--------------------+          +--------+
|  User  |          | Browser  |          | Client (SP)        |          |  Auth  |
|        |          |          |          |                    |          | Server |
+--------+          +----------+          +--------------------+          +--------+
    |                    |                          |                         |
    | clicks login       |                          |                         |
    |------------------->|                          |                         |
    |                    | GET /login               |                         |
    |                    |------------------------->|                         |
    |                    |                          |                         |
    |                    |                          | gen code_verifier       |
    |                    |                          | gen code_challenge      |
    |                    |                          | = BASE64URL(SHA256(v))  |
    |                    |                          | gen state               |
    |                    |                          |                         |
    |                    |    302 → /authorize      |                         |
    |                    |  ?response_type=code     |                         |
    |                    |  &code_challenge=...     |                         |
    |                    |  &code_challenge_method  |                         |
    |                    |  =S256 &state=...        |                         |
    |                    |<-------------------------|                         |
    |                    |                                                    |
    |                    | GET /authorize?code_challenge=...&state=...        |
    |                    |--------------------------------------------------->|
    |                    |                                                    |
    |                    |              login + consent UI                    |
    |                    |<---------------------------------------------------|
    | enter credentials  |                                                    |
    |  & approve         |                                                    |
    |------------------->|                                                    |
    |                    | credentials                                        |
    |                    |--------------------------------------------------->|
    |                    |                          |                         |
    |                    |                          |          store          |
    |                    |                          |       code_challenge    |
    |                    |                          |       against code      |
    |                    |                          |                         |
    |                    | 302 → /callback?code=AUTH_CODE&state=...           |
    |                    |<---------------------------------------------------|
    |                    | GET /callback?code=AUTH_CODE&state=...             |
    |                    |------------------------->|                         |
    |                    |                          | verify state ✓          |
    |                    |                          |                         |
    |                    |                          | POST /token             |
    |                    |                          | grant_type=auth_code    |
    |                    |                          | &code=AUTH_CODE         |
    |                    |                          | &code_verifier=...      |
    |                    |                          |------------------------>|
    |                    |                          |                         |
    |                    |                          |    SHA256(verifier)     |
    |                    |                          |    == code_challenge? ✓ |
    |                    |                          |                         |
    |                    |                          |   access_token          |
    |                    |                          |   id_token              |
    |                    |                          |   refresh_token         |
    |                    |                          |<------------------------|
    |                    |    set session cookie    |                         |
    |                    |<-------------------------|                         |
    | authenticated ✓    |                          |                         |
    |<-------------------|                          |                         |

3.3 Client Credentials Flow

Best for: Machine-to-machine (M2M) communication with no user involved.

Used by: microservices, background jobs, CI/CD pipelines, daemons.

How It Works

Client (Service)          Authorization Server          Resource Server
      |                          |                           |
      |-- POST /token ---------->|                           |
      |   (client_id +           |                           |
      |    client_secret)        |                           |
      |<-- access_token ---------|                           |
      |                          |                           |
      |-- API request + Bearer token ----------------------->|
      |<-- protected resource --------------------------------|

Token Request

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials
&scope=reports:read metrics:write

Token Response

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "reports:read metrics:write"
}

No refresh_token is issued — the client simply requests a new access token when needed.

3.4 Device Code Flow

Best for: Devices with limited input capability (smart TVs, IoT devices, CLI tools, gaming consoles).

The device cannot open a browser or accept keyboard input, so authentication is delegated to another device (e.g., a phone or laptop).

How It Works

Device                    Auth Server                  User's Phone/Browser
  |                           |                                |
  |-- POST /device_code ----->|                                |
  |<-- device_code,           |                                |
  |    user_code,             |                                |
  |    verification_uri ------|                                |
  |                           |                                |
  |-- display user_code ------|-------- user visits URI ------>|
  |                           |<------- enters user_code ------|
  |                           |<------- user approves ---------|
  |                           |                                |
  |-- poll POST /token ------>|                                |
  |<-- access_token ----------|                                |

Step 1: Device Authorization Request

POST /device_authorization HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

client_id=device-client-id
&scope=read:profile

Step 2: Device Authorization Response

{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://auth.example.com/device",
  "verification_uri_complete": "https://auth.example.com/device?user_code=WDJB-MJHT",
  "expires_in": 900,
  "interval": 5
}

The device displays: “Go to auth.example.com/device and enter code: WDJB-MJHT”

Step 3: Polling for the Token

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS
&client_id=device-client-id

While the user hasn’t approved yet, the AS responds:

{ "error": "authorization_pending" }

Once the user approves, the next poll returns:

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8xLOxBtZp8"
}

3.5 Refresh Token Flow

Access tokens expire. Rather than forcing the user to re-authenticate, the client uses a refresh token to get a new access token silently.

Token Refresh Request

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=refresh_token
&refresh_token=8xLOxBtZp8

Token Refresh Response

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9.NEW...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "9yMPxCuAq9"
}

Some AS implementations use refresh token rotation — each refresh issues a new refresh token and invalidates the old one. This limits the damage if a refresh token is stolen.

3.6 Deprecated Flows (Avoid These)

Implicit Flow (DEPRECATED)

The Authorization Server returned the access token directly in the URL fragment after user approval:

https://myapp.com/callback#access_token=eyJ...&expires_in=3600

Why it’s dangerous and deprecated:

• Access token appears in the browser URL bar — visible in browser history, server logs, and Referer headers
• No state parameter verification was common, enabling CSRF
• No refresh token support
• Replaced entirely by Authorization Code + PKCE for public clients

Resource Owner Password Credentials (ROPC) (DEPRECATED)

The user gives their username and password directly to the client application, which passes them to the AS.

POST /token
grant_type=password&username=user@example.com&password=hunter2&client_id=...

Why it’s dangerous:

• Completely defeats the purpose of OAuth (the client sees credentials)
• No consent screen or scoped access
• Only ever acceptable for first-party apps during migration — even then, avoid it

4. Protocol Internals

4.1 Key Endpoints

/authorize (GET)

Starts user-facing authorization. Browser redirects here.

GET https://auth.example.com/authorize?response_type=code&client_id=...&...

This is where the user logs in and sees the consent screen.

/token (POST)

Back-channel token issuance. Called by the client application directly (not browser redirect).

POST https://auth.example.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&...

/.well-known/openid-configuration (GET)

OIDC Discovery Document — a JSON document listing all AS endpoints, supported scopes, signing algorithms, etc. Use this to configure OAuth clients dynamically.

curl https://accounts.google.com/.well-known/openid-configuration

4.2 Key Parameters

4.3 Scopes and Consent

Scopes are string identifiers representing permissions. There is no universal standard for scope names (except OIDC scopes like openid, profile, email).

Examples:

openid profile email          # OIDC identity scopes
read:repositories             # GitHub
https://www.googleapis.com/auth/gmail.readonly   # Google (URL-style scopes)
user.read Mail.ReadWrite      # Microsoft Graph

The consent screen shown to users maps scopes to human-readable descriptions. Requesting minimal, specific scopes is a security best practice (principle of least privilege).

4.4 Token Formats

Opaque Tokens

• A random string with no inherent meaning
• The Resource Server must call the AS’s introspection endpoint (/introspect) to validate
• Allows the AS to revoke tokens instantly
• More network overhead

# Introspection request
POST /introspect
Authorization: Basic base64(rs_client_id:rs_secret)
token=random_opaque_token_string

JWT (JSON Web Token)

Defined in RFC 7519. Self-contained: the Resource Server can validate without calling the AS.

Structure: header.payload.signature (each Base64URL encoded)

Header:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id-1"
}

Payload (Claims):

{
  "iss": "https://auth.example.com",
  "sub": "user-12345",
  "aud": "https://api.example.com",
  "exp": 1700000000,
  "iat": 1699996400,
  "jti": "unique-token-id",
  "scope": "read:profile read:email"
}

Signature:

RSA_SHA256(
  base64url(header) + "." + base64url(payload),
  private_key
)

4.5 Token Validation (JWT)

A Resource Server validating a JWT must check:

1. Signature — Verify using the AS’s public key (fetched from /jwks endpoint)
2. iss (issuer) — Must match the expected Authorization Server
3. aud (audience) — Must include this Resource Server’s identifier
4. exp (expiry) — Current time must be before expiry
5. iat (issued at) — Should not be too far in the past
6. scope — Token must contain the required scope for the requested operation
7. jti (JWT ID) — Optionally check against a blocklist for replay prevention

5. End-to-End Example

A complete Authorization Code + PKCE flow for a Single Page Application calling a GitHub-style API.

Setup

• Client: Single Page Application at https://myapp.com
• Authorization Server: https://auth.example.com
• Resource Server: https://api.example.com
• Requested scope: repo:read user:profile

Step 1: User Clicks “Connect Account”

The SPA generates PKCE values:

code_verifier  = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
code_challenge = BASE64URL(SHA256(code_verifier))
             = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
state          = "abc123xyz789"   ← stored in sessionStorage

Browser is redirected to:

GET /authorize?
  response_type=code
  &client_id=spa-client-001
  &redirect_uri=https://myapp.com/callback
  &scope=repo:read%20user:profile
  &state=abc123xyz789
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
HTTP/1.1
Host: auth.example.com

What happens: AS presents login page and consent screen to user.

Step 2: User Authenticates and Approves

After the user logs in and clicks “Allow,” the AS redirects back to the SPA:

HTTP/1.1 302 Found
Location: https://myapp.com/callback?
  code=SplxlOBeZQQYbYS6WxSbIA
  &state=abc123xyz789

SPA verifies: state in the redirect matches state stored in sessionStorage.

What happens: SPA now has an authorization code. This code is useless to an attacker without the code_verifier.

Step 3: SPA Exchanges Code for Tokens

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https://myapp.com/callback
&client_id=spa-client-001
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

What the AS does: Recomputes SHA256(code_verifier), compares to stored code_challenge. Match → issues tokens.

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImtleS0xIn0.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyLTEyMzQ1IiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20iLCJleHAiOjE3MDAwMDAzNjAsImlhdCI6MTcwMDAwMDAwMCwic2NvcGUiOiJyZXBvOnJlYWQgdXNlcjpwcm9maWxlIn0.SIGNATURE",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8xLOxBtZp8",
  "scope": "repo:read user:profile"
}

Step 4: SPA Calls the API

GET /user/profile HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImtleS0xIn0...

What the RS does: Validates JWT signature, checks iss, aud, exp, scope. All valid → returns data.

Response:

{
  "id": "user-12345",
  "username": "shaheryar",
  "email": "shaheryar@example.com",
  "repos": [...]
}

Step 5: Access Token Expires — SPA Refreshes

One hour later, the API returns 401 Unauthorized. The SPA uses the refresh token:

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=8xLOxBtZp8
&client_id=spa-client-001

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9.NEW_TOKEN...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "9yMPxCuAq9"
}

The user never had to log in again.

6. Practical Exercises

Exercise 1: Craft an Authorization Request in the Browser

Use Google’s OAuth 2.0 Playground or construct this URL manually and open it:

https://accounts.google.com/o/oauth2/v2/auth?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://oauth2.example.com/code
  &scope=openid%20email%20profile
  &state=random_state_value_here
  &access_type=offline

Observe:

• The Google login/consent screen
• The code parameter in the redirect URL after approval
• The state value echoed back

Exercise 2: Exchange a Code for a Token Using curl

curl -X POST https://oauth2.googleapis.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=YOUR_AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://oauth2.example.com/code"

Or with PowerShell:

$body = @{
    grant_type    = "authorization_code"
    code          = "YOUR_AUTHORIZATION_CODE"
    client_id     = "YOUR_CLIENT_ID"
    client_secret = "YOUR_CLIENT_SECRET"
    redirect_uri  = "https://oauth2.example.com/code"
}

Invoke-RestMethod -Method Post `
    -Uri "https://oauth2.googleapis.com/token" `
    -Body $body

Exercise 3: Decode and Inspect a JWT

Take any JWT (e.g., the access_token from the above exercise) and decode it. Use jwt.io in the browser, or via CLI:

# Split JWT by "." and decode each part
TOKEN="eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyLTEyMzQ1In0.SIGNATURE"

# Decode header
echo $TOKEN | cut -d. -f1 | base64 -d 2>/dev/null | python3 -m json.tool

# Decode payload
echo $TOKEN | cut -d. -f2 | base64 -d 2>/dev/null | python3 -m json.tool

Identify:

• iss — who issued the token
• aud — who the token is for
• exp — when it expires (Unix timestamp → date -d @TIMESTAMP)
• scope — what permissions it grants

Note: You can decode the header and payload without any keys — they’re just Base64. The signature is what you need the public key to verify.

Exercise 4: Identify Parameters in a Real OAuth Request

Capture an OAuth flow using browser DevTools (Network tab) when logging in with Google on any site. Find and identify:

• The GET /authorize request and all query parameters
• The state value sent and returned
• The scope being requested
• The redirect_uri — does it match exactly?
• The POST /token request (may be hidden — it’s server-side)
• Whether PKCE parameters are present (code_challenge, code_challenge_method)

7. Security Deep Dive

This section covers OAuth 2.0 attack vectors, how they work, and how to prevent them. Understanding these is essential for SC-200 and IAM security roles.

7.1 Authorization Code Interception

The Attack

An attacker intercepts the authorization code from the redirect URL before the legitimate client receives it. This can happen via:

• Malicious apps on a mobile device registered to handle the same URI scheme
• Compromised browser extensions
• Network interception if redirect URI uses HTTP

Attack scenario:

1. User approves consent on legitimate app
2. AS redirects: myapp://callback?code=STOLEN_CODE
3. Attacker's malicious app intercepts the redirect (registered same URI)
4. Attacker sends STOLEN_CODE to AS /token endpoint
5. Attacker receives valid access token

Mitigation

PKCE — Even with the code, the attacker cannot exchange it for a token without the code_verifier that was never sent over the network unencrypted. Always use PKCE for public clients.

7.2 Missing or Weak state Parameter (CSRF)

The Attack

If the state parameter is absent or not validated, the flow is vulnerable to Cross-Site Request Forgery.

1. Attacker begins an OAuth flow and gets a valid authorization URL
2. Attacker sends victim a link that completes the attacker's authorization
3. Victim's browser sends the attacker's authorization code to the victim's logged-in session
4. Victim's account is now linked to attacker's external account
5. Attacker can now authenticate as victim

This is called an OAuth CSRF or account linking attack.

Mitigation

• Always generate a cryptographically random state value per authorization request
• Store it server-side or in a secure, HttpOnly cookie
• Reject any callback where state doesn’t match the stored value
• Never use predictable values (state=1, state=userid)

7.3 Open Redirect Abuse

The Attack

If the AS doesn’t strictly validate redirect_uri, an attacker can steal the authorization code by redirecting it to a URL they control:

Attacker crafts:
GET /authorize?client_id=legit-app&redirect_uri=https://attacker.com/steal&...

If AS allows partial/prefix matching:
→ Auth code is delivered to attacker.com

Partial matching is the key vulnerability: if the AS checks only that the redirect_uri starts with the registered domain, https://legit.com.evil.com would pass.

Mitigation

• Exact string matching of redirect_uri against pre-registered values — no wildcards, no prefix matching
• Require redirect URIs to be registered explicitly at client registration
• The AS should reject any mismatch with an error (not silently redirect)

7.4 Token Leakage

The Attack

Access tokens exposed in:

• URL query strings — appear in browser history, server access logs, proxy logs, and Referer headers (?access_token=eyJ...)
• Browser history — Implicit Flow’s fatal flaw
• Log files — if tokens are logged in application logs
• Referer headers — when navigating from a page with a token in the URL

Mitigation

• Never put tokens in URL query parameters
• Use Authorization: Bearer <token> header exclusively
• Set Referrer-Policy: no-referrer on pages that handle tokens
• Ensure tokens are excluded from application and infrastructure logging
• Use short token lifetimes to limit the window of exposure

7.5 PKCE Bypass and Misuse

The Attack

1. No PKCE enforcement: AS accepts token requests without code_verifier even when PKCE was used in the auth request → PKCE is decorative
2. code_challenge_method=plain: Using the verifier as the challenge directly — if an attacker can intercept the auth request, they get the verifier
3. Weak code_verifier: Using a short or low-entropy verifier — vulnerable to brute force

Mitigation

• AS must require code_verifier if code_challenge was sent
• Only allow S256 as code_challenge_method — reject plain
• Enforce minimum code_verifier length (43 characters) and cryptographic randomness
• PKCE should be required for all public clients and recommended for confidential clients too

7.6 Improper Redirect URI Validation

Already partly covered in Open Redirect, but includes additional vectors:

• Subdomain matching: Allowing *.example.com — attacker registers evil.example.com
• Path traversal: https://legit.com/path/../../../ tricks
• Localhost exceptions: Some AS implementations allow any localhost port — attackers run a local service to catch redirects
• HTTP vs HTTPS: Allowing HTTP redirect URIs in production

Mitigation

• Exact string comparison only
• All production redirect URIs must use HTTPS
• Reject loopback (localhost) URIs in production except for native app flows with specific protections

7.7 Scope Over-Permission

The Attack

• Applications requesting * or admin scopes when they only need read access
• Users blindly approving broad scopes they don’t understand
• If the application is compromised, the attacker has access to far more than necessary

Mitigation

• Request minimum necessary scopes for the specific operation
• Implement incremental authorization — request additional scopes only when needed
• AS should present clear, human-readable descriptions of each scope
• Resource Server should verify the specific scope required for each endpoint, not just “is the token valid?”

7.8 Token Replay Attacks

The Attack

If an attacker obtains a valid access token (via leakage, network interception, etc.), they can replay it against the Resource Server for the duration of its lifetime.

Mitigation

• Short token lifetimes (15–60 minutes) limit the replay window
• jti (JWT ID) tracking — maintain a blocklist of used JTIs on the Resource Server
• Sender-constrained tokens — Mutual TLS (mTLS) or DPoP (Demonstrating Proof of Possession) bind tokens to the client’s cryptographic key, making stolen tokens useless without the private key
• Token revocation — AS implements a revocation endpoint; Resource Servers check it or use short lifetimes

7.9 Real-World Attack Scenario: Account Takeover via OAuth

Setup: A web app lets users “Login with Google.” The app links a Google account to a local account by matching email addresses.

Attack:

1. Attacker knows victim's email: victim@gmail.com
2. Attacker creates a Google account with victim@gmail.com (or controls one)
3. Attacker completes OAuth login on the target app using their Google account
4. Target app sees email=victim@gmail.com and logs attacker into victim's account

Root cause: Trusting email from an OAuth provider without verifying it’s been confirmed by that provider, or not checking the sub (user ID) which is unique and stable.

Fix: Always use the immutable sub claim (not email) as the primary identifier for account matching. Email can change; sub cannot.

8. Best Practices

8.1 Flow Selection Guide

Is a user present?
├── YES
│   ├── Is the client a public app (SPA, mobile)?
│   │   └── Authorization Code + PKCE ✓
│   ├── Is the client a server-side app?
│   │   └── Authorization Code (+ PKCE recommended) ✓
│   └── Is the device input-constrained (TV, CLI)?
│       └── Device Code Flow ✓
└── NO (machine-to-machine)
    └── Client Credentials Flow ✓

NEVER USE:
- Implicit Flow (deprecated)
- ROPC / Password Grant (deprecated)

8.2 Token Security

8.3 Authorization Server Configuration

• Enforce exact redirect_uri matching
• Require PKCE for all public clients
• Set maximum authorization code lifetime to 60 seconds
• Implement authorization code single-use enforcement
• Enable refresh token rotation and absolute expiration
• Publish a /.well-known/openid-configuration discovery document
• Rotate signing keys regularly and publish via JWKS endpoint

8.4 Resource Server Implementation

• Validate every claim in the JWT: iss, aud, exp, scope
• Verify the JWT signature using the AS’s public key from the JWKS endpoint (cache with TTL, don’t fetch on every request)
• Check the specific scope required for each API endpoint
• Return WWW-Authenticate: Bearer error="insufficient_scope" on scope failure
• Return WWW-Authenticate: Bearer error="invalid_token" on token failure

8.5 Modern Recommendations Summary

• ✅ Always use PKCE — even for confidential clients (defense in depth)
• ✅ Use short-lived access tokens with refresh tokens
• ✅ Use state parameter — always generate and validate it
• ✅ Use nonce (in OIDC flows) to prevent ID token replay
• ✅ Request minimal scopes — principle of least privilege
• ✅ Use exact redirect URI matching — no wildcards, no prefix matching
• ✅ Implement token binding (DPoP or mTLS) for high-security environments
• ✅ Use refresh token rotation — single-use refresh tokens
• ❌ Never use Implicit Flow
• ❌ Never use ROPC/Password Grant
• ❌ Never put tokens in query strings
• ❌ Never store tokens in localStorage (use HttpOnly cookies or memory)

Quick Reference: OAuth 2.0 at a Glance

ACTORS:
  Resource Owner     → The user who owns the data
  Client             → The app wanting access
  Authorization Server → Issues tokens (Google, Azure AD, Okta...)
  Resource Server    → The API holding the protected data

TOKENS:
  Access Token       → Short-lived, sent to APIs (Bearer header)
  Refresh Token      → Long-lived, gets new access tokens
  ID Token (OIDC)    → JWT with user identity claims

FLOWS:
  Auth Code + PKCE   → User-facing flows (preferred for all clients)
  Client Credentials → M2M, no user
  Device Code        → Input-constrained devices
  Refresh Token      → Silent token renewal

SECURITY MUSTS:
  ✓ PKCE
  ✓ state parameter
  ✓ Exact redirect_uri matching
  ✓ Short token lifetimes
  ✓ HTTPS everywhere
  ✓ Validate ALL JWT claims

References

• RFC 6749 — The OAuth 2.0 Authorization Framework
• RFC 7636 — PKCE for OAuth Public Clients
• RFC 7519 — JSON Web Token (JWT)
• RFC 8628 — OAuth 2.0 Device Authorization Grant
• RFC 9068 — JWT Profile for OAuth 2.0 Access Tokens
• OAuth 2.0 Security Best Current Practice (BCP)
• OWASP — Testing for OAuth Weaknesses
• jwt.io — JWT Debugger
• OAuth 2.0 Playground (Google)

1. Context and Positioning

1.1 OIDC as a Layer, Not a Replacement

OpenID Connect (specification) is a thin identity layer built on top of OAuth 2.0. It does not replace OAuth 2.0 — it extends it by answering the question OAuth deliberately avoided:

“Who is the user that just authorized this request?”

The extension is minimal by design:

• Adds a new token type: the ID Token (a signed JWT asserting user identity)
• Adds a new scope: openid (signals to the AS that OIDC is being used)
• Adds a new endpoint: UserInfo (for fetching additional identity claims)
• Adds new parameters: nonce, prompt, max_age, acr_values, login_hint
• Standardizes a discovery document and JWKS endpoint

Every other mechanism — flows, token endpoint, PKCE, redirect URIs, client registration — is inherited from OAuth 2.0 unchanged.

1.2 The Protocol Boundary

The separation is precise:

This boundary is not cosmetic. Confusing the two — using an access token as proof of identity, or sending an ID Token to an API — is a significant security mistake covered in Section 9.

1.3 Adoption and Ecosystem

OIDC is the dominant federated identity protocol for modern web, mobile, and cloud systems. It underpins:

• Google Identity Platform, Microsoft Entra ID (Azure AD), Apple Sign In
• Enterprise SSO (Okta, Auth0, Ping Identity, Keycloak)
• Kubernetes service account tokens (projected volumes)
• GitHub Actions OIDC tokens for cloud federation
• AWS IAM Identity Center, GCP Workload Identity Federation

2. OIDC Architecture and Components

2.1 Identity Provider (IdP) vs Authorization Server

In pure OAuth 2.0, the Authorization Server (AS) issues access tokens and manages consent. In OIDC, this same server takes on an additional role: Identity Provider (IdP).

The conceptual difference:

In most deployments, a single server plays both roles simultaneously. The distinction matters architecturally because:

• An AS can exist without being an IdP (pure OAuth 2.0 deployment)
• An IdP must implement OAuth 2.0 as its transport layer (per OIDC spec)
• Some enterprise architectures federate a separate IdP (e.g., an on-premises Active Directory Federation Services) into a cloud AS (e.g., Azure AD), creating a chain

2.2 Relying Party (RP) vs OAuth Client

In OIDC, the OAuth Client is referred to as the Relying Party (RP). The terminological shift is intentional: the RP relies on the IdP’s assertion of identity.

Behavioral differences from a pure OAuth client:

• The RP must validate the ID Token — this is non-optional and precisely specified in the spec
• The RP tracks session state and may initiate logout via the RP-initiated logout protocol
• The RP must handle the nonce parameter: generate it, bind it to the session, and verify it in the ID Token
• The RP is registered with the IdP with additional metadata beyond standard OAuth client registration (e.g., id_token_signed_response_alg, userinfo_encrypted_response_alg)

2.3 UserInfo Endpoint vs ID Token

OIDC provides two ways to receive identity claims about the user. They serve different purposes:

When to use which:

• Use the ID Token for authentication decisions (who logged in, when, how)
• Use the UserInfo endpoint for profile data you need but that doesn’t need to be embedded in every token (avoids bloating tokens)
• Never use UserInfo data for making authentication decisions — it’s not cryptographically bound to the authentication event the same way the ID Token is

2.4 Trust Model and Metadata Discovery

The trust relationship in OIDC flows through:

1. Client Registration — The RP registers with the IdP (statically or dynamically via RFC 7591). The IdP issues client_id and optionally client_secret. Redirect URIs, allowed scopes, and token signing algorithms are registered here.

2. Discovery — The RP retrieves the IdP’s metadata from /.well-known/openid-configuration (covered in Section 5). This document anchors all subsequent trust decisions.

3. JWKS — The RP fetches the IdP’s public signing keys from the jwks_uri in the discovery document. All ID Token signatures are verified against these keys.

4. Issuer Binding — The iss claim in the ID Token must match the issuer in the discovery document. This is the root of the trust chain.

RP trusts IdP's discovery document
  → retrieves signing keys from jwks_uri
  → verifies ID Token signature with those keys
  → validates iss matches the trusted issuer
  → trusts the identity claims in the token

3. ID Token Deep Dive

The ID Token is the defining artifact of OIDC. It is a JWS (JSON Web Signature) — a signed JWT — that asserts the identity of the authenticated user.

3.1 JWT Structure

A JWT has three components, each Base64URL-encoded and concatenated with .:

BASE64URL(header) . BASE64URL(payload) . BASE64URL(signature)

Header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "signing-key-2024-01"
}

Payload (Claims)

{
  "iss": "https://auth.example.com",
  "sub": "user-a1b2c3d4",
  "aud": "myapp-client-id",
  "exp": 1700003600,
  "iat": 1700000000,
  "auth_time": 1699999800,
  "nonce": "n-0S6_WzA2Mj",
  "azp": "myapp-client-id",
  "at_hash": "MTIzNDU2Nzg5MDEyMzQ",
  "c_hash": "LDktKdoQak3Pk0cnXxCltA",
  "acr": "urn:mace:incommon:iap:silver",
  "amr": ["pwd", "mfa"],
  "name": "Shaheryar Ahmed",
  "email": "shaheryar@example.com",
  "email_verified": true
}

Signature

RSA_SHA256(
  base64url(header) + "." + base64url(payload),
  IdP_private_key
)

The signature is verified by the RP using the IdP’s public key retrieved from the JWKS endpoint.

3.2 Required and Optional Claims

Required Claims (MUST be present in every ID Token)

Conditionally Required Claims

Optional but Commonly Used Claims

Standard Profile Claims (from profile scope)

name, given_name, family_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at

Standard Email Claims (from email scope)

email, email_verified

Standard Phone Claims (from phone scope)

phone_number, phone_number_verified

3.3 Token Signing (JWS) and Optional Encryption (JWE)

JWS (JSON Web Signature) — The Default

All ID Tokens MUST be signed. Supported algorithms:

The RP must be configured to accept only specific alg values. Accepting alg from the token header without validation is a critical vulnerability.

JWE (JSON Web Encryption) — Optional

For sensitive deployments, the ID Token can additionally be encrypted (producing a JWE). The encryption wraps the entire JWS:

JWE(JWS(payload)) → encrypted ID Token

The RP registers its public encryption key with the IdP. The IdP encrypts the JWS using the RP’s public key. Only the RP can decrypt it with its private key.

Relevant fields when encryption is used:

• id_token_encrypted_response_alg — key agreement algorithm (e.g., RSA-OAEP)
• id_token_encrypted_response_enc — content encryption algorithm (e.g., A256GCM)

JWE is rare in practice but important for high-assurance or regulated environments where token contents must not be visible to intermediaries.

3.4 Key Rotation and JWKS Endpoint

The IdP regularly rotates its signing keys. The JWKS (JSON Web Key Set) endpoint exposes all current public keys:

GET /jwks HTTP/1.1
Host: auth.example.com

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "signing-key-2024-01",
      "alg": "RS256",
      "n": "pjdss8ZaDfEH6K6U7GeW2nxDqR4IP049fk1fK0lndimbMMVBdPv_hSpm8T8EtBDxrUdi1OHZfMhUixGyw...",
      "e": "AQAB"
    },
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "signing-key-2024-02",
      "alg": "RS256",
      "n": "new-key-modulus...",
      "e": "AQAB"
    }
  ]
}

Key rotation process:

1. IdP generates a new key pair, publishes new public key in JWKS (alongside old key)
2. IdP begins signing new tokens with the new private key
3. Old tokens (signed with old key) remain verifiable using the old public key still in JWKS
4. After old tokens expire, IdP removes old public key from JWKS

RP caching strategy:

• Cache JWKS with a reasonable TTL (e.g., 1 hour)
• If signature verification fails with cached keys, re-fetch JWKS once and retry
• Do not re-fetch on every token validation (DDoS risk to IdP)
• Use kid from the token header to select the correct key — avoid trying all keys

3.5 Sample ID Token — Full Annotated Example

Encoded:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InNpZ25pbmcta2V5LTIwMjQtMDEifQ
.
eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyLWExYjJjM2Q0IiwiYXVkIjoibXlhcHAtY2xpZW50LWlkIiwiZXhwIjoxNzAwMDAzNjAwLCJpYXQiOjE3MDAwMDAwMDAsImF1dGhfdGltZSI6MTY5OTk5OTgwMCwibm9uY2UiOiJuLTBTNl9XekEyTWoiLCJhenAiOiJteWFwcC1jbGllbnQtaWQiLCJhdF9oYXNoIjoiTVRJek5EVTJOemM0T1RBeE1qTTAiLCJhY3IiOiJ1cm46bWFjZTppbmNvbW1vbjppYXA6c2lsdmVyIiwiYW1yIjpbInB3ZCIsIm1mYSJdLCJuYW1lIjoiU2hhaGVyeWFyIEFobWVkIiwiZW1haWwiOiJzaGFoZXJ5YXJAZXhhbXBsZS5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZX0
.
SIGNATURE

Decoded Payload:

{
  "iss": "https://auth.example.com",      // Issuer — must match discovery doc
  "sub": "user-a1b2c3d4",                 // Stable, opaque user ID — use this, not email
  "aud": "myapp-client-id",               // Audience — must match this RP's client_id
  "exp": 1700003600,                      // Expires: 2023-11-14T22:13:20Z
  "iat": 1700000000,                      // Issued: 2023-11-14T21:13:20Z (1 hour token)
  "auth_time": 1699999800,                // User actually authenticated 200s before issuance
  "nonce": "n-0S6_WzA2Mj",               // Must match nonce sent in auth request
  "azp": "myapp-client-id",              // Authorized party (same as aud here)
  "at_hash": "MTIzNDU2Nzg5MDEyMzQ",     // Binds this ID Token to the access token
  "acr": "urn:mace:incommon:iap:silver", // Authentication assurance level
  "amr": ["pwd", "mfa"],                  // Authenticated via password + MFA
  "name": "Shaheryar Ahmed",              // From profile scope
  "email": "shaheryar@example.com",       // From email scope
  "email_verified": true                  // IdP has confirmed this email
}

4. OIDC Flow Internals

OIDC uses the same underlying flows as OAuth 2.0 but modifies their behavior. The openid scope is what triggers OIDC behavior at the Authorization Server.

4.1 Authorization Code Flow (OIDC Context)

This is the standard OIDC flow. Identical to OAuth 2.0 Authorization Code Flow with OIDC-specific additions.

What changes compared to pure OAuth 2.0:

• openid is required in scope
• nonce should be sent (required if response_type includes id_token)
• Token endpoint returns an id_token in addition to access_token
• The RP must validate the ID Token before trusting any identity claims

Step 1: Authorization Request

GET /authorize?
  response_type=code
  &client_id=myapp-client-id
  &redirect_uri=https://myapp.com/callback
  &scope=openid%20profile%20email
  &state=xK9mP2qR7vL4nJ1w
  &nonce=n-0S6_WzA2Mj
  &prompt=login
  &max_age=3600
HTTP/1.1
Host: auth.example.com

The nonce value must be:

• Cryptographically random (≥128 bits of entropy)
• Stored server-side or in a secure, HttpOnly session cookie
• Verified against the nonce claim in the returned ID Token

Step 2: Token Exchange

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(myapp-client-id:client_secret)

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https://myapp.com/callback

Step 3: Token Response (OIDC)

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9.ACCESS...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8xLOxBtZp8",
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNpZ25pbmcta2V5LTIwMjQtMDEifQ.eyJpc3MiOi...",
  "scope": "openid profile email"
}

The id_token is exclusively in the token endpoint response. It is never sent to the Resource Server.

ID Token Validation (Step 4 — Critical)

Full validation process covered in Section 7. At minimum:

1. Verify the signature
2. Verify iss, aud, exp, iat
3. Verify nonce matches what was sent
4. If at_hash is present, verify it against the access token

4.2 Authorization Code + PKCE (Recommended Modern Flow)

PKCE and OIDC are independent extensions to OAuth 2.0. They compose seamlessly and should always be used together for public clients.

How They Interact

PKCE protects the authorization code from being stolen and exchanged by an attacker. OIDC adds the ID Token to the token response. Together:

• PKCE prevents code interception → attacker can’t get tokens at all
• OIDC nonce prevents replay → even if an old ID Token is captured, it can’t be replayed into a new session
• at_hash in the ID Token cryptographically binds the ID Token to the specific access token issued — prevents token substitution

Request (Combined PKCE + OIDC)

GET /authorize?
  response_type=code
  &client_id=myapp-spa
  &redirect_uri=https://myapp.com/callback
  &scope=openid%20profile%20email
  &state=xK9mP2qR7vL4nJ1w
  &nonce=n-0S6_WzA2Mj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
HTTP/1.1
Host: auth.example.com

The nonce serves a different purpose than state:

• state → CSRF protection for the OAuth redirect
• nonce → replay protection for the ID Token itself

Both must be present and validated.

4.3 Hybrid Flow

The Hybrid Flow allows the RP to receive some tokens from the authorization endpoint (via redirect) and other tokens from the token endpoint (via back-channel). It is defined by using specific response_type combinations.

response_type Values

The most common Hybrid Flow uses code id_token:

GET /authorize?
  response_type=code%20id_token
  &client_id=myapp-client-id
  &redirect_uri=https://myapp.com/callback
  &scope=openid%20profile
  &state=xK9mP2qR7vL4nJ1w
  &nonce=n-0S6_WzA2Mj
HTTP/1.1
Host: auth.example.com

Response (via fragment):

https://myapp.com/callback#
  code=SplxlOBeZQQYbYS6WxSbIA
  &id_token=eyJhbGciOiJSUzI1NiJ9...
  &state=xK9mP2qR7vL4nJ1w

The id_token returned from the authorization endpoint contains a c_hash claim:

{
  "c_hash": "LDktKdoQak3Pk0cnXxCltA"
}

c_hash = Base64URL(left_half(SHA256(authorization_code)))

The RP verifies c_hash against the received code before using either. This binds the ID Token to the code, preventing substitution attacks.

Security Implications of Hybrid Flow

• Tokens returned in the authorization endpoint response travel via browser redirect (URL fragment or query string) — higher exposure risk
• The ID Token from the auth endpoint typically has fewer claims (it’s a “hint”) — the full ID Token with all claims comes from the token endpoint
• c_hash and at_hash are the critical security bindings — if validation is skipped, token substitution becomes possible
• Modern recommendation: Avoid Hybrid Flow unless there is a specific architectural reason. Authorization Code + PKCE achieves the same security goals with less complexity.

4.4 Implicit Flow (Historical)

In OIDC Implicit Flow, the ID Token (and optionally access token) were returned directly from the authorization endpoint via URL fragment:

https://myapp.com/callback#
  id_token=eyJhbGciOiJSUzI1NiJ9...
  &access_token=SlAV32hkKG
  &token_type=Bearer
  &expires_in=3600
  &state=xK9mP2qR7vL4nJ1w

Why it existed: Before PKCE, public clients had no secure way to use the Authorization Code Flow (no secret to authenticate the token exchange). The Implicit Flow removed the token exchange step entirely.

Why it is deprecated:

• ID Token in URL fragment → appears in browser history, server logs, proxy logs, Referer headers
• No refresh token support
• No c_hash or at_hash validation possible in the auth endpoint response for response_type=id_token
• PKCE makes it entirely unnecessary

What replaced it: Authorization Code + PKCE for all public clients.

5. Protocol Endpoints and Discovery

5.1 /.well-known/openid-configuration

The OIDC discovery document is a JSON document served at a well-known URL. It is the foundation of the trust model — the RP fetches this document to configure itself.

GET /.well-known/openid-configuration HTTP/1.1
Host: auth.example.com

Sample Discovery Document

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/authorize",
  "token_endpoint": "https://auth.example.com/token",
  "userinfo_endpoint": "https://auth.example.com/userinfo",
  "jwks_uri": "https://auth.example.com/jwks",
  "registration_endpoint": "https://auth.example.com/register",
  "end_session_endpoint": "https://auth.example.com/logout",
  "revocation_endpoint": "https://auth.example.com/revoke",
  "introspection_endpoint": "https://auth.example.com/introspect",
  "device_authorization_endpoint": "https://auth.example.com/device_authorization",

  "scopes_supported": ["openid", "profile", "email", "phone", "offline_access"],
  "response_types_supported": ["code", "id_token", "code id_token", "code token"],
  "response_modes_supported": ["query", "fragment", "form_post"],
  "grant_types_supported": ["authorization_code", "refresh_token", "client_credentials"],

  "id_token_signing_alg_values_supported": ["RS256", "ES256"],
  "id_token_encryption_alg_values_supported": ["RSA-OAEP"],
  "id_token_encryption_enc_values_supported": ["A256GCM"],

  "userinfo_signing_alg_values_supported": ["RS256"],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "private_key_jwt"
  ],

  "subject_types_supported": ["public", "pairwise"],
  "claim_types_supported": ["normal", "aggregated", "distributed"],
  "claims_supported": [
    "sub", "iss", "aud", "exp", "iat", "auth_time", "nonce",
    "name", "email", "email_verified", "phone_number"
  ],

  "code_challenge_methods_supported": ["S256"],
  "request_parameter_supported": true,
  "request_uri_parameter_supported": true,
  "require_request_uri_registration": true,

  "frontchannel_logout_supported": true,
  "backchannel_logout_supported": true,
  "backchannel_logout_session_supported": true
}

Key Fields Explained

5.2 Dynamic Discovery Process

1. RP is configured with the IdP’s issuer URL (e.g., https://auth.example.com)
2. RP constructs the discovery URL: {issuer}/.well-known/openid-configuration
3. RP fetches and caches the document
4. RP extracts endpoint URLs and supported capabilities
5. RP configures itself (sets authorization_endpoint, token_endpoint, jwks_uri, etc.)

This makes OIDC self-configuring — changing an IdP’s endpoint URLs only requires updating the discovery document, not reconfiguring every RP.

5.3 JWKS Endpoint

Covered in Section 3.4. Key operational notes:

• The JWKS response may contain multiple keys (different kid values, key rotation overlap)
• The RP selects the key matching the kid in the token header
• If no matching kid is found, refresh the JWKS and retry once
• JWKS responses should be cached (respect Cache-Control headers, or default to ~1 hour TTL)

5.4 UserInfo Endpoint

GET /userinfo HTTP/1.1
Host: auth.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.ACCESS_TOKEN...

{
  "sub": "user-a1b2c3d4",
  "name": "Shaheryar Ahmed",
  "given_name": "Shaheryar",
  "family_name": "Ahmed",
  "email": "shaheryar@example.com",
  "email_verified": true,
  "phone_number": "+92-300-1234567",
  "picture": "https://example.com/users/shaheryar/photo.jpg"
}

Critical: The sub in the UserInfo response MUST match the sub in the ID Token. If they don’t match, the RP must reject the response — this would indicate a response substitution attack.

The UserInfo response can also be returned as a signed JWT (if the IdP supports userinfo_signed_response_alg), providing authenticity guarantees beyond the TLS transport.

5.5 Token Endpoint Differences in OIDC

The token endpoint behaves identically to OAuth 2.0 with one addition: when openid is in scope, the response includes id_token.

Client authentication methods at the token endpoint:

private_key_jwt is the recommended method for confidential clients in high-security deployments. The client signs a JWT assertion with its private key; the IdP verifies with the registered public key. This eliminates the need to share any secret.

6. Advanced Parameters and Behavior

6.1 nonce

The nonce is a string value sent by the RP in the authorization request. The IdP embeds it verbatim in the ID Token as the nonce claim.

Purpose: Binds the ID Token to a specific authentication request, preventing ID Token replay attacks.

Lifecycle:

1. RP generates: nonce = cryptographically_random_string()
2. RP stores: session["nonce"] = nonce  (server-side, never in URL)
3. RP includes in auth request: &nonce=<value>
4. IdP embeds in ID Token: { "nonce": "<value>" }
5. RP validates: assert id_token_claims["nonce"] == session["nonce"]
6. RP invalidates: delete session["nonce"]  (single-use)

A nonce that is reused, predictable, or not validated defeats replay protection. The nonce must be:

• Cryptographically random (min 128 bits)
• Single-use (invalidated after one verification)
• Stored in a server-side session or HttpOnly cookie (not in localStorage)

6.2 state

Inherited from OAuth 2.0. In OIDC context: still for CSRF protection of the authorization redirect. Distinct from nonce — they protect different things at different layers.

state → protects the OAuth redirect (is this callback expected?)
nonce → protects the ID Token (is this token for this session?)

Both must be present. Both must be validated.

6.3 prompt

Controls whether the IdP forces the user to interact, regardless of existing session state.

prompt=none use case — silent token refresh in SPAs:

GET /authorize?
  response_type=code
  &client_id=myapp-spa
  &redirect_uri=https://myapp.com/silent-callback
  &scope=openid
  &prompt=none
  &nonce=new-nonce
  &code_challenge=...

This is done in a hidden iframe. If the user has an active session at the IdP, a new ID Token is issued silently. If not, the error is caught and the user is redirected to login.

6.4 max_age

Specifies the maximum elapsed time (in seconds) since the user’s last active authentication. If auth_time in the ID Token indicates the user authenticated longer ago than max_age, the IdP must re-authenticate the user.

GET /authorize?...&max_age=900

If max_age=900, the IdP must ensure the user authenticated within the last 15 minutes. If not, it forces re-login before issuing the token.

The RP must also validate: current_time - auth_time ≤ max_age on the received ID Token.

6.5 acr_values

Authentication Context Class Reference. The RP requests a specific assurance level for authentication:

GET /authorize?...&acr_values=urn:mace:incommon:iap:silver%20urn:mace:incommon:iap:bronze

(Space-separated list, ordered by preference.)

The IdP includes the actual acr achieved in the ID Token:

{ "acr": "urn:mace:incommon:iap:silver" }

Common ACR values:

• urn:mace:incommon:iap:bronze — password only
• urn:mace:incommon:iap:silver — password + second factor
• urn:mace:incommon:iap:gold — hardware token or biometric

The RP should verify the acr in the ID Token meets its minimum requirement for the requested operation.

6.6 login_hint

A hint to the IdP about which user is attempting to authenticate. Typically an email address or username. Allows the IdP to pre-populate the login form.

GET /authorize?...&login_hint=user%40example.com

This is only a hint — the IdP may ignore it. The authenticated user’s identity is always taken from the sub in the ID Token, not from login_hint.

6.7 response_type and response_mode

response_type defines which tokens are returned and from which endpoint (authorization or token). See Section 4.3 for the full table.

response_mode defines how the authorization endpoint delivers its response to the RP:

For response_type=code, prefer response_mode=form_post in high-security deployments to prevent authorization codes from appearing in server logs.

6.8 Scope Semantics in OIDC

Claims may be delivered in the ID Token directly, from the UserInfo endpoint, or both — depending on IdP configuration. RPs should request claims from UserInfo for large payloads (avoids bloating tokens stored in session state).

7. Token Validation and Trust Chain

7.1 Full ID Token Validation Process

The RP MUST perform all of these checks. Skipping any is a security vulnerability.

Step 1: Decrypt (if encrypted)
  - If id_token is a JWE, decrypt using the RP's private key
  - The result is the underlying JWS

Step 2: Parse the JWT
  - Split by "."
  - Base64URL-decode header and payload (no key needed)
  - Do NOT trust claims until signature is verified

Step 3: Algorithm check
  - header["alg"] must be an algorithm the RP is configured to accept
  - REJECT if alg == "none"
  - REJECT if alg is not in the RP's allowlist

Step 4: Key selection
  - Use header["kid"] to select the key from the cached JWKS
  - If kid is not found, re-fetch JWKS once and retry
  - If still not found, REJECT

Step 5: Signature verification
  - Verify the JWT signature using the selected public key
  - REJECT if verification fails

Step 6: Issuer validation
  - payload["iss"] must exactly match the expected issuer
  - The expected issuer comes from the discovery document, not from the token itself
  - REJECT if mismatch

Step 7: Audience validation
  - payload["aud"] must contain the RP's client_id
  - If payload["aud"] is an array with multiple entries, verify payload["azp"] == client_id
  - REJECT if client_id is not in aud

Step 8: Expiry validation
  - current_time < payload["exp"]  (allow a small clock skew: ≤ 60 seconds)
  - REJECT if token is expired

Step 9: Issued-at validation
  - payload["iat"] should not be too far in the past (IdP-dependent, but flag if > 5 minutes old at receipt)
  - This is advisory, not strictly required, but helps detect old tokens

Step 10: Nonce validation (REQUIRED if nonce was sent)
  - payload["nonce"] must exactly match the nonce stored in the RP's session
  - REJECT if mismatch or if nonce is absent when it was sent in the request
  - Invalidate the stored nonce (single-use)

Step 11: auth_time validation (if max_age was sent)
  - current_time - payload["auth_time"] ≤ max_age (+ clock skew tolerance)
  - REJECT if the user authenticated too long ago

Step 12: acr validation (if acr_values was sent)
  - payload["acr"] must meet the minimum assurance level required
  - REJECT if the achieved acr is insufficient

Step 13: at_hash validation (if access_token was also received)
  - Compute: expected_at_hash = base64url(left_half(sha256(access_token)))
  - payload["at_hash"] must match expected_at_hash
  - REJECT if mismatch

Step 14: c_hash validation (Hybrid Flow, if code was also received)
  - Compute: expected_c_hash = base64url(left_half(sha256(code)))
  - payload["c_hash"] must match expected_c_hash
  - REJECT if mismatch

Only after all steps pass should the RP consider the authentication successful and trust the sub and other identity claims.

7.2 ID Token vs Access Token Validation

A common misconfiguration: sending the ID Token to an API as a Bearer token. This is wrong because:

• The aud of the ID Token is the client, not the API
• The API would need to accept tokens with a different audience claim
• It blurs the authentication/authorization boundary

7.3 Local vs Remote Validation

For most deployments: use local JWT validation with short token lifetimes (15–60 min) to bound the revocation window. Implement introspection for high-assurance scenarios where immediate revocation is required.

8. End-to-End OIDC Exchange

A complete Authorization Code + PKCE + OIDC flow for a confidential web application.

Setup:

• IdP: https://auth.example.com
• RP: https://myapp.com (server-side, confidential client)
• client_id: myapp-client-id
• Requested scopes: openid profile email offline_access

Step 1: Discovery (RP startup / cached)

GET /.well-known/openid-configuration HTTP/1.1
Host: auth.example.com

RP extracts and caches authorization_endpoint, token_endpoint, jwks_uri, userinfo_endpoint.

Step 2: PKCE and Nonce Generation (RP, server-side)

code_verifier  = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
code_challenge = BASE64URL(SHA256(code_verifier))
             = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
state          = "xK9mP2qR7vL4nJ1w"
nonce          = "n-0S6_WzA2Mj"

RP stores state, nonce, and code_verifier in the user’s server-side session (not in the browser).

Step 3: Authorization Request

RP redirects the user’s browser:

GET /authorize?
  response_type=code
  &client_id=myapp-client-id
  &redirect_uri=https%3A%2F%2Fmyapp.com%2Fcallback
  &scope=openid%20profile%20email%20offline_access
  &state=xK9mP2qR7vL4nJ1w
  &nonce=n-0S6_WzA2Mj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &prompt=login
  &max_age=86400
HTTP/1.1
Host: auth.example.com

Internal: IdP records code_challenge, nonce, and session metadata. Displays login + consent UI.

Step 4: User Authenticates and Consents

User enters credentials, completes MFA, clicks “Allow.” IdP generates a short-lived authorization code.

Step 5: Authorization Response

HTTP/1.1 302 Found
Location: https://myapp.com/callback?
  code=SplxlOBeZQQYbYS6WxSbIA
  &state=xK9mP2qR7vL4nJ1w

RP Action: Verify state matches session. Extract code.

Step 6: Token Exchange

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic bXlhcHAtY2xpZW50LWlkOmNsaWVudC1zZWNyZXQ=

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fmyapp.com%2Fcallback
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

IdP Action: Verifies client_id/client_secret. Recomputes SHA256(code_verifier) and compares to stored code_challenge. Match confirmed. Generates tokens.

Step 7: Token Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNpZ25pbmcta2V5LTIwMjQtMDEifQ.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyLWExYjJjM2Q0IiwiYXVkIjoiaHR0cHM6Ly9hcGkubXlhcHAuY29tIiwiZXhwIjoxNzAwMDAzNjAwLCJpYXQiOjE3MDAwMDAwMDAsInNjb3BlIjoicHJvZmlsZSBlbWFpbCJ9.ACCESS_SIG",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8xLOxBtZp8",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InNpZ25pbmcta2V5LTIwMjQtMDEifQ.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyLWExYjJjM2Q0IiwiYXVkIjoibXlhcHAtY2xpZW50LWlkIiwiZXhwIjoxNzAwMDAzNjAwLCJpYXQiOjE3MDAwMDAwMDAsImF1dGhfdGltZSI6MTY5OTk5OTgwMCwibm9uY2UiOiJuLTBTNl9XekEyTWoiLCJhdF9oYXNoIjoiTVRJek5EVTJOemM0T1RBeE1qTTAiLCJhY3IiOiJ1cm46bWFjZTppbmNvbW1vbjppYXA6c2lsdmVyIiwiYW1yIjpbInB3ZCIsIm1mYSJdLCJuYW1lIjoiU2hhaGVyeWFyIEFobWVkIiwiZW1haWwiOiJzaGFoZXJ5YXJAZXhhbXBsZS5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZX0.ID_TOKEN_SIG",
  "scope": "openid profile email offline_access"
}

Step 8: ID Token Validation (RP)

RP performs all checks from Section 7.1:

✓ Fetch JWKS from https://auth.example.com/jwks
✓ Select key with kid="signing-key-2024-01"
✓ Verify RS256 signature
✓ iss == "https://auth.example.com"  ✓
✓ aud == "myapp-client-id"  ✓
✓ exp (1700003600) > current_time (1700000060)  ✓
✓ nonce == "n-0S6_WzA2Mj" matches session  ✓  → invalidate stored nonce
âerified against access_token  ✓
✓ auth_time: 1699999800 — authenticated 200s ago, within max_age=86400  ✓
✓ acr: "silver" — MFA confirmed  ✓
→ Authentication successful. User identity: sub=user-a1b2c3d4

Step 9: Optional UserInfo Call

GET /userinfo HTTP/1.1
Host: auth.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.ACCESS_TOKEN...

{
  "sub": "user-a1b2c3d4",
  "name": "Shaheryar Ahmed",
  "given_name": "Shaheryar",
  "family_name": "Ahmed",
  "email": "shaheryar@example.com",
  "email_verified": true,
  "picture": "https://auth.example.com/users/user-a1b2c3d4/photo.jpg"
}

RP Action: Verify sub matches ID Token sub. If mismatch → REJECT. Otherwise, use additional profile data.

9. Security Deep Dive

9.1 ID Token Replay Attacks (Nonce Misuse)

The Attack

An attacker captures a valid ID Token (from logs, from a compromised RP, or from a previous authentication). They inject this token into a new authentication session.```

1. Victim authenticates → IdP issues ID Token with nonce=”A”
2. Attacker captures the ID Token (e.g., from logs)
3. Attacker later initiates a new auth flow with the RP
4. Attacker intercepts the callback and substitutes the captured ID Token
5. If RP doesn’t validate nonce, RP accepts the old token as fresh authentication ```

Impact

Authentication bypass. Attacker is logged in as the victim.

Mitigation

• Always generate and validate nonce
• The nonce in the ID Token must match the o generated for that specific authentication session
• Nonces must be single-use — invalidate after successful validation
• Nonces must be cryptographically random (not sequential or user-derived)

9.2 Improper ID Token Validation

The Attack

RPs that partially validate ID Tokens — or skip validation entirely when tokens are received from “trusted” sources — are vulnerable.

Common omissions:

• Skipping signature verification (“we got it from the HTTPS token endpoint, it must be safe”) validating aud — token from one RP accepted by another
• Not validating exp — accepting expired tokens
• Not validating nonce

Impact

• Missing aud check → token issued for App A is accepted by App B (cross-site token confusion)
• Missing exp check → stolen tokens usable indefinitely
• Missing signature check → forged tokens accepted

Mitigation

Execute all 14 validation steps in Section 7.1. No exceptions. Use a well-tested OIDC library rather than hand-rolling validation. Like python-jose, nimbus-jose-jwt, jose (Node.js) handle the full validation chain.

9.3 Signature Verification Bypass (alg=none and Algorithm Confusion)

Attack 1: alg=none

Some JWT libraries, if misconfigured, accept a token with "alg": "none" and no signature — treating it as valid:

// Header
{ "alg": "none", "typ": "JWT" }
// Payload — any claims the attacker wants
{ "sub": "admin", "aud": "myapp-client-id", ... }
// Signature — empty string

This requires noographic key. If the library accepts it, the attacker can forge any identity.

Attack 2: RS256 → HS256 Algorithm Confusion

Some libraries accept either RSA (asymmetric) or HMAC (symmetric) algorithms. An attacker:

1. Takes the IdP’s public RSA key (publicly available in JWKS)
2. Signs a forged JWT using that public key as an HMAC secret with alg=HS256
3. Submits to an RP whose library uses the public key for both RS256 verification and HS256 verification without distinguishing

The librarverifies the HMAC signature using the “public key” as the secret — and it matches, because the attacker used it to sign.

Impact

Complete authentication bypass. Attacker can forge any identity.

Mitigation

• Hardcode the expected algorithm in the RP’s configuration — never accept alg from the token header without allowlisting
• Explicitly reject alg=none
• Use separate key material for HMAC and RSA operations
• Use well-maintained libraries with secure defaults (modern versions rt none by default)
• Configure: allowed_algorithms = ["RS256", "ES256"] — not ["RS256", "HS256", "none"]

9.4 Key Confusion Attacks (JWKS Misuse)

The Attack

The RP fetches the wrong JWKS, uses the wrong key, or is tricked into trusting attacker-controlled keys.

Scenarios:

• JWKS URL injection: If the RP derives the JWKS URL from the iss claim in the token (rather than from the pre-configured discovery document), an attacker sets "iss": "https://attacker.com", and the RP fetes keys from https://attacker.com/jwks — keys the attacker controls
• kid confusion: Multiple keys in JWKS — attacker crafts a token with a kid pointing to a key they control (if the JWKS is somehow tampered with)
• Stale key cache attack: The RP caches old keys indefinitely — a key compromise is not reflected

Mitigation

• Never derive JWKS URL from the token — always use the URL from the pre-configured or cached discovery document
• Validate iss against the expected issue selecting a key — not after
• Implement JWKS cache TTL and re-fetch on kid miss (but no more than once per request to prevent DoS)
• Pin the issuer URL — do not dynamically trust new issuers

9.5 Authorization Code Interception (OIDC Context)

Same mechanism as in OAuth 2.0, but with additional OIDC-specific consequences: the attacker who intercepts the code also receives the ID Token from the token endpoint, gaining the user’s identity.

Mitigation

PKCE is the primary control. In OIpecifically:

• nonce provides a secondary binding — even if the code is intercepted and exchanged, the attacker’s session won’t have the correct nonce in state to validate the returned ID Token
• This is why both PKCE and nonce should always be used together

9.6 Mix-Up Attacks

The Attack

The mix-up attack targets deployments where an RP supports multiple IdPs. An attacker operates a malicious IdP.

1. RP supports: auth.example.com (legitimate) and attacker.com (malicious)
2User intends to authenticate with auth.example.com
3. Attacker intercepts the authorization request and redirects it to attacker.com
4. attacker.com completes a flow and issues an authorization code for attacker.com
5. The RP's callback receives a code — but doesn't know which IdP issued it
6. RP sends the code to auth.example.com's token endpoint (the legitimate one)
7. auth.example.com rejects the code — but the error reveals information
   OR: the RP confuses which IdP's token endpoint to use, sendine code to attacker.com
8. attacker.com issues a token for a victim user (whose code was obtained elsewhere)

Impact

Cross-IdP token confusion; in some scenarios, authentication as a different user.

Mitigation

• Issuer binding: The RP must track which IdP initiated each authentication session and validate that the callback is from the expected IdP

• iss parameter in authorization response (RFC 9207) — the authorization server includes its issuer in the authorization response, aowing the RP to verify the response came from the expected IdP:

  https://myapp.com/callback?code=...&state=...&iss=https%3A%2F%2Fauth.example.com
  

• Store the expected iss in the session alongside state and nonce

9.7 Token Substitution Attacks

The Attack

In flows that return multiple tokens (Hybrid Flow), an attacker substitutes a token from one flow into another.

Example: Attacker has a valid ID Token issued to them by the IdP. They substitute it into the callback for a victim’s ongoing Hybrid Flow, tricking the RP into authenticating as the attacker rather than the victim.

Mitigation

• c_hash in the ID Token from the auth endpoint binds it to the specific authorization code — verify it
• at_hash binds the ID Token to the specific access token — verify it
• These hash bindings make substitution detectable: a substituted ID Token’s c_hash won’t match the victim’s code

9.8 Confusion Between Access Token and ID Token

The Attack

A develouses the access token as proof of identity (checking if it’s valid and concluding they know who the user is), or sends the ID Token to an API as a Bearer token.

Scenario A: RP sends ID Token to Resource Server as Bearer token. RS is configured to accept any token from the IdP, validates the signature, and accepts it — but the aud check would fail (aud is the client ID, not the RS identifier). If the RS skips aud validation, it accepts tokens not intended for it.

Scenario B: RP trusts any vid access token as proof of user identity without verifying the ID Token, not checking sub, nonce, or auth_time.

Impact

In Scenario A: horizontal privilege escalation if RS accepts tokens from other clients.
In Scenario B: authentication is reduced to “does a valid token exist” — bypassing user identity verification.

Mitigation

• ID Token → used exclusively by the RP to identify the user. Never forward to an API.
• Access Token → used exclusively to call APIs. Contains no reliabltity for the RP.
• Resource Servers must validate aud strictly — tokens intended for other audiences must be rejected.

9.9 Open Redirect Exploitation in OIDC

OIDC flows involve multiple redirects. Open redirect vulnerabilities can allow:

• Stealing authorization codes: redirect the callback to an attacker URL that captures the code parameter
• Stealing ID Tokens (Hybrid/Implicit): if response_mode=fragment or response_mode=query, tokens in the redirect URL go to the attacker

The attacsurface is the redirect_uri parameter. If the IdP allows partial matching or wildcards, an attacker can direct the response to their server.

Mitigation

• Exact redirect URI matching (covered in OAuth 2.0 security section)
• In OIDC specifically: PKCE + nonce provide defense-in-depth — even if the code is delivered to the attacker, they can’t exchange it (no code_verifier) and can’t use the ID Token (no nonce match)

9.10 PKCE Misconfiguration in OIDC Flows

When PKCE is required bunot enforced, or when plain method is allowed instead of S256:

• No PKCE enforcement: Authorization code can be exchanged by anyone who intercepts it — no code_verifier required. PKCE becomes theater.
• plain method: code_challenge = code_verifier — if an attacker intercepts the authorization request, they capture both the challenge (= verifier) and can use it in the token exchange.
• Weak verifier entropy: Predictable or short verifiers are brute-forceable within the code’s shortetime.

Mitigation

• IdP must enforce that if code_challenge was sent, code_verifier is required in the token exchange
• Only allow S256 — remove plain from supported methods
• Minimum verifier length: 43 characters from a cryptographically secure random source
• Best practice: require PKCE for all flows, including confidential clients

10. Best Practices and Modern Recommendations

10.1 Flow Selection

User-facing authentication (web app, mobile, SPA):
  → Authorization Co PKCE + OIDC
  → Always include nonce, state, code_challenge (S256)

Machine-to-machine (no user):
  → OAuth 2.0 Client Credentials
  → OIDC does not apply (no user to identify)

Input-constrained device:
  → Device Code Flow + OIDC
  → Include nonce in the device authorization request

NEVER use:
  → Implicit Flow
  → ROPC / Password Grant
  → Hybrid Flow (unless you have a specific architectural requirement)

10.2 ID Token Validation Checklist

□ Signature verified using IdP blic key from JWKS
□ Algorithm is in the configured allowlist (not "none", not unexpected alg)
□ kid-based key selection (not try-all-keys)
□ iss exactly matches expected issuer from discovery document
□ aud contains client_id
□ exp > current_time (with ≤60s clock skew tolerance)
□ nonce matches session-stored value (if sent)
□ Nonce invalidated after use (single-use)
□ at_hash verified (if access_token received)
□ c_hash verified (if Hybrid Flow)
□ auth_time checked against max_age (i)
□ acr meets minimum requirement (if sent)
□ sub from UserInfo matches sub from ID Token

10.3 Secure Parameter Handling

10.4 Token Storage

10.5 Scope and Claims Minimization

• Request only the scopes needed for the immediate operation (incremental authorization)
• Do not request profile if you only need sub and email
• Use offline_access only when the application genuinely needs background access
• Configure the IdP to issue minimal claims in ID Tokens; use UserInfo for supplemental data
• Custom claims with sensitive data should be in encrypted ID Tokens (JWE) if they must be in the token

10.6 Session Management and Logout

OIDC defines three logout mechanisms:

Back-channel logout is the modern recommendation. The logout token is a signed JWT (similar to an ID Token) containing sub and sid, allowing the RP to invalidate the corresponding session server-side without user browser involvement.

10.7 Library and Implementation Guidance

Do not implement OIDC validation from scratch in production. Use audited libraries:

When evaluating a library, verify it:

• Rejects alg=none
• Validates iss, aud, exp, nonce by default
• Uses kid-based key selection
• Supports automatic JWKS refresh

Quick Reference

OIDC EXTENDS OAUTH 2.0 BY ADDING:
  openid scope      → triggers OIDC
  id_token          → JWT asserting user identity
  nonce parameter   → ID Token replay protection
  UserInfo endpoint → additional identity claims
  Discovery doc     → self-configuringel

ID TOKEN REQUIRED CLAIMS:
  iss  sub  aud  exp  iat
  + nonce (if sent)  + auth_time (if max_age sent)

ID TOKEN CRITICAL VALIDATION:
  1. Signature (RS256/ES256, using JWKS)
  2. iss == expected issuer
  3. aud ∋ client_id
  4. exp > now
  5. nonce == session nonce (invalidate after)
  6. at_hash matches access_token

KEY SECURITY RULES:
  → Never accept alg=none
  → Never derive JWKS URL from token claims
  → Never use ID Token as Bearer token to APIs
  → Never use access token as proof of i→ Always validate nonce
  → Always use PKCE + S256
  → Always validate ALL 14 steps — no shortcuts

References

• OpenID Connect Core 1.0
• OpenID Connect Discovery 1.0
• OpenID Connect RP-Initiated Logout
• OpenID Connect Back-Channel Logout
• 9 — JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519)
• RFC 7517 — JSON Web Key (JWK)
• RFC 7518 — JSON Web Algorithms (JWA)
• RFC 9207 — OAuth 2.0 Authorization Server Issuer Identification
• OAuth 2.0 Security BCP
• OWASP Testing for OAuth/OIDC Weaknesses
• PortSwigger — OAuth 2.0 Authentication Vulnerabilities
• jwt.io — JWT Debugger

Overview & Architecture

This lab deploys a simulated on-premises Windows Active Directory environment inside Azure (using a VM), then connects it to your existing Entra ID tenant using three different hybrid identity methods. By the end you will have hands-on experience with every major hybrid identity pattern used in real enterprise environments.

What You Will Build

Architecture Diagram (Text)

Azure Subscription
  └── Resource Group: rg-hybrid-lab
        ├── VNet: vnet-lab (10.0.0.0/16)
        │     └── Subnet: snet-dc (10.0.1.0/24)
        ├── VM-DC01  (Windows Server 2022 — Domain Controller)
        │     ├── ADDS Role
        │     ├── Azure AD Connect installed
        │     └── Entra Cloud Sync agent
        └── VM-ADFS01  (Windows Server 2022 — Federation Server)
              └── ADFS Role
Entra ID Tenant (your M365 Dev Tenant)
  └── Synced users from lab.local domain
  └── Hybrid identity authentication methods configured

Cost Estimate

Two B2s VMs (~$0.048/hr each) + storage. Total: ~$5–8 for a full weekend lab if you deallocate VMs when not in use. Always stop (deallocate) VMs when not actively working. ⚠ Warning: Stop and deallocate both VMs when not in use. Do not just stop them — deallocate. Otherwise Azure still charges compute.

Phase 1 — Azure Infrastructure Setup

Step 1.1 — Create Resource Group and VNet

Everything for this lab lives in one resource group. This makes cleanup easy — delete the resource group and everything goes.

• In Azure Portal → Resource Groups → Create
• Name: rg-hybrid-lab - Region: choose one close to you (e.g. West Europe)
• Go to Virtual Networks → Create
• Name: vnet-lab - Address space: 10.0.0.0/16
• Add subnet: snet-dc - Address range: 10.0.1.0/24
• Review + Create

Step 1.2 — Deploy the Domain Controller VM (VM-DC01)

• Go to Virtual Machines → Create → Azure Virtual Machine
• Resource group: rg-hybrid-lab
• VM name: VM-DC01
• Image: Windows Server 2022 Datacenter — Gen2
• Size: Standard_B2s (2 vCPUs, 4GB RAM — cheapest viable option)
• Administrator username: labadmin - Password: something strong, write it down
• Under Networking — select vnet-lab and snet-dc subnet
• Public IP: create one (needed for RDP access)
• Under Inbound ports — allow RDP (3389) — we will lock this down after
• Review + Create → Create 💡 Tip: While VM-DC01 deploys, you can read ahead to Phase 1.3 to understand what you’re about to configure.

Step 1.3 — Configure Static Private IP

Domain Controllers must have a static IP — DNS registration breaks if the IP changes.

• Go to VM-DC01 → Networking → Network Interface
• IP Configurations → click ipconfig1
• Change Assignment from Dynamic to Static
• Set IP to: 10.0.1.4 → Save

Step 1.4 — Install Active Directory Domain Services

• RDP into VM-DC01 using its public IP, username: labadmin
• Open Server Manager → Add Roles and Features
• Select: Active Directory Domain Services → Add Features → Install
• After install, click the flag notification → Promote this server to a domain controller
• Select: Add a new forest
• Root domain name: lab.local
• Forest functional level: Windows Server 2016
• Set DSRM password (write this down — needed for AD recovery)
• Accept default paths → Install → Server will reboot automatically
• After reboot, RDP back in as: lab\labadmin 💡 Tip: lab.local is a non-routable domain used purely for lab purposes. In production, you would use a real domain you own (e.g. yourdomain.com).

Step 1.5 — Create Lab Users and OUs in Active Directory

Create a realistic OU structure — this matters when you configure sync scope later.

• Open Active Directory Users and Computers (ADUC) on VM-DC01
• Right-click lab.local → New → Organizational Unit → Name: LabUsers
• Create another OU: LabAdmins
• Inside LabUsers, create 3 test users:
• Right-click LabUsers → New → User
• User 1: First: Alice - Last: Smith - UPN: alice.smith@lab.local - Password: Lab@12345!
• User 2: Bob Jones - bob.jones@lab.local
• User 3: Carol Lee - carol.lee@lab.local

• Inside LabAdmins, create: Admin User - admin.user@lab.local — add to Domain Admins group

Step 1.6 — Configure VNet DNS to point to DC

Azure VMs use Azure DNS by default. We need them to use our DC for AD DNS resolution.

• Go to vnet-lab → DNS Servers
• Change to Custom → Enter 10.0.1.4 (VM-DC01 static IP)
• Save — restart VM-DC01 to pick up the DNS change

Phase 2 — Password Hash Sync (PHS)

What PHS Actually Does

PHS is the simplest hybrid identity method. Azure AD Connect takes a hash of the password hash stored in AD and syncs it to Entra ID. Authentication happens entirely in the cloud — Entra ID validates the credential without contacting your on-prem DC. If your on-prem goes down, users can still sign in. Conceptual Note: Microsoft hashes the password hash again before syncing — so Entra ID never has the original password or even the direct AD hash. It is a hash of a hash with a salt. PHS is considered secure and is the recommended default sync method for most organizations.

Step 2.1 — Add a Custom Domain to Entra ID

You cannot sync lab.local to Entra ID — .local is non-routable. You need to add a UPN suffix that matches a domain you own OR use the default onmicrosoft.com domain.

• In Entra ID portal → Custom domain names → Add custom domain
• If you own a domain (example.com etc.), add it and verify via DNS TXT record
• If not, skip this — Azure AD Connect will use the @xxx.onmicrosoft.com suffix
• Back in VM-DC01 → Tools → Active Directory Domains and Trusts → Right-click (Active Directory Domains and Trusts) → Properties → UPN Suffixes
• Add your verified domain or your onmicrosoft.com domain as an alternative UPN suffix

• Update your test users’ UPN to use the new suffix: alice.smith@xxx.onmicrosoft.com

Step 2.2 — Install Azure AD Connect on VM-DC01

• On VM-DC01, open a browser and go to: entra.microsoft.com
• In left pane, Entra ID → Entra Connect → Get Started → Manage → Download Connect Sync Agent
• Download and run the Azure AD Connect installer
• Accept license terms → Use express settings (for lab purposes)
• Connect to Entra ID — enter your Entra ID Global Admin credentials (xxx@xxx.onmicrosoft.com)
• Connect to ADDS — enter: lab\labadmin and password
• Azure AD sign-in configuration — you will see a warning that lab.local is not verified — acknowledge and continue
• On the sync method screen — confirm Password Hash Synchronization is selected
• Check: Start the synchronization process when configuration completes
• Install → Configuration completes → Initial sync runs

Step 2.3 — Verify Sync in Entra ID

• Go to Entra ID portal → Users
• You should see alice.smith, bob.jones, carol.lee appear as synced users
• Click on alice.smith — note the Source field shows: Windows Server AD
• Go to Entra ID → Azure AD Connect (under Hybrid management) — verify sync status shows Enabled 💡 Tip: Sync runs every 30 minutes by default. To force an immediate sync: on VM-DC01 open PowerShell and run:

  Start-ADSyncSyncCycle -PolicyType Delta
  

Step 2.4 — Test PHS Authentication

• Open a private browser window → go to portal.azure.com
• Sign in as alice.smith@xxx.onmicrosoft.com with password Lab@12345!
• Authentication should succeed — Entra ID validated against the synced password hash
• Check Entra ID → Sign-in logs — you will see the sign-in with authentication method: Password Hash Sync 🔴 Important: For PHS to work, the UPN of the synced user must match a verified domain in Entra ID. If you see authentication failures, the UPN suffix mismatch is the most likely cause.

Logging in as as alice smith

Phase 3 — Pass-Through Authentication (PTA)

What PTA Actually Does

Unlike PHS where authentication happens in the cloud, PTA delegates authentication back to your on-premises AD in real time. When a user signs into Entra ID, the authentication request is passed through to your DC via a lightweight agent. The password is never synced to the cloud — not even a hash. When to use PTA vs PHS: PTA is used when organizational policy requires that passwords (even hashed) never leave on-premises. The tradeoff: if your on-prem DC or the PTA agent goes down, cloud authentication fails. PHS is more resilient. Understanding this tradeoff is a real interview question.

Step 3.1 — Switch Azure AD Connect from PHS to PTA

• On VM-DC01, open Azure AD Connect from the Start Menu
• Click Configure → Change user sign-in → Next
• Enter your Entra ID Global Admin credentials
• Select: Pass-through authentication → Next
• Verify that Enable single sign-on is also checked
• Configure → the PTA agent is automatically installed on VM-DC01

Step 3.2 — Verify PTA Agent is Running

• In Entra ID portal → Azure AD Connect → Pass-through authentication
• You should see VM-DC01 listed as an active agent with status: Active
• The agent version and last active timestamp confirm it is communicating with Entra ID

Step 3.3 — Test PTA Authentication

• Open a private browser → sign into portal.azure.com as alice.smith@p2sp.onmicrosoft.com
• This time, Entra ID passes the authentication to VM-DC01 via the PTA agent
• Check Sign-in logs → authentication method now shows: Pass-through authentication
• To see what happens when on-prem fails: stop the Azure AD Connect PTA agent service on VM-DC01 → attempt sign-in again → it should fail
• Restart the agent service → verify sign-in works again

⚠ Warning: Stopping the PTA agent in production would lock out users. This is why production deployments run multiple PTA agents on different servers for redundancy.

Phase 4 — Active Directory Federation Services (ADFS)

What ADFS Actually Does

ADFS is a claims-based identity solution. Instead of syncing identities or delegating password checks, ADFS issues SAML tokens that assert claims about the user (who they are, what groups they belong to, their department etc.). Relying parties (apps) trust the ADFS server and accept its tokens. Authentication happens entirely on-premises. Why ADFS is legacy but still important: Most large enterprises built their federation infrastructure on ADFS 10-15 years ago. Many still run it. Understanding ADFS is important for inheriting or auditing those environments. Greenfield deployments today would use Entra ID native federation instead.

Step 4.1 — Deploy Second VM for ADFS (VM-ADFS01)

• In Azure Portal → Virtual Machines → Create
• Name: VM-ADFS01 - Same resource group, same VNet, same subnet
• Image: Windows Server 2022 Datacenter - Size: Standard_B2s
• Username: labadmin - Same password
• Allow RDP inbound
• Create → wait for deployment
• After deployment: join VM-ADFS01 to lab.local domain
  • RDP into VM-ADFS01
  • Windows + R → type sysdm.cpl & enter → Click Change button next to “To rename this computer or change its domain” → Domain: lab.local
  • Enter lab\labadmin credentials → reboot

Step 4.2 — Create a Self-Signed Certificate for ADFS

ADFS requires an SSL certificate. For lab purposes we use a self-signed cert.

• RDP into VM-ADFS01 as lab\labadmin
• Open PowerShell as Administrator and run:

  $cert = New-SelfSignedCertificate -DnsName 'adfs.lab.local' -CertStoreLocation 'cert:\LocalMachine\My' -KeyLength 2048
  

• Export the thumbprint for later: $cert.Thumbprint

Step 4.3 — Install ADFS Role on VM-ADFS01

• Open Server Manager → Add Roles and Features

This is enough for learning purposes. Converting an Entra ID domain to ADFS-federated in 2026 is a legacy operation. Microsoft’s own documentation now steers you toward migrating away from ADFS, not toward it. We can safely ignore the rest of this ADFS lab.

• Select: Active Directory Federation Services → Install
• After install, click Configure the federation service on this server
• Select: Create the first federation server in a federation server farm
• Connect with lab\labadmin domain admin credentials
• SSL Certificate: select the adfs.lab.local cert created above
• Federation service name: adfs.lab.local
• Federation service display name: Lab ADFS
• Service account: create a Group Managed Service Account (gMSA) named adfssvc
• Database: Use Windows Internal Database (WID) for lab — sufficient for testing
• Configure → Next → Configure

Step 4.4 — Configure Entra ID to use ADFS (Federated Domain)

This is the most important step — converting a managed domain to a federated domain tells Entra ID to redirect authentication to your ADFS server instead of handling it natively.

• On VM-DC01, install the MSOnline PowerShell module: Install-Module Microsoft.Graph -Force Connect-MgGraph -Scopes "Domain.ReadWrite.All"
• Enter your Entra ID Global Admin credentials when prompted
• Convert the domain to federated (replace with your actual domain): Convert-MsolDomainToFederated -DomainName xxxx.onmicrosoft.com -SupportMultipleDomain
• Verify federation settings: Get-MsolDomainFederationSettings -DomainName xxx.onmicrosoft.com ⚠ Warning: Converting to a federated domain means ALL authentication for that domain goes through ADFS. If ADFS goes down, no one can sign in. Always keep at least one cloud-only Global Admin as a break-glass account that is NOT in the federated domain.

Step 4.5 — Test ADFS Authentication Flow

• Open a private browser → go to portal.azure.com
• Enter alice.smith@xxx.onmicrosoft.com
• Entra ID should redirect you to the ADFS sign-in page (adfs.lab.local/adfs/ls)
• Sign in with AD credentials → ADFS issues a SAML token → Entra ID accepts it → access granted
• Check Entra ID Sign-in logs → authentication method: Federated
• On VM-ADFS01, open Event Viewer → Applications and Services Logs → AD FS → Admin — observe the token issuance events 💡 Tip: The ADFS Event Viewer logs are goldmine for understanding what happens during federation. Every authentication attempt, every claim issued, every error is logged here. Get comfortable reading them.

Phase 5 — Entra Cloud Sync

What Entra Cloud Sync Actually Does

Entra Cloud Sync is Microsoft’s modern, lightweight replacement for Azure AD Connect. Instead of a heavyweight on-prem application with a full sync engine, Cloud Sync uses a small provisioning agent that communicates with a sync engine hosted in Entra ID. Configuration is done entirely in the cloud portal — nothing needs to be configured on-prem beyond installing the agent.

Step 5.1 — First, Convert Domain Back to Managed

If you completed Phase 4 (ADFS), your domain is federated. Convert it back to managed before testing Cloud Sync.

• On VM-DC01, open PowerShell:

  Connect-MsolService
  Convert-MsolDomainToStandard -DomainName xxx.onmicrosoft.com -SkipUserConversion $false 
  

  -PasswordFile C:\temp\passwords.txt

• Also switch Azure AD Connect back to PHS or disable it — Cloud Sync and Azure AD Connect cannot run simultaneously on the same domain

Step 5.2 — Install the Entra Cloud Sync Provisioning Agent

• On VM-DC01, go to Entra ID portal → Hybrid management → Azure AD Connect → Cloud sync
• Click: Download agent
• Run the installer: AADConnectProvisioningAgentSetup.exe
• Sign in with your Entra ID Global Admin account during install
• Select: Active Directory Domain Services
• Add lab.local domain → enter lab\labadmin credentials
• Finish installation

Step 5.3 — Create a Cloud Sync Configuration in Entra ID Portal

• In Entra ID portal → Azure AD Connect → Cloud sync → New configuration
• Select: lab.local from the dropdown
• Enable Password Hash Sync: Yes

• Under Scope — add a scoping filter to sync only the LabUsers OU:
• Attribute: distinguishedName - Operator: CONTAINS - Value: OU=LabUsers,DC=lab,DC=local
• Review attribute mappings — observe how AD attributes map to Entra ID attributes
• Enable the configuration → Save
• Monitor the provisioning logs in the portal — you will see each user synced in real time 💡 Tip: The scoping filter is a critical concept — in real environments you never sync all AD users to Entra ID. You sync specific OUs or groups. This is a common interview question about Cloud Sync configuration.

Step 5.4 — Verify and Compare with Azure AD Connect

• Go to Entra ID → Users — verify LabUsers OU members appear
• Note: users synced via Cloud Sync show Source: Azure Active Directory (provisioning)
• Compare with users synced via Azure AD Connect — they show Source: Windows Server AD
• Review the provisioning logs: Entra ID → Monitoring → Provisioning logs — observe the sync events per user

What You’ve Built & What It Means

Cleanup — Avoid Unnecessary Azure Costs

• When done for the day: go to both VMs → Stop (this deallocates them, stopping compute charges)
• When completely done with the lab: delete rg-hybrid-lab resource group — this deletes everything inside it
• In Entra ID: remove the synced test users if no longer needed
• Revert any federated domain configuration back to managed

Portfolio Documentation

This lab covers the following bullet points you can legitimately add to your resume and discuss in interviews:

• Deployed and configured Windows Server ADDS in Azure as a simulated on-premises domain controller
• Implemented hybrid identity sync using Azure AD Connect with Password Hash Sync and Pass-Through Authentication
• Configured ADFS for claims-based federation between on-premises AD and Entra ID — observed SAML token issuance and relying party trust
• Deployed Entra Cloud Sync provisioning agent with OU-scoped filtering — contrasted architecture and tradeoffs against Azure AD Connect
• Analyzed authentication flow differences across PHS, PTA, and ADFS using Entra ID sign-in logs

What is CSPM?

CSPM refers to a category of security tools that automate the identification and remediation of risks across cloud infrastructure. These tools help ensure that cloud resources are configured according to security best practices and compliance requirements.

Key capabilities include:

• Continuous monitoring of cloud resource configurations
• Compliance assessment against frameworks (CIS, NIST, PCI-DSS, SOC 2)
• Misconfiguration detection and remediation guidance
• Visibility across multi-cloud environments

Cloud-Native CSPM Tools

Microsoft Defender for Cloud

Microsoft Defender for Cloud is Azure’s built-in CSPM and Cloud Workload Protection Platform (CWPP). It provides a centralized dashboard to assess the security posture of your Azure, AWS, and GCP resources.

• What it does: Continuously evaluates your cloud resources against security benchmarks (Microsoft Cloud Security Benchmark, CIS, NIST, PCI-DSS). It generates a Secure Score that quantifies your overall posture and prioritizes remediation steps.
• When to use it: If you’re running workloads in Azure (or multi-cloud with Azure as your primary), this is the go-to tool. It integrates natively with Azure Policy, Microsoft Sentinel, and Defender plans for VMs, containers, databases, and more.
• Key features: Secure Score, regulatory compliance dashboard, attack path analysis, agentless scanning, and auto-remediation through Azure Policy.
• Cost: The foundational CSPM features are free. Advanced features (Defender plans for servers, containers, databases, etc.) are paid per-resource.

AWS Security Hub

AWS Security Hub is Amazon’s native security posture management service that aggregates findings from multiple AWS security services into a single pane of glass.

• What it does: Collects and normalizes findings from services like AWS Config, GuardDuty, Inspector, IAM Access Analyzer, and Firewall Manager. It runs automated compliance checks against standards like CIS AWS Foundations Benchmark, AWS Foundational Security Best Practices, and PCI-DSS.
• When to use it: If your infrastructure is primarily on AWS. It acts as a central hub for all security findings across your AWS accounts and regions.
• Key features: Automated compliance checks, cross-account aggregation, integration with AWS Organizations, custom actions for automated remediation via EventBridge + Lambda.
• Cost: Priced per compliance check and per finding ingested. Free tier available for 30 days.

Google Cloud Security Command Center

Google Cloud SCC is GCP’s native security and risk management platform that provides visibility into your Google Cloud assets and their security state.

• What it does: Discovers and inventories all your GCP assets, detects misconfigurations and vulnerabilities, identifies threats through integrated threat detection (Event Threat Detection, Container Threat Detection), and visualizes attack paths.
• When to use it: If you’re running workloads on GCP. The Premium tier adds features like Security Health Analytics, compliance monitoring, and the Virtual Red Team for attack path simulation.
• Key features: Asset inventory, vulnerability scanning, threat detection, compliance monitoring (CIS, PCI-DSS, NIST), and findings export to SIEM/SOAR tools.
• Cost: Standard tier is free with basic asset discovery. Premium tier is paid and unlocks full CSPM capabilities.

Open-Source & Third-Party Tools

Prowler

Prowler is an open-source CLI security assessment tool that performs hundreds of checks across AWS, Azure, and GCP.

• What it does: Runs automated security audits and generates reports against compliance frameworks including CIS Benchmarks, PCI-DSS, HIPAA, GDPR, SOC 2, NIST 800-53, and more. It outputs results in multiple formats (CSV, JSON, HTML) and can send findings to AWS Security Hub.
• When to use it: When you want a free, framework-agnostic tool to audit your cloud environments on-demand or in CI/CD pipelines. Great for multi-cloud teams that don’t want to rely solely on vendor-native tools.
• Key features: 300+ checks for AWS, 200+ for Azure, 70+ for GCP, multi-output format, CI/CD integration, and SaaS version (Prowler Cloud) available.

ScoutSuite

ScoutSuite is an open-source multi-cloud security auditing tool that collects configuration data from cloud APIs and generates an interactive HTML report.

• What it does: Fetches resource configurations from AWS, Azure, GCP, Oracle Cloud, and Alibaba Cloud, then applies a set of rules to flag dangerous configurations. The output is a self-contained HTML report you can browse locally.
• When to use it: When you need a quick, visual snapshot of your cloud security posture across multiple providers. Useful for security assessments and penetration tests where you want a browsable report without needing a dashboard or SaaS tool.
• Key features: Multi-cloud support (5 providers), interactive HTML report, rule-based engine, no agents required, and easy to extend with custom rules.

CloudSploit

CloudSploit (now part of Aqua Security) is an open-source cloud security configuration monitoring tool.

• What it does: Scans AWS, Azure, GCP, and Oracle Cloud for misconfigurations and compliance violations. Checks cover areas like IAM, networking, encryption, logging, and monitoring. The open-source version runs as a CLI tool; the managed SaaS version provides continuous monitoring.
• When to use it: When you want a lightweight, developer-friendly scanner that’s easy to integrate into automated workflows. Good for teams that want quick misconfiguration checks without heavyweight tooling.
• Key features: Plugin-based architecture (easy to add custom checks), supports 4 cloud providers, JSON output, and a SaaS offering through Aqua Security.

Checkov

Checkov is a static analysis tool for Infrastructure-as-Code (IaC) that catches security misconfigurations before resources are deployed.

• What it does: Scans Terraform, CloudFormation, Kubernetes manifests, Helm charts, ARM templates, Bicep, Serverless Framework, and Dockerfile files for security and compliance issues. It also supports scanning runtime cloud configurations via integration with Bridgecrew.
• When to use it: In your CI/CD pipeline to shift security left. Run it before terraform apply or az deployment create to catch problems at the code stage rather than in production. Essential for GitOps and IaC-heavy workflows.
• Key features: 1000+ built-in policies, custom policy support (Python and YAML), graph-based analysis for cross-resource checks, IDE plugins, and CI/CD integration (GitHub Actions, GitLab CI, Jenkins).

Azure Quick Review (azqr)

Azure Quick Review (azqr) is an open-source CLI tool from Microsoft that scans Azure resources and produces a detailed Excel report on best practice recommendations.

• What it does: Evaluates your Azure resources against the Azure Well-Architected Framework pillars (Reliability, Security, Cost Optimization, Operational Excellence, Performance Efficiency). It checks for things like missing diagnostic settings, lack of availability zones, unencrypted resources, and missing private endpoints.
• When to use it: When you want a quick, one-shot assessment of your Azure subscription before an architecture review or audit. It’s lightweight (single binary, no install) and produces a spreadsheet that’s easy to share with stakeholders.
• Key features: Covers 80+ Azure resource types, Excel output with categorized findings, Azure Well-Architected alignment, no authentication token required beyond Azure CLI login, and runs in minutes.

ThreatMapper

ThreatMapper by Deepfence is an open-source cloud-native threat detection and attack surface management platform.

• What it does: Goes beyond configuration checks — it discovers running workloads (VMs, containers, serverless), scans them for vulnerabilities (CVEs), detects exposed secrets, and maps the attack surface by correlating findings with network reachability. It visualizes threat paths from the internet to your sensitive assets.
• When to use it: When you want runtime visibility into your cloud-native workloads, not just configuration audits. Ideal for organizations running Kubernetes, Docker, or serverless at scale that need to understand which vulnerabilities are actually exploitable based on network exposure.
• Key features: Topology visualization of cloud assets, runtime vulnerability scanning, secret scanning, malware detection, attack path mapping, Kubernetes and Docker support, integrations with Slack/Jira/SIEM, and a management console UI.

ScubaGear

ScubaGear (Secure Cloud Business Applications Gear) is a tool developed by CISA (Cybersecurity and Infrastructure Security Agency) to assess the security configuration of Microsoft 365 (M365) tenants.

• What it does: Evaluates your M365 tenant against CISA’s Secure Cloud Business Applications (SCuBA) security baselines. It checks configurations for Azure Active Directory / Entra ID, Exchange Online, SharePoint Online, OneDrive, Microsoft Teams, Power BI, Power Platform, and Defender for Office 365.
• When to use it: When you need to audit your Microsoft 365 security posture against US government-recommended baselines. Essential for government agencies (required by CISA BOD 25-01) and any organization that wants to harden their M365 configuration.
• Key features: PowerShell-based (runs locally), generates HTML reports with pass/fail results per baseline, covers 8 M365 products, regularly updated baselines, and fully open-source.

Maester

Maester is an open-source test automation framework for verifying Microsoft Entra ID (Azure AD), Microsoft 365, and Azure security configurations using Pester (PowerShell testing framework).

• What it does: Lets you define security configuration baselines as Pester tests and run them against your tenant. It ships with a growing library of built-in tests covering Entra ID Conditional Access policies, authentication methods, privileged roles, M365 settings, and more. Think of it as unit tests for your identity and M365 security settings.
• When to use it: When you want continuous, automated validation that your Entra ID and M365 configurations haven’t drifted from your desired security baseline. Ideal for DevOps/SecOps teams that want to integrate identity security checks into CI/CD pipelines or scheduled monitoring.
• Key features: Pester-based (familiar to PowerShell users), built-in test library aligned with CIS and CISA recommendations, custom test support, HTML and NUnit report output, GitHub Actions integration, and daily scheduled monitoring support.

Comparison

Choosing the Right Tool

There’s no single tool that covers everything. The best approach is to layer tools based on your needs:

• Cloud-native CSPM (Defender for Cloud / Security Hub / SCC) for continuous posture management in your primary cloud provider.
• Prowler or ScoutSuite for on-demand multi-cloud audits and compliance checks.
• Checkov in your CI/CD pipeline to catch IaC misconfigurations before deployment.
• azqr for Azure Well-Architected reviews and quick subscription assessments.
• ThreatMapper for runtime vulnerability and attack surface visibility in container/Kubernetes environments.
• ScubaGear to validate your Microsoft 365 tenant against CISA baselines.
• Maester for continuous, automated Entra ID and M365 security testing in your pipelines.

Conclusion

Cloud security isn’t a one-and-done activity — it’s an ongoing process that scales with your infrastructure. The tools covered in this post range from cloud-native platforms like Defender for Cloud and AWS Security Hub that give you continuous visibility, to open-source scanners like Prowler and Checkov that fit cleanly into DevOps workflows, to specialized tools like ScubaGear and Maester that lock down your Microsoft 365 and Entra ID configurations.

No single tool will catch everything. The real value comes from combining them: use cloud-native CSPM for day-to-day monitoring, IaC scanners to shift left, and targeted tools like azqr or ScubaGear for periodic deep-dive assessments. Most of the open-source options covered here are free and can be up and running in minutes, so there’s very little barrier to getting started.

The most important step is the first one — pick a tool, run a scan, and start closing gaps.

As I discussed in my previous post, azqr is one of several tools organizations can use to gain visibility into the security posture of their workloads and resources.

Lab Setup

The vulnerable infrastructure was deployed using Terraform. The source code is available here.

Prerequisites are listed in the GitHub repo. The repo was originally built to support Prowler, but it works equally well for testing azqr’s capabilities.

After cloning the repo and provisioning the infrastructure with Terraform (instructions are in the GitHub repo), the next step is to install azqr.

From the official repo, there are two ways to install it:

• winget install azqr

OR

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/azure/azqr/main/scripts/install.ps1'))

Since I was using PowerShell at the time, I went with the latter option. This one-liner downloads and runs the azqr install script directly from GitHub.

The script drops the azqr.exe executable in the current working directory. I moved it to a dedicated Azqr/ folder inside Program Files/ for easier access.

Running azqr

Now that azqr is installed, let’s look at a few of its flags and options:

The option we’re interested in is scan, which allows us to scan a subscription for misconfigurations.

Syntax for the scan command:

azqr scan -s <SUB_ID>

The scan command offers several additional flags and options, the most notable being:

1. Scanning specific resources only.
2. --filter to apply a filter (in YAML format).
3. -g to scope the scan to a specific resource group.
4. --xlsx, --csv, --stdout for different output formats.

Running a scan with just the -s <SUB> flag produces an .xlsx file containing all findings. For example:

Limitations of azqr

While azqr is an excellent assessment tool for Azure workloads, its output formats are not particularly user-friendly.

Part of my motivation for documenting azqr was to understand its inner workings, with the goal of building a more readable and accessible front-end. The idea is that users interact through a web UI, which in turn invokes the CLI to initiate scans and present results in a cleaner format.

All of these answer two questions:

1. Who is the user?
2. What are they allowed to do?

SAML (Security Assertion Markup Language)

SAML is an older, XML-based standard that predates mobile/API-first architecures and many enterprises still use it. It makes this possible by providing a way to authenticate a user once and then communicate that authentication to multiple applications. The most current version in SAML 2.0.

SAML workflow:

A typical SSO authentication process involves three parties

• Principal (also known as the “subject”): Almost always a human user who is trying to access cloud-hosted application.
• Identity Provider: IdP is a cloud software service that stores and confirms user identity, typically through a login process. IdP’s role is to say “I know this person and this is the list of things they are allowed to do”. An SSO system may in fact be separate from the IdP, but in those cases the SSO essentially acts as a representative for the IdP, so for all intents and purposes, they are the same in a SAML workflow.
• Service Provider: This is the cloud-hosted application or service the user wants to use. Common examples include Gmail, M365 and others include Salesforce, ServiceNow, Jira etc. Ordinarily a user would just log in to these services directly, but when SSO is used, the user logs into the SSO instead, and SAML is used to give them access instead of a direct login.

Typical Workflow:

Working:

• Uses XML-based messages
• Browser redirects user to an Identity Provider (IdP)
• IdP sends back a SAML assertion

OAuth 2.0 Framework:

It is a security standard where you give one application permission to access your data from another service/application.

Components of OAuth2.0:

1. Resource Owner: The owner of the data, you. You are in charge of your data and the things that can be done with it. You can grant permission for it.

2. Client: The application that wants to access data or perform actions on behalf of the resource owner.

3. Authorization Server: The server that knows the resource owner and the resource owner has an account with the authorization server.

4. Resource Server: The API or service that the client wants to use on behalf of the user/resource owner.

Sometimes the authorization server and the resource server are the same server. However, there are cases where the two servers are different. For example, the authorization server may be a 3rd party service that the resource server trusts for validation and authorization.

1. Redirect URI: The URI that the resource server will redirect the resource owner to after granting permission to the client.

2. Response Type: The type of information that the client expects to receive. The most common type is authorization code.

3. Scope: The granualar permissions that are required by the clients. For example:

• Read contacts
• Create Contact
• Delete contact

1. Consent: The authorization server takes the scope that the client is requesting and verifies with the resource owner whether or not they want to give the client the requested permissions.

2. Client ID: This ID is used to identify the client with the authorization server.

3. Client Secret: Only the client and auth server know this, and this allows them to securely share information.

4. Authorization Code: A short lived temporary code that the auth server sends back to the client. The client sends this Authorization code along with the Client Secret & Client ID back to the authorization server in exchange for an Access token.

5. Access token: Is a value/key that the client will use from that point forward to communicate with the resource server.

Full end-to-end flow:

1. User clicks “Sign in with Microsoft”:

   • Front-end redirects the user’s browser to entra’s authorization endpoint

     https://login.microsoftonline.com/common/oauth2/v2.0/authorize
     ?client_id=YOUR_CLIENT_ID
     &response_type=code
     &redirect_uri=https://yourapp.com/auth/callback
     &scope=openid profile email
     &state=random_string
     

2. User authenticates with Microsoft:

3. Entra ID redirects back to your app:

   • After successful login, Entra Redirects the browser back to the redirect URI with a short-lived authorization code:

      https://yourapp.com/auth/callback?code=AUTHORIZATION_CODE&state=random_string
     

4. Your backend exchanges the code for tokens:

   • Backend makes a POST req to entra id: ``` POST https://login.microsoftonline.com/common/oauth2/v2.0/token

   client_id=YOUR_CLIENT_ID client_secret=YOUR_CLIENT_SECRET code=AUTHORIZATION_CODE redirect_uri=https://yourapp.com/auth/callback grant_type=authorization_code ``` This is the only step where your client secret is used. Entra ID verifies that the secret matches the client ID, confirming the request is genuinely from your app and not someone who intercepted the code.

5. Entra ID returns tokens:

   • Entra reponds with:

      {
      "access_token": "eyJ...",
      "id_token": "eyJ...",
      "refresh_token": "eyJ...",
      "expires_in": 3600
      }
     

   • ID token — contains the user’s identity (name, email, Entra object ID). This is what you use to know who just logged in.
   • Access token — used to call Microsoft APIs on behalf of the user (e.g. Microsoft Graph), if your app needs that.
   • Refresh token — lets your backend silently get new tokens when the access token expires, without making the user log in again.

6. Backend reads the ID token:

   • You decode the ID token (it’s a JWT) and extract the user’s information:

      {
      "oid": "user's unique Entra object ID",
      "email": "user@outlook.com",
      "name": "John Doe",
      "iss": "https://login.microsoftonline.com/...",
      "aud": "YOUR_CLIENT_ID",
      "exp": 1234567890
      }
     

     You should validate the token — check that iss is Microsoft, aud matches your client ID, and exp hasn’t passed. Never skip validation.

   The oid claim is the most important one — it’s the user’s permanent, unique identifier in Entra ID. Use this as their ID in your database, not their email (emails can change).

OpenID connect (OIDC):

OpenID Connect (OIDC) is an identity layer built on top of OAuth 2.0. If OAuth 2.0 answers “what is this app allowed to do on the user’s behalf?”, OIDC answers “who is this user?” in a standard, interoperable way.

How OIDC extends OAuth 2.0

• Reuses OAuth 2.0 flows: Authorization code flow, access tokens, refresh tokens, redirect URIs, scopes, etc.
• Adds an id_token: A signed JWT that the client validates to prove the user’s identity.
• Defines standard scopes and claims: Scopes like openid, profile, email and well-known claims (sub, email, name, etc.) so different identity providers expose user info in a common shape.
• Standardizes discovery: Via the /.well-known/openid-configuration endpoint so clients can auto-discover the correct authorization, token, and JWKS endpoints.

In the Microsoft Entra example above, the moment you added the openid profile email scopes and received an id_token, you moved from plain OAuth 2.0 into OpenID Connect:

• The access token is for calling APIs on behalf of the user (authorization).
• The ID token is for logging the user into your app and answering “who just signed in?” (authentication).

OIDC is what powers most modern “Sign in with X” buttons (Microsoft, Google, GitHub, etc.) and is generally the preferred choice for new web and mobile applications, because it gives you a clean, token-based answer to both questions from the big picture section:

1. Who is the user? → From the id_token and its claims.
2. What are they allowed to do? → From scopes and access tokens (via OAuth 2.0).

Comparing SAML, OAuth 2.0 and OIDC

• Primary goal
  • SAML: Enterprise SSO between a corporate identity provider and browser-based applications.
  • OAuth 2.0: Delegated authorization – let an application call APIs on behalf of a user.
  • OIDC: Authentication – log the user in and give the app a verified identity for them.
• Token / data format
  • SAML: XML-based assertions passed via browser redirects or POSTs.
  • OAuth 2.0: Access tokens (opaque or JWT) used to protect APIs.
  • OIDC: JWT ID tokens (plus OAuth 2.0 access tokens when you also call APIs).
• Best suited for
  • SAML: Older/SaaS apps in enterprise SSO ecosystems (Okta, legacy ADFS-style setups).
  • OAuth 2.0: Securing APIs, microservices, and third‑party integrations.
  • OIDC: User sign‑in flows for modern web, SPA, and mobile applications.

A helpful way to remember it:

• SAML and OIDC are mainly about “who is the user?” (authentication and SSO).
• OAuth 2.0 is mainly about “what is this app allowed to do?” (authorization against APIs and resources).

In many real systems you will use OAuth 2.0 and OIDC together for a complete identity story: OIDC to sign the user in and establish who they are, and OAuth 2.0 scopes and access tokens to control what your services and APIs are allowed to do on their behalf.