OAuth & Authentication Concepts

// Server-side token exchange
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: authCode,
    client_id: 'abc123',
    client_secret: process.env.CLIENT_SECRET,
    redirect_uri: 'https://app.com/callback'
  })
});
const { access_token, refresh_token, id_token } = await response.json();

// Generate PKCE code_verifier and code_challenge
function generateCodeVerifier() {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return btoa(String.fromCharCode(...array))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

async function generateCodeChallenge(verifier) {
  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(/=+$/, '');
}

// Usage in authorization URL
const verifier = generateCodeVerifier();
const challenge = await generateCodeChallenge(verifier);
// Store verifier in sessionStorage for later use

const authUrl = `https://auth.example.com/authorize?
  response_type=code&
  client_id=abc123&
  code_challenge=${challenge}&
  code_challenge_method=S256&
  redirect_uri=https://app.com/callback`;

// Client Credentials — server-to-server auth
const response = await fetch('https://auth.example.com/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': `Basic ${btoa(`${CLIENT_ID}:${CLIENT_SECRET}`)}`
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    scope: 'api:read api:write'
  })
});

// Refresh an expired access token
const response = await fetch('https://auth.example.com/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'refresh_token',
    refresh_token: storedRefreshToken,
    client_id: 'abc123'
  })
});
// Returns new { access_token, refresh_token (rotated) }

{
  "iss": "https://auth.example.com",
  "sub": "user_abc123",
  "aud": "https://api.example.com",
  "exp": 1716242622,
  "iat": 1716239022,
  "scope": "openid profile email",
  "roles": ["admin", "editor"],
  "org_id": "org_xyz",
  "email": "john@example.com",
  "email_verified": true
}

// Typically at: https://auth.example.com/.well-known/jwks.json
{
  "keys": [
    {
      "kty": "RSA",            // Key type
      "kid": "key-2024-01",     // Key ID — matches JWT header 'kid'
      "use": "sig",             // Usage: signing
      "alg": "RS256",           // Algorithm
      "n":   "0vx7agoebGc...",  // RSA modulus (Base64URL)
      "e":   "AQAB"             // RSA exponent
    }
  ]
}

// ID token payload (returned when scope includes "openid")
{
  "iss": "https://auth.example.com",
  "sub": "user_abc123",
  "aud": "client_abc123",      // Your app's client_id
  "exp": 1716242622,
  "iat": 1716239022,
  "nonce": "n-0S6_WzA2Mj",    // Prevents replay attacks
  "auth_time": 1716239020,     // When user actually authenticated
  "name": "John Doe",
  "email": "john@example.com",
  "email_verified": true,
  "picture": "https://example.com/john.jpg"
}

{
  "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/.well-known/jwks.json",
  "scopes_supported": ["openid", "profile", "email"],
  "response_types_supported": ["code"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

// Common patterns for API scopes
"scope": "read:users write:users delete:users"    // Resource-based
"scope": "api.read api.write api.admin"            // Namespace-based
"scope": "repos:read gists:write orgs:admin"       // GitHub-style

// POST to introspection endpoint
POST /introspect
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

token=ACCESS_TOKEN&token_type_hint=access_token

// Response
{
  "active": true,
  "sub": "user_abc123",
  "client_id": "my_app",
  "scope": "read write",
  "exp": 1716242622,
  "token_type": "Bearer"
}

// Revoke a token (usually refresh token on logout)
POST /revoke
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

token=REFRESH_TOKEN&token_type_hint=refresh_token

// Returns 200 OK (always, even if token was already invalid)