OAuth/OIDC Debugger

Debug OAuth 2.0 and OpenID Connect flows. Decode JWTs, generate PKCE challenges, validate redirect URIs, and troubleshoot OAuth errors.

What the OAuth/OIDC Debugger Does

OAuth 2.0 and OpenID Connect break in subtle ways — a malformed redirect URI, a missing scope, a mismatched PKCE verifier. This tool gives you the pieces needed to inspect and reason about a flow without standing up a full client:

  • JWT decoder — read the header, claims, and signature segments of access and ID tokens.
  • PKCE generator — produce a code_verifier and its derived code_challenge (S256).
  • Flow tester — walk through authorization-code and related grants.
  • Error troubleshooting — map opaque error codes to likely causes.

Key Concepts

OAuth 2.0 is authorization (delegated access via tokens); OpenID Connect layers authentication on top, adding the ID token — a JWT asserting who the user is. PKCE protects the authorization-code flow against interception by binding the code exchange to a secret the attacker never sees; it is now recommended for all clients, not just mobile.

Decode Tokens Carefully

A JWT is Base64url-encoded, not encrypted — anyone holding it can read its claims. Decoding shows you iss, aud, exp, nbf, and scopes, which is exactly what you check when access is wrongly granted or denied. Decoding does not verify the signature; never trust a token's contents without validating the signature and issuer server-side. Treat real tokens as secrets even while debugging.

When to Reach for It

  • A redirect returns invalid_grant or redirect_uri_mismatch.
  • An ID token is rejected and you need to inspect aud/exp.
  • You are wiring up PKCE and need matching verifier/challenge values to test.

When you only need to crack open a token's payload, the Base64 Encoder / Decoder handles the raw segments.

Debug OAuth and OIDC Flows

Test OAuth 2.0 authorization flows and decode OIDC tokens. Essential for authentication troubleshooting.

Supported Flows

  • Authorization Code (with PKCE)
  • Client Credentials
  • Implicit (legacy)
  • Device Code

Token Analysis

Decode access tokens and ID tokens. Verify signatures, check claims, validate expiration.

How JWT Decoding Works

JWT Token Structure

A JWT token consists of three parts separated by dots (.):

  1. Header - Contains metadata about the token type and signing algorithm
  2. Payload - Contains claims (statements about the user and additional data)
  3. Signature - Used to verify the token hasn't been tampered with

Decoding Process

Each part is Base64URL encoded. To decode a JWT:

  1. Split the token by the dot (.) separator
  2. Base64URL decode each part
  3. Parse the header and payload as JSON
  4. The signature remains as a Base64URL string

Important Security Note

Decoding a JWT does not verify its signature. Anyone can decode a JWT and read its contents. Always verify the signature server-side before trusting the claims in a token.

PKCE Implementation Guide

Implementing PKCE in Your Application

PKCE (Proof Key for Code Exchange) adds security to the OAuth authorization code flow. Here's how to implement it:

Step 1: Generate Code Verifier

Create a cryptographically random string (43-128 characters):

  • Use a secure random number generator
  • Encode as Base64URL
  • Store securely in your application

Step 2: Create Code Challenge

Compute the SHA-256 hash of the code verifier and encode it as Base64URL:

code_challenge = BASE64URL(SHA256(code_verifier))

Step 3: Authorization Request

Include these parameters in your authorization URL:

  • code_challenge - The computed challenge
  • code_challenge_method - Set to "S256"

Step 4: Token Exchange

When exchanging the authorization code for tokens, include:

  • code_verifier - The original verifier (NOT the challenge)

The authorization server will verify that SHA256(code_verifier) matches the code_challenge from the authorization request.

Common OAuth Error Solutions

Troubleshooting OAuth Errors

invalid_grant

Most Common Causes:

  1. Authorization code expired (typically >10 minutes)
  2. Code was already used (single-use only)
  3. Redirect URI mismatch

Solutions:

  • Ensure code exchange happens quickly
  • Never reuse authorization codes
  • Use exact redirect_uri in both requests

invalid_client

Most Common Causes:

  1. Wrong client_id or client_secret
  2. Client authentication method mismatch

Solutions:

  • Verify credentials match your provider dashboard
  • Check if using correct auth method (basic, post, jwt)

