oauth-oidc-protocols

name	oauth-oidc-protocols
description	OAuth 2.0 and OpenID Connect protocol fundamentals including authorization code flow with PKCE, client credentials, refresh tokens, discovery documents, JWKS, and token introspection. Protocol-level troubleshooting and compliance.
invocable	false

OAuth 2.0 & OpenID Connect Protocols

When to Use This Skill

Use this skill when:

• Choosing the correct OAuth 2.0 grant type for a scenario
• Debugging token exchange flows or redirect-based authentication
• Understanding what claims and headers appear in identity tokens vs access tokens
• Implementing or troubleshooting PKCE (Proof Key for Code Exchange)
• Working with discovery documents, JWKS endpoints, or token introspection
• Reviewing security properties of different protocol flows
• Implementing refresh token rotation or token revocation

Core Principles

1. OAuth 2.0 is for Authorization, OIDC is for Authentication — OAuth alone does not tell you who the user is. OpenID Connect adds an identity layer (the ID token) on top of OAuth.
2. Authorization Code + PKCE is the Universal Flow — Use it for web apps, SPAs (via BFF), native apps, and any interactive scenario. It replaced implicit flow.
3. Tokens are Opaque to Clients — Clients should not parse access tokens. Only the resource server (API) validates access tokens. Clients use the ID token for authentication.
4. Discovery Documents are the Source of Truth — Always resolve endpoints from /.well-known/openid-configuration rather than hardcoding URLs.
5. Refresh Tokens Require Secure Storage — Refresh tokens are long-lived credentials. Rotate them on every use (OneTimeOnly) and store them server-side.

Related Skills

• identityserver-configuration — Server-side configuration of clients, resources, and scopes
• aspnetcore-authentication — Implementing OIDC authentication in ASP.NET Core apps
• token-management — Automated token lifecycle with Duende.AccessTokenManagement
• identity-security-hardening — Security hardening including DPoP, PAR, and FAPI
• duende-bff — Backend-for-Frontend pattern for SPAs

Docs: https://docs.duendesoftware.com/identityserver/fundamentals

---

Concept 1: The OAuth 2.0 / OIDC Mental Model

Roles

Role	OAuth 2.0 Term	OIDC Term	Example
User	Resource Owner	End-User	A person logging in
Browser/App	Client	Relying Party (RP)	ASP.NET Core web app
Token Server	Authorization Server	OpenID Provider (OP)	Duende IdentityServer
API	Resource Server	—	ASP.NET Core Web API

Tokens

Token	Purpose	Who Consumes It	Format
ID Token	Proves user identity	Client application	Always JWT
Access Token	Authorizes API calls	Resource server (API)	JWT or reference
Refresh Token	Obtains new access tokens	Client application	Opaque handle

Critical Rule: Clients authenticate users with the ID token. Clients authorize API calls with the access token. Never use an access token to determine who a user is. Never send an ID token to an API.

---

Concept 2: Grant Types (Flows)

Authorization Code + PKCE (Recommended for All Interactive Scenarios)

The authorization code flow with PKCE is the recommended flow for all clients that involve a user. PKCE prevents authorization code interception attacks.

How it works:

1. Client generates a random code_verifier and its SHA256 hash code_challenge
2. Client redirects user to the authorize endpoint with code_challenge
3. User authenticates at IdentityServer and consents (if required)
4. IdentityServer redirects back with an authorization code
5. Client exchanges the code + code_verifier at the token endpoint
6. IdentityServer verifies the verifier matches the original challenge
7. IdentityServer returns ID token + access token (+ refresh token if offline_access scope)

