Skip to main content
skill CX Codex

authentication-patterns · travisjneuman — Claude Code skill for auth patterns

authentication-patterns — a Claude Code skill for authentication and authorization patterns. It comes into play when building login flows, MFA, SSO, or access-control models.

MIT 144 installs ★ 114 updated 2026-11-10

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add travisjneuman/.claude --skill authentication-patterns -a claude-code
Open on GitHub

What authentication-patterns does

The skill covers authentication and authorization for web and mobile apps. Topics include OAuth 2.0 flows, JWT access and refresh tokens, session management, TOTP and WebAuthn MFA, SAML and OIDC SSO, plus RBAC and ABAC. Examples connect these patterns to Auth.js v5, Clerk, Supabase Auth, and Lucia.

Use its guidance while building sign-up and login, adding social providers, introducing MFA, or moving between auth providers. It also discusses session checks, CSRF protection, rate limits, account recovery, and least-privilege access. The Auth.js example uses GITHUB_ID, GITHUB_SECRET, GOOGLE_ID, and GOOGLE_SECRET; the JWT example uses JWT_SECRET. Database sessions can be revoked immediately.

What it helps with

  • design login and sign-up with OAuth providers
  • rotate access and refresh tokens for an API
  • add MFA with TOTP or WebAuthn
  • define permissions with RBAC or ABAC
  • move an application to a different auth provider

Example prompts for the agent

  • Design Google and GitHub login for a Next.js app using Auth.js v5.
  • Show an API token flow with rotating access and refresh tokens.
  • Add WebAuthn MFA and account recovery to the login flow.

How to install authentication-patterns

1Skills CLI (Vercel)

npx skills add travisjneuman/.claude --skill authentication-patterns -a claude-code

2Manually: put the files in place

~/.claude/skills/authentication-patterns/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/authentication-patterns/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about authentication-patterns

How do I install authentication-patterns in Claude Code?

Run npx skills add travisjneuman/.claude --skill authentication-patterns -a claude-code. The skill file is at ~/.claude/skills/authentication-patterns/SKILL.md.

What does authentication-patterns do?

It provides implementation patterns for OAuth 2.0, JWT, sessions, MFA, SSO, and authorization models. The examples include Auth.js v5 and other authentication libraries.

Which environment variables do the authentication-patterns examples use?

The Auth.js example uses GITHUB_ID, GITHUB_SECRET, GOOGLE_ID, and GOOGLE_SECRET. The JWT example uses JWT_SECRET.

Source text

SKILL.md · MIT
---
name: authentication-patterns
description: OAuth 2.0, JWT, SSO, MFA, NextAuth/Clerk/Supabase Auth implementation patterns
---

# Authentication Patterns

## Overview

This skill covers authentication and authorization implementation across web and mobile applications. It addresses OAuth 2.0 flows (Authorization Code with PKCE, Client Credentials), JWT management (access tokens, refresh tokens, rotation), session management strategies, multi-factor authentication (TOTP, WebAuthn/passkeys), integration with auth libraries (NextAuth/Auth.js v5, Clerk, Supabase Auth, Lucia), SSO protocols (SAML, OIDC), and authorization patterns (RBAC, ABAC).

Use this skill when building login/signup flows, integrating social login providers, implementing MFA, setting up SSO for enterprise customers, designing authorization models, or migrating between auth providers.

---

## Core Principles

1. **Never roll your own crypto** - Use established libraries for password hashing (bcrypt, argon2), JWT signing, and OAuth flows. Custom auth code is the #1 source of security vulnerabilities in web applications.
2. **Defense in depth** - Authentication is not a single check. Layer session validation, CSRF protection, rate limiting, and anomaly detection. Assume every layer can be bypassed individually.
3. **Tokens are credentials** - Access tokens, refresh tokens, and session cookies must be stored securely (httpOnly cookies, encrypted storage), transmitted over HTTPS only, and rotated regularly.
4. **Least privilege by default** - Users and API clients should start with minimal permissions. Elevate access through explicit role assignment, never through implicit trust.
5. **Plan for account recovery** - Password reset, MFA recovery codes, email verification, and account lockout all need designed flows. These are more complex than the happy-path login.

---