unauthorized_client

Most Common Causes:

  1. Grant type not enabled for client
  2. Redirect URI not registered

Solutions:

  • Enable required grant types in provider settings
  • Register all redirect URIs (exact match required)

access_denied

Most Common Causes:

  1. User clicked "Deny" on consent screen
  2. User lacks required permissions

Solutions:

  • Handle denial gracefully in your app
  • Request only necessary scopes
  • Provide clear explanation of why permissions are needed

OAuth Security Best Practices

Securing Your OAuth Implementation

1. Always Use PKCE

PKCE is no longer just for public clients. Use it for all OAuth flows to prevent authorization code interception attacks.

2. Short-Lived Access Tokens

Keep access tokens short-lived (5-15 minutes). Use refresh tokens for longer sessions.

3. Validate State Parameter

Always generate a unique state parameter for each authorization request and validate it on callback. This prevents CSRF attacks.

4. Exact Redirect URI Matching

Never use wildcards or regex for redirect URIs. OAuth requires exact string matching for security.

5. Verify Token Signatures

Always verify JWT signatures server-side before trusting token contents. Don't skip this step!

6. Check Token Expiration

Validate the exp claim and reject expired tokens. Don't accept tokens without expiration.

7. Secure Token Storage

  • Never store tokens in localStorage (vulnerable to XSS)
  • Use httpOnly cookies for refresh tokens
  • Store access tokens in memory when possible

8. Use HTTPS Everywhere

Never use OAuth over unencrypted HTTP in production. All endpoints must use HTTPS.

9. Implement Token Rotation

Rotate refresh tokens on each use to limit exposure if compromised.

10. Limit Scope Permissions

Request only the minimum scopes your application needs. Follow the principle of least privilege.

Need Help Implementing OAuth/OIDC?

Our security experts can help you implement secure OAuth 2.0 and OpenID Connect authentication in your applications. We provide architecture review, implementation guidance, and security audits for your authentication systems.

Get Security AssessmentLearn About DevSecOps

Frequently Asked Questions

How do I decode a JWT token?+

Paste your JWT token into the "JWT Decoder" tab. The tool will automatically decode the header, payload, and signature. You'll see all claims with syntax highlighting, validation status, and expiration warnings. Optionally provide a secret to verify the signature. All decoding happens in your browser - tokens are never sent to any server.

What is PKCE and why should I use it?+

PKCE (Proof Key for Code Exchange) is a security extension to OAuth 2.0 that prevents authorization code interception attacks. It's required for mobile and single-page applications (SPAs) and recommended for all OAuth clients. Use the "PKCE Generator" tab to create a code verifier and code challenge. Send the challenge during authorization and the verifier during token exchange.

How do I test an OAuth authorization flow?+

Go to the "Flow Tester" tab, select your OAuth flow type (Authorization Code, PKCE, etc.), fill in the required parameters (client_id, redirect_uri, scope), and click "Generate Authorization URL". Copy the URL and open it in a new tab to start the OAuth flow. The tool will help you understand each step and provide examples for token exchange.

Why is my redirect URI validation failing?+

OAuth requires exact string matching for redirect URIs. Common issues include: trailing slash differences (/callback vs /callback/), protocol mismatches (http vs https), port numbers (localhost:3000 vs localhost:8080), and query parameters. Use the "Redirect Validator" tab to compare your URIs character-by-character and see exactly what's different.

What does "invalid_grant" error mean?+

'invalid_grant' is the most common OAuth error with multiple possible causes. The top three are: (1) authorization code expired (usually >10 minutes old), (2) code was already used (codes are single-use), and (3) redirect_uri mismatch between authorization and token requests. Use the "Error Debugger" tab for detailed troubleshooting steps ranked by likelihood.

Is it safe to paste production tokens into this tool?+

Yes - all token processing happens entirely in your browser using JavaScript. No tokens, secrets, or sensitive data are sent to any server or stored permanently. The tool uses browser sessionStorage (cleared when you close the tab) and never logs data to analytics. However, always be cautious with production secrets and use development/test tokens when possible.

How do I verify JWT signatures? Why doesn't this tool verify them?+

