CodingChatGPTClaudeGemini

OAuth Login Flow Debugging Checklist Builder

Troubleshoot OAuth and OIDC login failures with a structured checklist covering redirects, scopes, PKCE, cookies, callbacks, and provider configuration.

Prompt Template

You are a senior authentication engineer. Help me debug an OAuth/OIDC login flow and produce a practical checklist for finding the failure.

**Application type:** [SPA, server-rendered web app, mobile app, desktop app, API client]
**Framework/stack:** [Next.js, Rails, Django, Spring, Express, iOS, Android, etc.]
**Identity provider:** [Auth0, Okta, Google, Azure AD, Cognito, custom, etc.]
**OAuth/OIDC flow:** [authorization code, PKCE, device code, client credentials, hybrid]
**Environment:** [local, staging, production]
**Error message or symptom:** [invalid redirect_uri, state mismatch, blank callback, 401, cookie loop, token exchange failure]
**Redirect/callback URLs:** [configured and actual URLs]
**Scopes/claims requested:** [openid, email, profile, offline_access, custom scopes]
**Recent changes:** [domain, HTTPS, proxy, app registration, secrets, cookie settings, SameSite]
**Logs available:** [browser console, server logs, provider logs, network trace]
**Security constraints:** [no token logging, enterprise SSO, multi-tenant, compliance]

Return:
1. **Likely failure map** — rank the top causes based on the symptom.
2. **End-to-end flow trace** — each step from login click to session creation, with expected inputs/outputs.
3. **Configuration checklist** — app registration, redirect URIs, allowed origins, client ID/secret, issuer, audience, scopes, logout URLs.
4. **Browser/network checklist** — cookies, SameSite, HTTPS, CORS, proxy headers, state/nonce, PKCE verifier, callback parameters.
5. **Server-side checks** — token exchange, JWKS validation, clock skew, session storage, refresh token handling, error logging.
6. **Provider-specific questions** — what to check in the identity provider dashboard.
7. **Safe diagnostic steps** — commands, log fields, and temporary instrumentation that avoid leaking secrets.
8. **Fix plan and regression tests** — ordered fixes plus tests for local, staging, and production.

Include warnings for insecure shortcuts such as disabling state validation, logging tokens, or using wildcard redirect URIs in production.

Example Output

OAuth Debugging Plan — Next.js + Auth0

Likely Causes

1. **Redirect URI mismatch** — provider has `https://app.example.com/callback`, but the app sends `https://www.example.com/api/auth/callback`.

2. **Cookie settings behind proxy** — callback succeeds, but session cookie is not set because `secure`/`trust proxy` is misconfigured.

3. **State mismatch** — multiple domains or tabs are overwriting the transaction cookie.

Flow Trace

| Step | Expected | What to Capture |

|---|---|---|

| Login click | Redirect to Auth0 `/authorize` | client_id, redirect_uri, scope, state present |

| Provider callback | Returns `code` and `state` | URL params, no token in URL |

| Token exchange | Server exchanges code | status code, issuer, audience, no secret logging |

| Session set | Secure cookie created | `Set-Cookie`, SameSite, domain, path |

Fix Plan

- Add both production callback URLs exactly as emitted by the app.

- Set `NEXTAUTH_URL=https://www.example.com` and confirm proxy forwards `x-forwarded-proto=https`.

- Add a Playwright smoke test that completes login in staging and asserts the session endpoint returns 200.

Do Not Do

Do not disable state validation to "make it work"; fix the transaction cookie/domain mismatch instead.

Tips for Best Results

  • 💡Paste the exact authorization URL and callback URL with secrets removed; tiny domain differences cause many failures.
  • 💡Compare local, staging, and production configuration side by side instead of debugging one variable at a time.
  • 💡Never paste client secrets, refresh tokens, or ID tokens into public AI tools.
  • 💡Add a login smoke test after fixing the bug so the same redirect or cookie issue does not return later.

Try it with

ChatGPTClaudeGemini

Related Prompts

Coding

Code Review Assistant

Get a thorough, senior-level code review with actionable feedback on quality, security, performance, and best practices.

ChatGPTClaudeGemini
Coding

Debugging Detective

Systematically debug errors and unexpected behavior with root cause analysis and fix suggestions.

ChatGPTClaudeGemini
Coding

Code Refactoring Advisor

Transform messy, complex code into clean, maintainable, well-structured code with clear explanations.

ChatGPTClaudeGemini