## Key Patterns

### Pattern 1: NextAuth (Auth.js v5) with OAuth and Database Sessions

**When to use:** Next.js applications needing social login, email/password, or magic link authentication with server-side session management.

**Implementation:**

```typescript
// auth.ts - Auth.js v5 configuration
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import Google from "next-auth/providers/google";
import Credentials from "next-auth/providers/credentials";
import { PrismaAdapter } from "@auth/prisma-adapter";
import { prisma } from "@/lib/prisma";
import { verifyPassword } from "@/lib/password";

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [
    GitHub({
      clientId: process.env.GITHUB_ID!,
      clientSecret: process.env.GITHUB_SECRET!,
    }),
    Google({
      clientId: process.env.GOOGLE_ID!,
      clientSecret: process.env.GOOGLE_SECRET!,
    }),
    Credentials({
      credentials: {
        email: { label: "Email", type: "email" },
        password: { label: "Password", type: "password" },
      },
      async authorize(credentials) {
        if (!credentials?.email || !credentials?.password) return null;

        const user = await prisma.user.findUnique({
          where: { email: credentials.email as string },
        });

        if (!user?.passwordHash) return null;

        const valid = await verifyPassword(
          credentials.password as string,
          user.passwordHash
        );

        if (!valid) return null;

        return { id: user.id, email: user.email, name: user.name };
      },
    }),
  ],
  session: {
    strategy: "database", // Server-side sessions (not JWT)
    maxAge: 30 * 24 * 60 * 60, // 30 days
    updateAge: 24 * 60 * 60, // Refresh session every 24 hours
  },
  callbacks: {
    async session({ session, user }) {
      // Add user role to session
      session.user.id = user.id;
      session.user.role = user.role;
      return session;
    },
    async signIn({ user, account }) {
      // Block sign-in for disabled accounts
      if (user.id) {
        const dbUser = await prisma.user.findUnique({
          where: { id: user.id },
        });
        if (dbUser?.disabled) return false;
      }
      return true;
    },
  },
  pages: {
    signIn: "/login",
    error: "/auth/error",
    verifyRequest: "/auth/verify",
  },
});
```

```typescript
// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";
export const { GET, POST } = handlers;
```

```typescript
// Middleware for route protection
// middleware.ts
import { auth } from "@/auth";
import { NextResponse } from "next/server";

export default auth((req) => {
  const isLoggedIn = !!req.auth;
  const isAuthPage = req.nextUrl.pathname.startsWith("/login") ||
                     req.nextUrl.pathname.startsWith("/register");
  const isDashboard = req.nextUrl.pathname.startsWith("/dashboard");

  if (isDashboard && !isLoggedIn) {
    return NextResponse.redirect(new URL("/login", req.url));
  }

  if (isAuthPage && isLoggedIn) {
    return NextResponse.redirect(new URL("/dashboard", req.url));
  }

  return NextResponse.next();
});

export const config = {
  matcher: ["/dashboard/:path*", "/login", "/register"],
};
```

**Why:** Auth.js v5 handles OAuth complexity (state parameters, PKCE, token exchange), session management, CSRF protection, and provider-specific quirks. Database sessions are more secure than JWT sessions because they can be revoked instantly and don't expose claims to the client.

---

### Pattern 2: JWT Access/Refresh Token Pattern

**When to use:** API authentication for SPAs, mobile apps, or microservice-to-microservice communication where stateless verification is needed.

**Implementation:**

