OAuth 2.0 Flows Explained — Which One to Use and Why

1. User clicks "Login"
2. App redirects to auth server with:
   ?response_type=code
   &client_id=...
   &redirect_uri=https://app.example.com/callback
   &scope=openid profile
   &state=
3. User authenticates at auth server
4. Auth server redirects back: /callback?code=AUTH_CODE&state=...
5. Server validates state, then exchanges code for tokens:
   POST /token
   grant_type=authorization_code
   &code=AUTH_CODE
   &client_id=...
   &client_secret=...   ← server-side only
6. Auth server returns access_token + refresh_token + id_token

// React SPA — Authorization Code + PKCE

function generateCodeVerifier(): string {
  const array = new Uint8Array(64);
  crypto.getRandomValues(array);
  return btoa(String.fromCharCode(...array))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
}

async function generateCodeChallenge(verifier: string): Promise<string> {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const digest = await crypto.subtle.digest('SHA-256', data);
  return btoa(String.fromCharCode(...new Uint8Array(digest)))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
}

async function startLogin() {
  const verifier = generateCodeVerifier();
  const challenge = await generateCodeChallenge(verifier);

  // Store verifier — needed for exchange step
  sessionStorage.setItem('code_verifier', verifier);

  const params = new URLSearchParams({
    response_type: 'code',
    client_id: 'my-spa',
    redirect_uri: 'https://app.example.com/callback',
    scope: 'openid profile api:read',
    state: crypto.randomUUID(),
    code_challenge: challenge,
    code_challenge_method: 'S256'
  });

  window.location.href = `https://auth.example.com/authorize?${params}`;
}

async function handleCallback() {
  const params = new URLSearchParams(window.location.search);
  const code = params.get('code');
  const verifier = sessionStorage.getItem('code_verifier');

  const response = await fetch('https://auth.example.com/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: code!,
      redirect_uri: 'https://app.example.com/callback',
      client_id: 'my-spa',
      code_verifier: verifier!  // Auth server verifies hash matches
    })
  });

  const { access_token, refresh_token, id_token } = await response.json();
  // Store access_token in memory, refresh_token in HttpOnly cookie via your own server
}

// Program.cs
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://auth.example.com";
        options.Audience = "api.example.com";
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidAlgorithms = new[] { "RS256" }
        };
    });

// Controller
[Authorize]
[HttpGet("profile")]
public IActionResult GetProfile()
{
    var userId = User.FindFirst(ClaimTypes.NameIdentifier)?.Value;
    var scopes = User.FindFirst("scope")?.Value?.Split(' ') ?? [];

    if (!scopes.Contains("api:read"))
        return Forbid();

    return Ok(new { UserId = userId });
}

POST /token
grant_type=client_credentials
&client_id=service-a
&client_secret=...
&scope=reports:read

// ASP.NET Core — calling a downstream API with client credentials
services.AddHttpClient("ReportService")
    .AddClientCredentialsTokenHandler(); // from Duende.AccessTokenManagement

// The library handles token caching and renewal automatically

1. Device: POST /device_authorization
   → response: { device_code, user_code: "GFKJ-QNTS", verification_uri, expires_in }
2. Device displays: "Go to example.com/activate, enter GFKJ-QNTS"
3. Device polls: POST /token (grant_type=urn:ietf:params:oauth:grant-type:device_code)
   → responds with "authorization_pending" until user approves
4. User approves on phone
5. Device poll returns tokens

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

openid          — OIDC: include an ID token
profile         — OIDC: name, picture, etc.
email           — OIDC: email address
api:read        — custom: read-only access to the API
api:write       — custom: write access
reports:export  — custom: specific feature