OAuth 2.1

OAuth 2.1 is the consolidation of OAuth 2.0 and its best practices into a single standard. It allows third-party applications to grant limited access to an HTTP service through an authorization server.

When to Use

• Delegated Authorization Framework: Permitting third-party applications to access user resources without exposing user passwords.
• Single Sign-On (SSO) Architectures: Authorizing cross-application access tokens across interconnected enterprise platforms.
• Securing Public and Mobile APIs: Implementing standards-compliant token issuance, verification, and revocation.
• Machine-to-Machine Service Accounts: Granting automated microservice background daemons scoped API access.

Quick Start

// Client (Frontend) - redirect to Auth Server
const authUrl = `https://auth.example.com/authorize?
  response_type=code&
  client_id=${CLIENT_ID}&
  redirect_uri=${REDIRECT_URI}&
  scope=read:profile&
  code_challenge=${pkceChallenge}&
  code_challenge_method=S256`;

window.location.href = authUrl;

// Callback (Handling the redirect)
const code = new URLSearchParams(window.location.search).get("code");
const tokenResponse = await fetch("https://auth.example.com/token", {
  method: "POST",
  body: JSON.stringify({
    grant_type: "authorization_code",
    code,
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    code_verifier: pkceVerifier, // Proof Key
  }),
});

Core Concepts

The 4 OAuth 2.0 / 2.1 Grant Types

Proof Key for Code Exchange (PKCE) Protocol Flow

Protects authorization codes from interception on public clients:

[ Client ] ──1. Generate Verifier & Challenge (SHA256)──→ Local
[ Client ] ──2. GET /authorize?code_challenge=xyz───────→ [ Auth Server ]
[ Client ] ←─3. Receive Authorization Code─────────────── [ Auth Server ]
[ Client ] ──4. POST /token?code=123&code_verifier=abc──→ [ Auth Server ]
[ Client ] ←─5. Receive Access Token & Refresh Token───── [ Auth Server ]

Scopes & Consent Management

Defines granular operational permissions approved by the resource owner:

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

grant_type=client_credentials
&client_id=service_analytics
&client_secret=supersecret
&scope=read:reports%20export:csv

Common Patterns

Authorization Code Flow with PKCE (Proof Key for Code Exchange)

Problem: Public clients (SPAs, mobile apps) cannot safely store client secrets, making authorization codes vulnerable to interception.

Solution: Generate cryptographic code verifier and code challenge on the client before initiating authorization:

// Generate Code Verifier and S256 Challenge
const verifier = generateRandomString(64);
const challenge = base64UrlEncode(sha256(verifier));

// Redirect user to authorization endpoint
const authUrl =
  `https://auth.example.com/oauth/authorize?` +
  `response_type=code&client_id=spa-client&` +
  `redirect_uri=${encodeURIComponent(redirectUri)}&` +
  `code_challenge=${challenge}&code_challenge_method=S256`;

Best Practices

Do:

• Enforce OAuth 2.1 Recommendations: Deprecate legacy Implicit Grant and Resource Owner Password Credentials (ROPC) completely.
• Mandate PKCE for All Authorization Code Flows: Require PKCE for confidential clients as well as public clients.
• Implement Refresh Token Rotation: Invalidate previous refresh tokens upon each exchange to detect token reuse and theft immediately.
• Validate Redirect URIs Strictly: Use exact string matching against registered redirect URIs; never use wildcard regular expressions.

Don't:

• Use OAuth 2.0 for Authentication without OpenID Connect: OAuth provides authorization (access tokens); OIDC adds authentication (ID tokens).
• Pass access tokens in URL query strings: Query parameters leak into browser histories, server access logs, and referrer headers.
• Grant broad wildcard scopes: Enforce least privilege by issuing fine-grained scopes tailored to the application's actual needs.

Troubleshooting

References

• OAuth 2.1 Draft
• OAuth 2.0 Simplified