```typescript
// Token generation
import jwt from "jsonwebtoken";
import { randomBytes } from "crypto";

interface TokenPayload {
  sub: string; // User ID
  email: string;
  role: string;
}

interface TokenPair {
  accessToken: string;
  refreshToken: string;
  expiresIn: number;
}

const ACCESS_TOKEN_EXPIRY = "15m";
const REFRESH_TOKEN_EXPIRY = "7d";

function generateTokenPair(user: TokenPayload): TokenPair {
  const accessToken = jwt.sign(
    { sub: user.sub, email: user.email, role: user.role },
    process.env.JWT_SECRET!,
    {
      expiresIn: ACCESS_TOKEN_EXPIRY,
      issuer: "myapp",
      audience: "myapp-api",
    }
  );

  // Refresh token is opaque (not JWT) - stored server-side
  const refreshToken = randomBytes(64).toString("hex");

  return {
    accessToken,
    refreshToken,
    expiresIn: 900, // 15 minutes in seconds
  };
}

// Token refresh endpoint
async function refreshTokens(refreshToken: string): Promise<TokenPair> {
  // 1. Look up refresh token in database
  const stored = await db.refreshToken.findUnique({
    where: { token: hashToken(refreshToken) },
    include: { user: true },
  });

  if (!stored || stored.expiresAt < new Date()) {
    throw new UnauthorizedError("Invalid or expired refresh token");
  }

  // 2. Rotate refresh token (invalidate old, create new)
  await db.refreshToken.delete({ where: { id: stored.id } });

  const newPair = generateTokenPair({
    sub: stored.user.id,
    email: stored.user.email,
    role: stored.user.role,
  });

  // 3. Store new refresh token
  await db.refreshToken.create({
    data: {
      token: hashToken(newPair.refreshToken),
      userId: stored.user.id,
      expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
    },
  });

  return newPair;
}

// Token verification middleware
function verifyAccessToken(token: string): TokenPayload {
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET!, {
      issuer: "myapp",
      audience: "myapp-api",
    });
    return decoded as TokenPayload;
  } catch (err) {
    if (err instanceof jwt.TokenExpiredError) {
      throw new UnauthorizedError("Access token expired");
    }
    throw new UnauthorizedError("Invalid access token");
  }
}
```

```typescript
// Secure cookie-based token delivery (for web apps)
function setAuthCookies(res: Response, tokens: TokenPair): void {
  // Access token in httpOnly cookie
  res.headers.append(
    "Set-Cookie",
    `access_token=${tokens.accessToken}; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=${tokens.expiresIn}`
  );

  // Refresh token in httpOnly cookie with restricted path
  res.headers.append(
    "Set-Cookie",
    `refresh_token=${tokens.refreshToken}; HttpOnly; Secure; SameSite=Strict; Path=/api/auth/refresh; Max-Age=${7 * 24 * 60 * 60}`
  );
}
```

**Why:** Short-lived access tokens (15 minutes) limit the damage window if a token is stolen. Opaque refresh tokens stored server-side can be revoked immediately (unlike JWTs). Refresh token rotation detects token theft: if a stolen refresh token is used after the legitimate user has already rotated it, the entire token family is invalidated.

---

### Pattern 3: Multi-Factor Authentication (TOTP)

**When to use:** When you need an additional authentication factor beyond password, especially for admin accounts and sensitive operations.

**Implementation:**

```typescript
// MFA setup flow
import { authenticator } from "otplib";
import QRCode from "qrcode";

// Step 1: Generate secret and QR code for user
async function setupMFA(userId: string): Promise<{ qrCodeUrl: string; secret: string }> {
  const secret = authenticator.generateSecret();

  const user = await db.user.findUniqueOrThrow({ where: { id: userId } });

  // Store encrypted secret (not yet verified)
  await db.mfaSetup.upsert({
    where: { userId },
    create: { userId, secret: encrypt(secret), verified: false },
    update: { secret: encrypt(secret), verified: false },
  });

  const otpauth = authenticator.keyuri(user.email, "MyApp", secret);
  const qrCodeUrl = await QRCode.toDataURL(otpauth);

  return { qrCodeUrl, secret };
}

// Step 2: Verify code to complete setup
async function verifyMFASetup(userId: string, code: string): Promise<string[]> {
  const setup = await db.mfaSetup.findUniqueOrThrow({
    where: { userId },
  });

  const secret = decrypt(setup.secret);
  const isValid = authenticator.verify({ token: code, secret });

  if (!isValid) {
    throw new ValidationError("Invalid verification code");
  }

  // Generate recovery codes
  const recoveryCodes = Array.from({ length: 10 }, () =>
    randomBytes(4).toString("hex").toUpperCase()
  );

  // Store hashed recovery codes
  await db.$transaction([
    db.mfaSetup.update({
      where: { userId },
      data: { verified: true },
    }),
    db.user.update({
      where: { id: userId },
      data: { mfaEnabled: true },
    }),
    ...recoveryCodes.map((code) =>
      db.recoveryCode.create({
        data: { userId, codeHash: hashCode(code) },
      })
    ),
  ]);

  return recoveryCodes; // Show to user ONCE
}

// Step 3: Verify TOTP during login
async function verifyMFA(userId: string, code: string): Promise<boolean> {
  const setup = await db.mfaSetup.findUniqueOrThrow({
    where: { userId, verified: true },
  });

  const secret = decrypt(setup.secret);

  // Check TOTP code (allows 1 window of drift)
  if (authenticator.verify({ token: code, secret })) {
    return true;
  }

  // Check recovery codes
  const recoveryCodes = await db.recoveryCode.findMany({
    where: { userId, used: false },
  });

  for (const rc of recoveryCodes) {
    if (await verifyHash(code, rc.codeHash)) {
      // Mark recovery code as used (one-time use)
      await db.recoveryCode.update({
        where: { id: rc.id },
        data: { used: true, usedAt: new Date() },
      });
      return true;
    }
  }

  return false;
}
```