JWT signature verification requires access to the secret key (for HMAC algorithms like HS256) or the public key (for asymmetric algorithms like RS256/ES256). Since this is a client-side tool and we never store, transmit, or have access to your signing keys, we cannot verify signatures. This tool is designed for inspecting and understanding JWT structure, debugging claims, and analyzing algorithms - not for production authentication. Always verify JWT signatures server-side using proper cryptographic libraries before trusting the token contents.

What OAuth flows should I use for my application?+

For server-side web apps: Authorization Code Flow (with client secret). For mobile apps and SPAs: Authorization Code Flow with PKCE. For backend service-to-service: Client Credentials Flow. Avoid legacy flows: Implicit Flow and Resource Owner Password Flow are deprecated due to security concerns. See the "Flow Tester" tab for detailed descriptions.

How do I generate a secure PKCE code verifier and challenge?+

Go to the "PKCE Generator" tab and click "Generate New PKCE Pair". The tool creates a cryptographically random code verifier (256 bits of entropy) and computes the code challenge using SHA-256 (S256 method, recommended) or plain method. Copy the challenge for your authorization request and keep the verifier for token exchange.

What are common JWT security vulnerabilities I should know about?+

Major JWT vulnerabilities include: (1) Algorithm confusion attacks - changing "alg" to "none" or switching from RS256 to HS256 to forge tokens. (2) Weak signing secrets - short or common secrets that can be brute-forced. (3) Missing signature verification - accepting tokens without validating signatures. (4) Missing expiration claims - tokens that never expire, allowing indefinite access if stolen. (5) Token storage issues - storing JWTs in localStorage where XSS attacks can steal them. (6) Accepting untrusted algorithms - not enforcing algorithm allowlists. Always use strong algorithms (RS256, ES256), verify signatures, include expiration claims, and store tokens securely.

When should I use JWT vs traditional session tokens?+

Use JWTs when: You need stateless authentication across distributed systems, APIs, or microservices; implementing single sign-on (SSO); mobile apps need offline access; scaling horizontally without shared session storage. Use session tokens when: You need instant token revocation (logout); managing long-lived sessions; security is paramount (JWTs can't be invalidated once issued until expiration); working with traditional server-rendered apps. JWTs are self-contained and stateless (don't require server-side session storage), while session tokens require a session store but offer better revocation control.

What's the difference between HS256 and RS256 algorithms?+

HS256 (HMAC-SHA256) is a symmetric algorithm where the same secret key is used for both signing and verifying tokens. This means anyone who can verify tokens can also create them, making key distribution risky. RS256 (RSA-SHA256) is an asymmetric algorithm where a private key signs tokens and a separate public key verifies them. Only the authorization server with the private key can create tokens, but any service can verify tokens using the widely-distributed public key. RS256 is recommended for distributed systems, while HS256 may be acceptable for simple, single-server applications where the secret never leaves the server.

How do JWT expiration and refresh tokens work together?+

JWT access tokens should have short lifespans (5-15 minutes) to limit exposure if stolen. When the access token expires, applications use a separate refresh token (stored securely, often in httpOnly cookies) to obtain a new access token without requiring the user to log in again. Refresh tokens have longer lifespans (days to weeks) and are used only with the authorization server, never sent to resource APIs. This two-token pattern balances security (short-lived access) with user experience (no constant re-authentication). The refresh token can be revoked server-side for instant logout, while access tokens remain stateless.

Related tools

JWT Decoder & Validator

Decode and inspect JWT tokens instantly. View header, payload, and verify signatures with security validation.

Base64 Encoder/Decoder

Encode and decode Base64 strings for data transport, email attachments, and web development

JSON Formatter

Format, validate, and beautify JSON data with syntax highlighting and error detection

Hash Generator - MD5, SHA-256, SHA-512

Generate MD5, SHA-1, SHA-256, and SHA-512 hashes from text or files. HMAC support, multiple output formats, 100% client-side.

Password Strength Checker

Check how strong your password is with entropy analysis, crack time estimates, and breach database checks via Have I Been Pwned. 100% client-side.

This tool is provided for informational and educational purposes only. All processing happens in your browser — no data is sent to or stored on our servers. While we strive for accuracy, we make no warranties about the completeness or reliability of results.