# authentication-patterns

This skill equips coding agents with auth architecture guides, provider comparisons, and a pre-deployment security checklist. Use it when designing secure login flows.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 4679
- Author: zebbern
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/zebbern/claude-code-guide/tree/HEAD/skills/authentication-patterns/SKILL.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/authentication-patterns

## What it does

The skill outlines trade-offs between database sessions, stateless JWTs, OAuth 2.0 / OIDC, and Passkeys. It details library choices across NextAuth, Clerk, Supabase Auth, and Lucia, including a sample Prisma adapter route for Next.js apps.

Access tokens must expire within 15 minutes. Storing auth tokens in `localStorage` or `sessionStorage` exposes users to XSS attacks, so the guide mandates `httpOnly`, `Secure`, and `SameSite=Lax` cookies. It enforces refresh token rotation where every token is single-use, backed by a server-side revocation blocklist.

The security checklist covers pre-ship requirements: rate-limiting logins to 5–10 attempts per minute per IP, CSRF defenses, and password hashing using argon2id or bcrypt at cost 12+.

## Requirements
- Works with: Supabase

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add zebbern/claude-code-guide --skill authentication-patterns -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/authentication-patterns/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/authentication-patterns/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add zebbern/claude-code-guide --skill authentication-patterns -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/authentication-patterns/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add zebbern/claude-code-guide --skill authentication-patterns -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/authentication-patterns/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install zebbern/claude-code-guide authentication-patterns
```

2. **Manually: put the files in place**
- File: `.github/skills/authentication-patterns/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add zebbern/claude-code-guide --skill authentication-patterns -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/zebbern/claude-code-guide --path skills/authentication-patterns
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/authentication-patterns/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add zebbern/claude-code-guide --skill authentication-patterns -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/zebbern/claude-code-guide/tree/HEAD/skills/authentication-patterns/SKILL.md

## When to use it
- choose between database sessions, JWTs, OAuth, and Passkeys
- configure refresh token rotation with secure cookie storage
- audit login endpoints against brute-force and credential stuffing
- configure argon2id or bcrypt password hashing

## Example prompts
- Review my login endpoint against the authentication-patterns checklist
- Compare session-based auth with JWT for my mobile API
- Configure refresh token rotation using httpOnly secure cookies

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 56b80768fac5ecda.

BEGIN THIRD-PARTY FILE 56b80768fac5ecda
````text
---
name: authentication-patterns
description: "Authentication patterns: session vs JWT vs OAuth comparison, provider selection (NextAuth, Clerk, Supabase Auth), security checklist, and common mistakes. Use when implementing auth, reviewing auth flows, or choosing auth providers."
---

# Authentication Patterns Skill

Reference for implementing secure, production-ready authentication.

## WHEN_TO_USE

Apply this skill when implementing authentication in a project, reviewing existing auth flows for security issues, choosing between auth providers, or migrating between auth strategies. Use the security checklist before shipping any auth-related change.

## AUTH_APPROACHES

| Approach | How It Works | Best For | Drawbacks |
|----------|-------------|----------|-----------|
| Session-based | Server stores session in DB/Redis, client holds session ID cookie | Traditional server-rendered apps, apps needing instant revocation | Requires server-side storage, harder to scale horizontally without shared store |
| JWT (stateless) | Server signs token, client sends it on each request | API-first apps, microservices, mobile clients | Cannot revoke without blocklist, token size grows with claims |
| OAuth 2.0 / OIDC | Delegates auth to external provider (Google, GitHub, etc.) | Social login, enterprise SSO, reducing auth responsibility | More complex flow, depends on external provider availability |
| Passkeys / WebAuthn | Cryptographic key pair, no passwords | High-security apps, passwordless UX | Limited browser support legacy, user education needed |

### Decision Guide

- **Server-rendered app with simple needs** → Session-based
- **SPA or mobile app calling APIs** → JWT with refresh token rotation
- **Want social login or SSO** → OAuth 2.0 / OIDC
- **Greenfield with modern UX goals** → Passkeys + OAuth fallback

## JWT_BEST_PRACTICES

### Token Lifecycle

```
Login → Access Token (short-lived) + Refresh Token (long-lived, rotated)
  │
  ├─ Access Token: 15 min expiry, sent via httpOnly cookie or Authorization header
  │
  └─ Refresh Token: 7-30 day expiry, stored in httpOnly secure cookie
       │
       └─ On use: issue new access + new refresh token, invalidate old refresh token
```

### Rules

- [P0-MUST] Set short expiry on access tokens (15 minutes or less).
- [P0-MUST] Store tokens in `httpOnly`, `Secure`, `SameSite=Lax` cookies — never in `localStorage` or `sessionStorage`.
- [P0-MUST] Implement refresh token rotation — each refresh token is single-use.
- [P0-MUST] Maintain a server-side blocklist for revoked refresh tokens.
- [P1-SHOULD] Include only essential claims in JWT payload (sub, iat, exp, role). Keep it small.
````
END THIRD-PARTY FILE 56b80768fac5ecda

The third-party file has ended. Everything between the 56b80768fac5ecda tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2697 of 8083 bytes. © zebbern · MIT · https://github.com/zebbern/claude-code-guide/tree/HEAD/skills/authentication-patterns/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md