Understand the key differences between OAuth 2.0 and 2.1, including PKCE requirements, deprecated flows, and a step-by-step migration guide for secure authentication.
OAuth 2.1 consolidates years of security best practices into a single, coherent specification. While OAuth 2.0 provided flexibility, that flexibility enabled insecure patterns. OAuth 2.1 removes the dangerous options and mandates secure defaults.
The specification is not a major protocol overhaul—it is OAuth 2.0 with mandatory security measures and deprecated features removed. If you follow current best practices, you are likely already OAuth 2.1 compliant. If not, migration is straightforward.
This guide covers the key differences, explains why each change improves security, and provides a practical migration path. Use the JWT Decoder to inspect your tokens during migration and verify they contain the expected claims.
OAuth 2.1 makes several security measures mandatory that were optional or documented elsewhere in OAuth 2.0.
PKCE (Proof Key for Code Exchange) is now required for all authorization code grants, not just public clients. This prevents authorization code interception attacks.
The implicit grant is removed entirely. It exposed tokens in URLs and browser history, creating security risks that the newer approaches avoid.
The resource owner password credentials grant is removed. Collecting passwords in your application, even to exchange for tokens, undermines the entire point of OAuth.
Refresh tokens must be sender-constrained or rotated. This prevents stolen refresh tokens from being used indefinitely.
Exact redirect URI matching is required. No more wildcard or partial matching that could enable redirect attacks.
PKCE was originally designed for mobile and single-page applications that cannot securely store client secrets. OAuth 2.1 requires it for all clients, including confidential clients with secrets.
The PKCE flow adds a code verifier and code challenge. Before authorization, the client generates a random code_verifier and computes its SHA256 hash as the code_challenge. The challenge goes with the authorization request; the verifier goes with the token request.
This proves the same client that initiated authorization is completing it. Even if an attacker intercepts the authorization code, they cannot exchange it without the original code_verifier.
Implementation is straightforward: generate a random string (43-128 characters), compute its SHA256 hash, Base64url-encode the hash as the challenge. Most OAuth libraries handle this automatically.
OAuth 2.1 removes two flows that were already discouraged in practice.
The implicit grant (response_type=token) returned access tokens directly in the URL fragment. This exposed tokens in browser history, server logs, and referrer headers. The authorization code flow with PKCE is secure and not significantly more complex.
The password grant (grant_type=password) had applications collect user credentials directly. This trains users to enter passwords in arbitrary applications, undermines phishing protection, and prevents authorization server security measures like MFA.
If you currently use these flows, migration to authorization code with PKCE is required. This is more work initially but provides better security and user experience.
OAuth 2.1 strengthens token handling to prevent theft and misuse.
Access tokens should be short-lived. Long-lived tokens increase the window for theft and abuse. OAuth 2.1 emphasizes this practice without mandating specific lifetimes.
Refresh tokens must be either sender-constrained (bound to the client that requested them) or rotated on each use. Rotation means each refresh token can only be used once—using it again indicates theft.
Token type hints in introspection and revocation requests are now properly defined. This prevents confusion about which token is being inspected or revoked.
Use the JWT Decoder to inspect your access tokens. Verify they contain appropriate claims, reasonable expiration times, and audience restrictions.
Understanding the different roles of access and refresh tokens helps you implement them securely.
Access tokens authorize specific actions. They should be short-lived (minutes to hours) and contain minimal claims. Do not store sensitive data in access tokens as they travel with every request.
Refresh tokens obtain new access tokens. They should be longer-lived but still expire. Store them securely—in HTTP-only cookies for web applications, secure storage for mobile apps.
Rotate refresh tokens on use. When a client exchanges a refresh token for new tokens, issue a new refresh token and invalidate the old one. If the old token is used again, revoke all tokens for that session.
Consider token binding where supported. DPoP (Demonstrating Proof of Possession) binds tokens to cryptographic keys, preventing stolen tokens from being used by attackers.
Migration to OAuth 2.1 can be done incrementally. This checklist helps you prioritize and track changes.
Audit current usage. Document which OAuth flows your applications use, where tokens are stored, and how refresh tokens are handled. This reveals what needs to change.
Implement PKCE for all clients. Even confidential clients with secrets should use PKCE. Update client libraries and authorization server configurations.
Remove implicit and password grants. This may require significant client application changes. Plan user communication for workflow changes.
Implement refresh token rotation. Configure your authorization server to issue new refresh tokens on each use and detect reuse attempts.
Enforce exact redirect URI matching. Remove any wildcard or partial matching. Verify each registered redirect URI is necessary and specific.
After migration, thorough testing ensures security and functionality.
Test the authorization code flow with PKCE. Verify the challenge and verifier are properly generated and validated. Attempt to exchange a code without the correct verifier—it should fail.
Test refresh token rotation. Exchange a refresh token, then attempt to use the old token. The second use should fail and potentially trigger security alerts.
Test redirect URI validation. Attempt authorization with modified redirect URIs. Only exact matches should succeed.
Use the JWT Decoder to inspect issued tokens. Verify claims are correct: issuer, audience, expiration, scope, and any custom claims your application requires.
Test error handling. Expired tokens, invalid tokens, and revoked tokens should produce appropriate error responses without exposing sensitive information.
The JWT Decoder is invaluable during OAuth implementation and debugging.
Decode access tokens to verify claims. Check that the issuer (iss), audience (aud), and subject (sub) are correct. Verify expiration (exp) is reasonable and scope claims match requested permissions.
Verify token structure. OAuth 2.1 access tokens can be either reference tokens (opaque strings) or self-contained JWTs. If using JWTs, verify the header specifies appropriate algorithm (RS256, ES256) not weak options like HS256 without proper key management.
Debug authentication failures. When tokens are rejected, decode them to see why. Common issues include expired tokens, wrong audience, or missing required claims.
Never paste production tokens with real user data into untrusted tools. The JWT Decoder processes tokens locally in your browser, but develop good habits.
Certain mistakes appear frequently during OAuth 2.1 migration. Anticipating them speeds your implementation.
PKCE implementation errors. The code verifier must be random and the correct length (43-128 characters). The challenge must be properly Base64url-encoded (URL-safe Base64 without padding). Mismatches cause token requests to fail.
Incomplete flow removal. Disabling implicit grant on the authorization server while clients still request it produces confusing errors. Coordinate client and server changes.
Refresh token rotation without client updates. Clients must expect new refresh tokens on each use and handle rotation failures gracefully. Old clients may not store the new tokens correctly.
Redirect URI mismatches. Exact matching is strict. Trailing slashes, port numbers, and scheme all matter. Audit all registered redirect URIs carefully.
Testing only happy paths. Security testing requires attempting bypass and abuse. Try using old refresh tokens, wrong PKCE verifiers, and modified redirect URIs.
OAuth 2.1 compliance positions you well for future security developments.
The OAuth working group continues developing security extensions. DPoP for token binding, RAR (Rich Authorization Requests) for fine-grained permissions, and PAR (Pushed Authorization Requests) for enhanced security are emerging standards.
Keep client libraries updated. Security fixes and new feature support arrive regularly. Outdated libraries may have known vulnerabilities or lack support for newer security measures.
Monitor OAuth security advisories. New attack vectors are discovered periodically. Staying informed helps you assess risk and implement mitigations.
Consider moving to OpenID Connect if you need identity information. OIDC builds on OAuth 2.0/2.1 and standardizes identity tokens and user info endpoints.
OAuth 2.1 removes flows that were already discouraged (implicit, password grant) and mandates practices that were already recommended (PKCE, refresh token rotation). If you follow current best practices, your implementation may already be OAuth 2.1 compliant. The changes are significant for implementations using deprecated flows.
PKCE protects against authorization code interception attacks regardless of client type. Even confidential clients with secrets can have codes intercepted through browser vulnerabilities, malicious extensions, or network attacks. PKCE is a simple addition that provides defense in depth for all clients.
Replace implicit flow with authorization code flow using PKCE. Your SPA will request authorization codes instead of tokens, then exchange codes for tokens via a token request. This adds one step but keeps tokens out of URLs and browser history. Most modern OAuth libraries support this natively.
Refresh token reuse after rotation indicates potential theft. Best practice is to revoke all tokens for that session when reuse is detected. The legitimate user and attacker both lose access, but the attacker cannot continue. The user must re-authenticate, which alerts them to potential compromise.
Use the JWT Decoder to inspect issued tokens and verify correct claims. Test PKCE validation by attempting token exchange with wrong verifiers. Test redirect URI matching with modified URIs. Attempt refresh token reuse after rotation. Consider professional security testing for high-value applications.
JWTs as access tokens work well for distributed validation without database lookups. However, they cannot be revoked instantly (only at expiration) and expose claims to anyone with the token. Reference tokens (opaque strings) require validation against the authorization server but support instant revocation. Choose based on your architecture needs.
Founder of CodeUtil. Web developer building tools I actually use. When I'm not coding, I experiment with productivity techniques (with mixed success).
SQL injection is still the #1 web attack. Learn the real difference between escaping and parameterized queries — with code examples in Python, PHP, and Node.js — and why one method leaves you exposed.
Learn how JWT claims work, explore registered, public, and private claims, and discover security best practices for implementing JSON Web Tokens in your applications.
Learn why password hashing matters, why MD5 is broken for security, how SHA-256 differs, and why bcrypt and Argon2 are the right choice for storing passwords. Understand rainbow tables, salting, and modern best practices.