**Why:** TOTP-based MFA is widely supported (Google Authenticator, Authy, 1Password), doesn't require SMS (which is vulnerable to SIM swapping), and works offline. Recovery codes provide a safety net when users lose their authenticator device. The encrypted secret and hashed recovery codes protect against database breaches.

---

### Pattern 4: Role-Based Access Control (RBAC)

**When to use:** When different users need different levels of access to resources.

**Implementation:**

```typescript
// Permission definitions
const PERMISSIONS = {
  // Projects
  "project:read": "View project details",
  "project:write": "Edit project settings",
  "project:delete": "Delete projects",
  "project:manage_members": "Add/remove project members",

  // Billing
  "billing:read": "View billing information",
  "billing:write": "Manage subscriptions and payments",

  // Admin
  "admin:users": "Manage all users",
  "admin:settings": "Manage organization settings",
} as const;

type Permission = keyof typeof PERMISSIONS;

// Role definitions
const ROLES: Record<string, Permission[]> = {
  viewer: ["project:read"],
  editor: ["project:read", "project:write"],
  admin: [
    "project:read",
    "project:write",
    "project:delete",
    "project:manage_members",
    "billing:read",
    "billing:write",
  ],
  owner: Object.keys(PERMISSIONS) as Permission[],
};

// Permission check middleware
function requirePermission(...requiredPermissions: Permission[]) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const user = req.user;
    if (!user) {
      return res.status(401).json({ error: "Authentication required" });
    }

    const userPermissions = ROLES[user.role] ?? [];
    const hasAllPermissions = requiredPermissions.every((p) =>
      userPermissions.includes(p)
    );

    if (!hasAllPermissions) {
      return res.status(403).json({
        error: "Insufficient permissions",
        required: requiredPermissions,
        current: user.role,
      });
    }

    next();
  };
}

// Usage in routes
app.get("/api/projects/:id", requirePermission("project:read"), getProject);
app.put("/api/projects/:id", requirePermission("project:write"), updateProject);
app.delete("/api/projects/:id", requirePermission("project:delete"), deleteProject);

// Component-level permission checks (React)
function usePermission(permission: Permission): boolean {
  const { data: session } = useSession();
  if (!session?.user?.role) return false;
  const permissions = ROLES[session.user.role] ?? [];
  return permissions.includes(permission);
}

function ProjectSettings({ project }: { project: Project }) {
  const canEdit = usePermission("project:write");
  const canDelete = usePermission("project:delete");

  return (
    <div>
      <h2>Settings</h2>
      {canEdit ? (
        <ProjectForm project={project} />
      ) : (
        <ProjectDetails project={project} />
      )}
      {canDelete && <DeleteProjectButton projectId={project.id} />}
    </div>
  );
}
```

**Why:** RBAC provides a clear, auditable permission model. Defining permissions as constants with TypeScript ensures compile-time safety. Checking permissions on both server (middleware) and client (UI) provides defense in depth -- the server enforces security, the client provides user experience.

---

## Reference files

Detailed material is in separate files so this overview stays short. Read only the file whose topic matches the task; each one is self-contained. Paths are relative to the folder that holds this `SKILL.md` (in the full toolkit install, `~/.claude/skills/authentication-patterns/`).