┌──────┐          ┌──────────┐          ┌──────────────┐
│Client│          │  Browser  │          │IdentityServer│
└──┬───┘          └────┬─────┘          └──────┬───────┘
   │  1. Generate PKCE │                       │
   │  code_verifier    │                       │
   │  code_challenge   │                       │
   │                   │                       │
   │  2. Redirect ───────────────────────────► │
   │     /authorize?code_challenge=...         │
   │                   │  3. User logs in      │
   │                   │  ◄──────────────────► │
   │                   │                       │
   │  4. Redirect back ◄────────────────────── │
   │     ?code=abc123  │                       │
   │                   │                       │
   │  5. POST /token ─────────────────────────►│
   │     code=abc123&code_verifier=...         │
   │                   │                       │
   │  6. Tokens ◄──────────────────────────────│
   │     { id_token, access_token,             │
   │       refresh_token }                     │
   └───────────────────┴───────────────────────┘

When to use: Web applications, native apps, SPAs (via BFF pattern).

Client Credentials

For machine-to-machine communication with no user involvement.

┌──────────┐                    ┌──────────────┐
│  Service  │                    │IdentityServer│
└────┬─────┘                    └──────┬───────┘
     │  POST /token                    │
     │  grant_type=client_credentials  │
     │  client_id=...                  │
     │  client_secret=...              │
     │  scope=api1                     │
     │  ───────────────────────────►   │
     │                                 │
     │  { access_token }               │
     │  ◄───────────────────────────   │
     └─────────────────────────────────┘

When to use: Background services, daemons, server-to-server API calls.

Key difference: No user identity — the access token contains only client claims, not user claims.

Refresh Token Exchange

┌──────┐                         ┌──────────────┐
│Client│                         │IdentityServer│
└──┬───┘                         └──────┬───────┘
   │  POST /token                       │
   │  grant_type=refresh_token          │
   │  refresh_token=old_rt              │
   │  ─────────────────────────────►    │
   │                                    │
   │  { access_token,                   │
   │    refresh_token: new_rt }         │
   │  ◄─────────────────────────────    │
   └────────────────────────────────────┘

With RefreshTokenUsage = OneTimeOnly, each refresh returns a new refresh token. The old one is invalidated. This enables refresh token rotation, a key security measure. Note: the default changed to ReUse in IdentityServer v7.0 — set OneTimeOnly explicitly for rotation.

Deprecated / Discouraged Flows

Flow	Status	Why
Implicit (token / id_token)	Deprecated	Tokens in URL fragments; no PKCE protection
Resource Owner Password (ROPC)	Discouraged	Client handles credentials directly; no MFA support
Hybrid	Replaced	Use Authorization Code + PKCE instead

---

Concept 3: Discovery and JWKS

Discovery Document

Every OpenID Connect provider publishes a discovery document at /.well-known/openid-configuration. This JSON document advertises:

• Endpoint URLs (authorize, token, userinfo, introspection, revocation, end_session)
• Supported grant types, scopes, claims, and response types
• Signing algorithms and JWKS URI
• Token endpoint authentication methods

// ✅ Use IdentityModel to fetch discovery programmatically
using var httpClient = new HttpClient();
var disco = await httpClient.GetDiscoveryDocumentAsync("https://identity.example.com");

if (disco.IsError) throw new Exception(disco.Error);

var tokenEndpoint = disco.TokenEndpoint;
var jwksUri = disco.JwksUri;

Best Practice: Never hardcode endpoint URLs. Always resolve them from the discovery document. This ensures your application adapts to URL changes and load balancer configurations.

JWKS (JSON Web Key Set)

The JWKS endpoint (advertised via the jwks_uri field in the discovery document; in Duende IdentityServer this is /.well-known/openid-configuration/jwks) publishes the public keys used to verify token signatures. APIs and clients fetch this to validate JWTs.

Key rotation: When IdentityServer rotates signing keys, the new key appears in JWKS during the propagation period before it becomes the active signing key. Client libraries cache JWKS for 24 hours by default.

---

Concept 4: Token Anatomy

ID Token (JWT)

