OAuth2 Troubleshooting Guide

This document outlines the 10 most common OAuth2 issues, how to identify them, and steps to resolve or investigate each one.

Use this guide when debugging authentication, token exchange, or authorization problems in your OAuth2 server or clients.

Table of Contents

  1. Invalid Redirect URI

  2. Invalid Client Credentials

  3. Invalid or Expired Authorization Code

  4. Invalid or Expired Access Token

  5. Missing or Incorrect Scopes

  6. Clock Skew and Token Validation Failures

  7. Missing HTTPS / Invalid Certificates

  8. Incorrect Grant Type

  9. CORS (Cross-Origin Resource Sharing) Errors

  10. Refresh Token Issues Additional Troubleshooting Tools

1. Invalid Redirect URI

Symptom: redirect_uri_mismatch or invalid_request errors.

Cause: The redirect URI in the authorization request does not exactly match one registered with the authorization server.

Fix:

  • Ensure the redirect URI is identical, including protocol (https vs http), port, path, and trailing slash.

  • Check the client’s registered URIs in your OAuth2 configuration.

  • Update the client registration to match the exact URI used by the application.

2. Invalid Client Credentials

Symptom: “Invalid client,” “unauthorized client,” or HTTP 401.

Cause: Incorrect client_id or client_secret, or client not authorized for the requested grant type.

Fix:

  • Verify the correct credentials are being used.

  • Confirm that the grant type (e.g., client credentials, authorization code) is enabled for the client.

  • Rotate or reissue secrets if necessary.

3. Invalid or Expired Authorization Code

Symptom: “Invalid_grant” when exchanging authorization code for a token.

Cause: The code was already used, expired, or issued for a different client or redirect URI.

Fix:

  • Ensure the code is exchanged only once and promptly after issuance.

  • Use the same redirect URI in both authorization and token requests.

  • Verify the authorization code lifetime configuration (commonly 1–5 minutes).

4. Invalid or Expired Access Token

Symptom: API calls return HTTP 401 or “invalid_token.”

Cause: Access token expired or was revoked.

Fix:

  • Inspect the token’s exp (expiration) field.

  • Implement refresh tokens for short-lived access tokens.

  • Use token introspection or revocation endpoints to confirm status.

5. Missing or Incorrect Scopes

Symptom: User denied access to specific resources or “insufficient_scope” errors.

Cause: Token lacks required scopes for the requested resource.

Fix:

  • Check requested scopes during authorization.

  • Ensure the resource server properly validates and enforces scope requirements.

  • Adjust client configuration if scopes were changed or restricted.

6. Clock Skew and Token Validation Failures

Symptom: “Token expired” or “token not yet valid” immediately after issuance.

Cause: System clock mismatch between OAuth2 server and resource servers.

Fix:

  • Synchronize all servers using NTP (Network Time Protocol).

  • Allow small tolerance (e.g., ±60 seconds) when validating token timestamps (iat, exp).

7. Missing HTTPS / Invalid Certificates

Symptom: SSL/TLS or “invalid_request” errors during OAuth2 flow.

Cause: Insecure connections (http://) or invalid certificates.

Fix:

  • Enforce HTTPS for all endpoints (authorization, token, introspection, revocation).

  • Validate SSL/TLS certificates and intermediate CAs.

  • Update reverse proxy or load balancer settings if necessary.

8. Incorrect Grant Type

Symptom: “unsupported_grant_type.”

Cause: The request’s grant_type parameter is missing or unsupported by the server.

Fix:

  • Verify that grant_type is correctly specified (authorization_code, refresh_token, etc.).

  • Confirm that the grant type is enabled in the server configuration for that client.

9. CORS (Cross-Origin Resource Sharing) Errors

Symptom: Browser console errors when performing OAuth2 flows in SPAs.

Cause: Missing or incorrect CORS headers on OAuth2 endpoints.

Fix:

  • Add proper Access-Control-Allow-Origin headers for authorized domains.

  • Prefer Authorization Code Flow with PKCE instead of Implicit Flow for browser-based apps.

10. Refresh Token Issues

Symptom: “invalid_grant” when using refresh tokens, or refresh token stops working.

Cause: Refresh token expired, revoked, or reused incorrectly.

Fix:

  • Check refresh token lifetime and revocation logic.

  • Verify token belongs to the same client and user session.

  • Review rotation logic if using Refresh Token Rotation (RFC 6819).

Additional Troubleshooting Tools

  • Enable verbose logging on the authorization server to capture full request/response cycles.

  • Use tools like Postman, curl, or OAuth2 Playground for step-by-step validation.

  • Always inspect the error_description field in OAuth2 error responses for specific details.

  • Consider monitoring your token endpoints with a test client to detect early regressions.

PreviousTroubleshootingNextApp template store

Last updated