| Topic | File | Covers |
| --- | --- | --- |
| Password Hashing Reference | [`references/password-hashing-reference.md`](references/password-hashing-reference.md) | 12 lines |
| Anti-Patterns | [`references/anti-patterns.md`](references/anti-patterns.md) | 15 lines |
| Checklist | [`references/checklist.md`](references/checklist.md) | 17 lines |

## Related Resources

- **Skills:** `application-security` (OWASP auth vulnerabilities), `payment-integration` (billing auth)
- **Skills:** `email-systems` (password reset emails), `product-analytics` (identify/alias on auth)
- **Rules:** `docs/reference/stacks/fullstack-nextjs-nestjs.md` (NestJS auth guards)

© travisjneuman · MIT · travisjneuman/.claude

Similar skills

All skills for Security →

authentication-patterns by other authors comes first.

authentication-patterns zebbern The authentication-patterns skill equips coding agents with auth architecture guides, provider comparisons, and a pre-deployment security checklist. Use it when designing secure login flows. CX Codex +1 ★ 4,719repo stars authentication-patterns rohitg00 authentication-patterns is a Claude Code skill with authentication and authorization patterns: JWT, OAuth2 with PKCE, role-based access control, and Express middleware. For securing a Node.js backend. CX Codex +1 ★ 2,858repo stars auth0-authentication Mindrally auth0-authentication — a skill that gives your coding agent Auth0 guidelines: auth flows, Actions, token validation and redirect safety. CX Codex +1 740installs add-authentication-system davila7 The add-authentication-system command for Claude Code builds an authentication layer for an existing application using a selected sign-in method. It covers user accounts, sessions, access rules, and security controls. CX Codex +1 382installs authentication-setup akillness Picks and structures the authentication setup for a web app or API before any JWT code gets written. Separates hosted, framework-native, platform-native, enterprise-add-on and self-hosted auth paths. CX Codex +1 372installs catalyst-authentication catalystbyzoho catalyst-authentication guides user login, social auth, and OAuth connections in Zoho Catalyst. Prevents broken production deployments caused by mismatched ZAID identifiers. CX Codex +1 1,200installs api-authentication aj-geddes A skill for API authentication: JWT, OAuth 2.0, API keys and session handling. Useful when you lock down endpoints or build a login flow. CX Codex +1 613installs auth-wasp-drone Legion Code Inc. auth-wasp-drone — an authentication implementation subagent for provider choice, OAuth wiring, MFA, RBAC, session handling, and B2B SSO. CX Codex ★ 96repo stars

From the same set117

The whole set →
frontend-enhancer frontend-enhancer polishes the visual side of a web app: palette, layout, motion, component states. Useful when the UI still reads as a stock starter. CX Codex +1 145installs status-report-generator The status-report-generator Claude Code skill builds project status reports from Git activity, task context, and milestone tracking. It can create weekly updates, sprint reviews, and stakeholder reports. CX Codex +1 145installs generic-ux-designer generic-ux-designer — a UX skill for Claude and other coding agents: design-thinking steps, heuristic review and accessibility checks, packaged as checklists the agent follows. CX Codex +1 145installs performance-engineering performance-engineering — a skill for Claude Code designed for full-stack web application performance optimization. Activates when Core Web Vitals drop, bundle sizes increase, or page response times degrade. CX Codex +1 144installs i18n-localization The i18n-localization Claude Code skill guides internationalization and localization work. It activates for translation setup, locale-specific formatting, and adapting an app for multiple regions. CX Codex +1 143installs vue-development vue-development — a Claude Code skill for building Vue 3 applications with the Composition API and Script Setup. Guides state setup in Pinia, custom composables, and Nuxt 3 full-stack tasks. CX Codex +1 143installs generic-design-system generic-design-system provides standard design system guidelines for AI coding agents, covering color tokens, typography, spacing scales, and component states. CX Codex +1 143installs event-driven-architecture The event-driven-architecture skill guides asynchronous system design around brokers, event flows, and distributed work. Use it when services must communicate through messages. CX Codex +1 143installs

Project sponsors

Companies that keep this analytics open