{
  "iss": "https://identity.example.com",
  "sub": "818727",
  "aud": "web.app",
  "exp": 1311281970,
  "iat": 1311280970,
  "nonce": "n-0S6_WzA2Mj",
  "auth_time": 1311280969,
  "at_hash": "77QmUPtjPfzWtF2AnpK9RQ",
  "amr": ["pwd", "mfa"],
  "name": "Alice Smith",
  "email": "[e-mail]"
}

Key claims:

• iss — Issuer (must match your IdentityServer URL)
• sub — Subject (unique user identifier)
• aud — Audience (must match the client ID)
• nonce — Replay protection (sent in authorize request, echoed in token)
• at_hash — Hash of the access token (binds the ID token to the access token)
• amr — Authentication methods used

Access Token (JWT)

{
  "iss": "https://identity.example.com",
  "aud": "https://api.example.com",
  "client_id": "web.app",
  "sub": "818727",
  "scope": "openid profile api1",
  "exp": 1311284570,
  "iat": 1311280970,
  "jti": "unique-token-id"
}

Key claims:

• aud — The API resource(s) this token is valid for
• client_id — Which client requested this token
• scope — Granted permissions
• jti — Unique token identifier (for revocation tracking)

Reference Tokens

Reference tokens are not self-contained JWTs. Instead, the access token is an opaque identifier. The API must call the introspection endpoint to validate it:

POST /connect/introspect
Content-Type: application/x-www-form-urlencoded

token=<reference_token>&token_type_hint=access_token

When to use reference tokens:

• Tokens contain sensitive claims you don't want exposed to intermediaries
• You need immediate token revocation (JWT lifetimes are not revocable until expiry)
• Token size is a concern (reference tokens are small opaque strings)

---

Concept 5: Token Introspection and Revocation

Introspection

APIs validate reference tokens by calling the introspection endpoint. The API authenticates itself with its own secret:

// Using IdentityModel
var introspectionResponse = await httpClient.IntrospectTokenAsync(
    new TokenIntrospectionRequest
    {
        Address = disco.IntrospectionEndpoint,
        ClientId = "api1",
        ClientSecret = "api1-secret",
        Token = accessToken
    });

if (!introspectionResponse.IsActive)
{
    // Token is invalid, expired, or revoked
}

Revocation

Clients can revoke access tokens and refresh tokens:

var revocationResponse = await httpClient.RevokeTokenAsync(
    new TokenRevocationRequest
    {
        Address = disco.RevocationEndpoint,
        ClientId = "web.app",
        ClientSecret = "secret",
        Token = refreshToken,
        TokenTypeHint = "refresh_token"
    });

---

Concept 6: Scopes and Claims Mapping

Scopes Control What's in Tokens

Scope requested	What it controls	Token affected
openid	Returns sub claim	ID token
profile	Returns name, family_name, etc.	ID token / userinfo
email	Returns email, email_verified	ID token / userinfo
api1	Grants access to API	Access token
offline_access	Returns refresh token	Refresh token issued

Claims Destinations

By default, IdentityServer emits identity claims to the ID token and the userinfo endpoint. Claims associated with API scopes go into the access token. The IProfileService controls claim emission:

public class ProfileService : IProfileService
{
    public Task GetProfileDataAsync(ProfileDataRequestContext context)
    {
        // Add claims based on the requested resources
        var claims = GetClaimsForUser(context.Subject);
        context.IssuedClaims.AddRange(
            claims.Where(c => context.RequestedClaimTypes.Contains(c.Type)));
        return Task.CompletedTask;
    }

    public Task IsActiveAsync(IsActiveContext context)
    {
        context.IsActive = true; // Check if user account is still active
        return Task.CompletedTask;
    }
}

---

Concept 7: Security Extensions

Pushed Authorization Requests (PAR)

PAR moves the authorization parameters from the query string to a backchannel POST, preventing parameter tampering and URL length issues:

1. Client POSTs parameters to /connect/par → gets a request_uri
2. Client redirects user to /authorize?request_uri=...&client_id=...

DPoP (Demonstrating Proof-of-Possession)

DPoP binds access tokens to a client's cryptographic key, preventing token theft and replay:

1. Client generates a key pair
2. Client creates a DPoP proof (signed JWT with the public key)
3. Client sends the DPoP proof in the DPoP header with the token request
4. IdentityServer binds the token to the key via a "cnf" claim
5. API verifies the DPoP proof matches the token's "cnf" claim

FAPI 2.0

Financial-grade API profile requires PAR, DPoP or mTLS, and stricter validation. Duende IdentityServer supports FAPI 2.0 compliance from v7.3+.

---

Common Pitfalls

1. Using Access Tokens for Authentication

// ❌ WRONG — Access tokens are for authorization, not authentication
var userId = accessToken.Claims.First(c => c.Type == "sub").Value;
// The access token's audience is the API, not your app

// ✅ CORRECT — Use the ID token (via the authentication middleware)
var userId = User.FindFirst("sub")?.Value;

2. Parsing Access Tokens in the Client

// ❌ WRONG — Clients should treat access tokens as opaque
var handler = new JwtSecurityTokenHandler();
var jwt = handler.ReadJwtToken(accessToken);
// This breaks when the server switches to reference tokens

// ✅ CORRECT — Only the resource server (API) validates access tokens
// The client just forwards the token in the Authorization header
httpClient.SetBearerToken(accessToken);

3. Missing PKCE

// ❌ WRONG — No PKCE leaves authorization code flow vulnerable
// Duende IdentityServer requires PKCE by default (RequirePkce = true)

// ✅ The ASP.NET Core OIDC handler sends PKCE automatically since .NET 7
// No extra configuration needed on the client side

4. Ignoring Token Expiration

// ❌ WRONG — Using a token without checking expiration
httpClient.SetBearerToken(cachedAccessToken); // Might be expired

// ✅ CORRECT — Use Duende.AccessTokenManagement for automatic refresh
// See the `token-management` skill
builder.Services.AddOpenIdConnectAccessTokenManagement();

5. Hardcoding Endpoint URLs

// ❌ WRONG — Breaks when server URL changes
var tokenEndpoint = "https://identity.example.com/connect/token";

// ✅ CORRECT — Resolve from discovery
var disco = await httpClient.GetDiscoveryDocumentAsync(authority);
var tokenEndpoint = disco.TokenEndpoint;

---

Protocol Debugging Checklist

When a token exchange fails, check these in order:

1. Discovery document — Is /.well-known/openid-configuration reachable? Does it return valid JSON?
2. Client ID — Does the client ID in the request exactly match the server registration?
3. Redirect URI — Exact string match including scheme, host, port, path, and trailing slash
4. Scopes — Are all requested scopes registered in AllowedScopes on the client?
5. Grant type — Is the grant type in the request allowed by the client's AllowedGrantTypes?
6. PKCE — Is the client sending code_challenge and code_verifier? Duende IS requires PKCE by default.
7. Client secret — Is the secret correct? Check for encoding issues (Sha256 hash, not plaintext).
8. Clock skew — Is the server time within acceptable bounds for token validation? (default: 5 min)
9. HTTPS — Is the authorize redirect using HTTPS? Mixed content blocks cause silent failures.
10. CORS — If calling the token endpoint from a browser, is the origin in AllowedCorsOrigins?

---

Resources

• OAuth 2.0 (RFC 6749)
• OAuth 2.0 for Browser-Based Apps (RFC draft)
• PKCE (RFC 7636)
• OpenID Connect Core 1.0
• OpenID Connect Discovery 1.0
• JWT Access Tokens (RFC 9068)
• Resource Indicators (RFC 8707)
• DPoP (RFC 9449)
• PAR (RFC 9126)
• Duende IdentityServer Specs — Duende Docs