OAuth 2.0 and OpenID Connect — Identity Reference

1
2
3
4
5
6
7
8

OAuth 2.0  ->  authorization: may this client call this API?
OIDC       ->  authentication : who is the user?

ID token      -> for the client. "This is Ana, authenticated at 10:04."
                 audience = client_id. Never send it to an API.
Access token  -> for the resource server. audience = the API.
                 The API validates it and reads scopes/roles from it.
Refresh token -> for the client only, to obtain new access tokens.

1
2
3
4
5
6
7

// Which flow? Two questions.
// 1. Is there a user in front of the screen?
//    yes -> authorization code + PKCE
//    no  -> client credentials
// 2. Can the client keep a secret? (server-side)
//    yes -> confidential client, secret or certificate
//    no  -> public client, PKCE required, no secret shipped

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

1. Client generates:  code_verifier (43-128 chars, random)
                      code_challenge = BASE64URL(SHA256(code_verifier))

2. Browser redirect:
   GET /authorize
     ?response_type=code
     &client_id=orders-web
     &redirect_uri=https://app.example.com/callback
     &scope=openid profile orders.read
     &state=<random, verified on return>
     &nonce=<random, verified inside the ID token>
     &code_challenge=<challenge>&code_challenge_method=S256

3. Authorization server authenticates the user, redirects back with ?code=...&state=...

4. Client exchanges the code, server-to-server:
   POST /token
     grant_type=authorization_code&code=<code>
     &redirect_uri=...&client_id=orders-web
     &code_verifier=<the original verifier>

5. Response: access_token, id_token, refresh_token (optional), expires_in

1
2
3
4
5
6
7
8
9
10
11
12

{
  "iss": "https://login.example.com/",        // issuer  - validate
  "aud": "orders-api",                       // audience - validate
  "sub": "8f14e45f-...",                     // user id - stable
  "scp": "orders.read orders.write",         // scopes (Entra: scp, others: scope)
  "roles": ["OrderManager"],                 // app roles, if configured
  "exp": 1747051200, "nbf": 1747047600,      // lifetime - validate with small skew
  "iat": 1747047600,
  "tid": "0e9f2fce-..."                      // tenant, for multi-tenant APIs
}

// Header: {"alg":"RS256","kid":"k-2025-05"} -> RS256, key selected by kid

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(o =>
    {
        o.Authority = "https://login.example.com";     // OIDC discovery + JWKS
        o.Audience = "orders-api";
        o.MapInboundClaims = false;                    // keep "sub", "scp" as issued
        o.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ClockSkew = TimeSpan.FromSeconds(30),
            NameClaimType = "sub"
        };
    });

app.UseAuthentication();
app.UseAuthorization();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("orders:read", p => p
        .RequireClaim("scp", "orders.read")
        .AddRequirements(new MinimumTenantRequirement()));

    o.AddPolicy("orders:approve", p => p
        .RequireAuthenticatedUser()
        .RequireRole("OrderManager")
        .RequireClaim("scp", "orders.write"));
});

[Authorize(Policy = "orders:approve")]
[HttpPost("orders/{id:guid}/approve")]
public async Task<IActionResult> Approve(Guid id) { ... }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// Server-side token store, minimal shape
public sealed record RefreshToken(string Hashed, string FamilyId, DateTime ExpiresAt, bool Revoked);

async Task<TokenResponse> RefreshAsync(string presented)
{
    var stored = await _store.FindAsync(Hash(presented))
        ?? throw new SecurityTokenException("Unknown refresh token");

    if (stored.Revoked)
    {
        await _store.RevokeFamilyAsync(stored.FamilyId);    // reuse detected
        throw new SecurityTokenException("Refresh token reuse");
    }

    var next = await _idp.RefreshAsync(presented);
    await _store.RevokeAsync(stored);
    await _store.SaveAsync(Hash(next.RefreshToken), stored.FamilyId, next.ExpiresAt);
    return next;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// Program.cs - .NET 8 with Microsoft.Identity.Web
builder.Services.AddMicrosoftIdentityWebAppAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

// Typed client: the handler attaches the token, the caller never sees it
builder.Services.AddHttpClient<IPricingClient, PricingClient>(c =>
    c.BaseAddress = new Uri("https://pricing.internal/"));

public sealed class PricingClient(HttpClient http, ITokenAcquisition tokens)
{
    public async Task<Price?> GetAsync(string sku)
    {
        var token = await tokens.GetAccessTokenForAppAsync("api://pricing/.default");
        http.DefaultRequestHeaders.Authorization = new("Bearer", token);
        return await http.GetFromJsonAsync<Price>($"/prices/{sku}");
    }
}

1
2
3
4
5
6
7
8
9
10
11

Browser  <->  BFF (same origin, cookie)  <->  API (bearer token)

BFF responsibilities:
  - OIDC login/logout, holds access + refresh tokens server-side
  - sets an HttpOnly, Secure, SameSite=Lax session cookie
  - proxies /api/* to the real API, attaching the bearer token
  - CSRF protection on state-changing requests
  - silent renewal with the refresh token, invisible to the SPA

Why: XSS can still act as the user, but it cannot exfiltrate a token
that was never in the browser, and revocation happens server-side.

1
2
3
4
5
6
7
8
9

# RP-initiated logout
GET https://login.example.com/logout
  ?id_token_hint=<id_token>
  &post_logout_redirect_uri=https://app.example.com/signed-out
  &client_id=orders-web

# .NET: clear the local cookie too, always
await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
return Redirect(logoutUrl);

1
2
3
4
5
6
7

// What a good review looks like at the middleware level
o.Authority = "https://login.example.com";   // iss + JWKS from discovery
o.Audience  = "orders-api";                  // aud must be us
o.RequireHttpsMetadata = true;
o.MapInboundClaims = false;
o.TokenValidationParameters.ValidAlgorithms = ["RS256"];   // no alg confusion
o.TokenValidationParameters.ClockSkew = TimeSpan.FromSeconds(30);

1
2
3
4
5
6
7

1. Decode the token (payload only) and read: iss, aud, exp, scp/roles, tid
2. Compare aud with the API's expected audience, exactly
3. Compare iss with Authority, including the trailing slash
4. Check exp/nbf against the server clock, not your laptop's
5. If signature fails: does the kid exist in {authority}/.well-known/openid-configuration -> jwks_uri?
6. If claims are missing: MapInboundClaims and the mapping table renamed them
7. Still 401? Enable PII logging in development, never in production

1
2
3
4
5
6

// Decision shortcut
// Users + modern app        -> OIDC
// Enterprise IdP, no OIDC   -> SAML 2.0 (bridge it if you can)
// Service inside a mesh     -> mTLS, or workload identity
// Public API, third parties -> OAuth 2.0 client credentials per partner
// Internal script, one team -> API key only if it can be rotated and scoped