Authentication Issues
Overview
This playbook covers login failures, redirect loops, expired sessions, and permission confusion.
Why It Matters
Auth issues block access and are often caused by a mismatch between layers.
Core Concepts
- Authentication proves identity.
- Authorization checks permission.
- Session persistence and redirects must agree.
Mental Models
Trace the whole flow: login, session creation, redirect, protected route, and refresh.
Best Practices
- Check cookies, tokens, and middleware.
- Verify server and client behavior separately.
- Test expired-session behavior.
Common Mistakes
- Confusing auth with permissions.
- Forgetting one layer in the redirect path.
- Assuming the token is present because the UI says so.
Trade-offs
Centralized auth logic is easier to reason about, but it must stay aligned across server and client.
Decision Framework
flowchart TD
A[Auth bug] --> B{Login works?}
B -->|No| C[Check credentials/session creation]
B -->|Yes| D{Redirect issue?}
D -->|Yes| E[Check middleware/client routing]
D -->|No| F[Check permissions/session expiry]Examples
- Fix a loop by aligning the protected-route check with the session source.
Checklists
- Can I sign in successfully?
- Are protected routes blocked correctly?
- Does expiration behave as expected?
Senior Engineer Notes
Senior engineers trace auth end to end because the bug is often at the boundary, not the visible screen.