菜单
NextAuth.js / Auth.js authentication library for Next.js — providers, sessions, JWT, database adapters, middleware protection
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/InugamiDev/ultrathink-oss --skill next-auth命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
Unified design foundations — design system architecture, tokens, component specs, visual principles, creative vision, figma integration, plus brand design system loader (66 real brands via DESIGN.md). Absorbs design, design-system, design-systems, design-principles, design-router, creative-vision, figma, design-md.
Render, summarize, and present markdown documents and structured content in multiple output modes
Ultra UI skill - combines Google's DESIGN.md spec (machine-readable design tokens) with the ui-ux-pro-max knowledge base (91 styles, 161 palettes, 73 font pairings, 161 products, 104 UX guidelines, 25 chart types). Generates lint-clean DESIGN.md files, validates token references and WCAG contrast, exports Tailwind/DTCG tokens, and diffs design systems version-over-version.
基于 SOC 职业分类
| name | next-auth |
| description | NextAuth.js / Auth.js authentication library for Next.js — providers, sessions, JWT, database adapters, middleware protection |
| layer | domain |
| category | authentication |
| triggers | ["next-auth","nextauth","authjs","auth.js","getServerSession","useSession"] |
| inputs | ["Authentication provider requirements","Session management strategy","Route protection rules"] |
| outputs | ["NextAuth configuration and route handlers","Provider setup (OAuth, credentials, magic link)","Session access patterns (server/client)","Middleware-based route protection"] |
| linksTo | ["nextjs","authentication","react","prisma"] |
| linkedFrom | [] |
| preferredNextSkills | ["nextjs","prisma","authentication"] |
| fallbackSkills | ["better-auth","authentication"] |
| riskLevel | medium |
| memoryReadPolicy | selective |
| memoryWritePolicy | none |
| sideEffects | [] |
Provide expert guidance on NextAuth.js (Auth.js v5) for Next.js authentication, including OAuth providers, credentials auth, JWT/session strategies, database adapters, middleware protection, role-based access, and production security patterns.
npm install next-auth@beta @auth/prisma-adapter
// auth.ts (project root)
import NextAuth from 'next-auth';
import { PrismaAdapter } from '@auth/prisma-adapter';
import { prisma } from '@/lib/prisma';
import GitHub from 'next-auth/providers/github';
import Google from 'next-auth/providers/google';
import Credentials from 'next-auth/providers/credentials';
import { compare } from 'bcryptjs';
import type { DefaultSession } from 'next-auth';
// Extend session types
declare module 'next-auth' {
interface Session {
user: {
id: string;
role: 'ADMIN' | | ;
} & [];
}
{
: | | ;
}
}
{ handlers, auth, signIn, signOut } = ({
: (prisma),
: { : },
: {
: ,
: ,
: ,
},
: [
({
: process..!,
: process..!,
}),
({
: process..!,
: process..!,
}),
({
: ,
: {
: { : , : },
: { : , : },
},
() {
(!credentials?. || !credentials?.) ;
user = prisma..({
: { : credentials. },
: { : , : , : , : , : , : },
});
(!user?.) ;
isValid = (credentials. , user.);
(!isValid) ;
{ : user., : user., : user., : user., : user. };
},
}),
],
: {
() {
(user) {
token. = user.;
token. = user.;
}
(trigger === && session) {
token. = session..;
token. = session..;
}
token;
},
() {
session.. = token. ;
session.. = token. | | ;
session;
},
() {
isLoggedIn = !!auth?.;
isOnDashboard = nextUrl..();
isOnAdmin = nextUrl..();
(isOnAdmin) {
auth?.?. === ;
}
(isOnDashboard) {
isLoggedIn;
}
;
},
},
: {
() {
.();
},
},
});
// app/api/auth/[...nextauth]/route.ts
import { handlers } from '@/auth';
export const { GET, POST } = handlers;
// middleware.ts
export { auth as middleware } from '@/auth';
export const config = {
matcher: [
// Match all routes except static files and API auth routes
'/((?!api/auth|_next/static|_next/image|favicon.ico).*)',
],
};
// In Server Components
import { auth } from '@/auth';
export default async function DashboardPage() {
const session = await auth();
if (!session?.user) {
redirect('/login');
}
return (
<div className="p-8">
<h1 className="text-2xl font-bold">
Welcome, {session.user.name}
</h1>
<p className="text-text-secondary">Role: {session.user.role}</p>
</div>
);
}
// In Server Actions
'use server';
import { auth } from '@/auth';
export async function updateProfile(formData: FormData) {
const session = await auth();
if (!session?.user?.id) throw new Error('Unauthorized');
const name = formData.get('name') as string;
await prisma.user.update({
where: { id: session.user.id },
data: { name },
});
revalidatePath('/settings');
}
// In API Routes
import { auth } from '@/auth';
import { NextResponse } from 'next/server';
export async function GET() {
const session = await auth();
if (!session?.user) {
return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
}
const data = await prisma.post.findMany({
where: { authorId: session.user.id },
});
return NextResponse.json(data);
}
// app/layout.tsx — wrap with SessionProvider
import { SessionProvider } from 'next-auth/react';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<SessionProvider>{children}</SessionProvider>
</body>
</html>
);
}
// Client component usage
'use client';
import { useSession, signIn, signOut } from 'next-auth/react';
export function UserMenu() {
const { data: session, status } = useSession();
if (status === 'loading') {
return <div className="h-8 w-8 rounded-full bg-gray-200 animate-pulse" />;
}
if (!session) {
return (
<button
onClick={() => signIn()}
className="px-6 py-4 text-base rounded-lg bg-brand-600 text-white hover:bg-brand-700 transition-all duration-200 focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-brand-500"
>
Sign in
</button>
);
}
return (
<div className="flex items-center gap-3">
<span className="text-sm text-text-secondary">{session.user.email}</span>
<button
onClick={() => signOut({ callbackUrl: '/' })}
className="px-4 py-2 text-sm rounded-lg border border-border text-text-primary hover:bg-gray-50 transition-all duration-200"
>
Sign out
</button>
</div>
);
}
// lib/auth-utils.ts
import { auth } from '@/auth';
import { redirect } from 'next/navigation';
type Role = 'ADMIN' | 'MEMBER' | 'VIEWER';
export async function requireAuth() {
const session = await auth();
if (!session?.user) redirect('/login');
return session;
}
export async function requireRole(...roles: Role[]) {
const session = await requireAuth();
if (!roles.includes(session.user.role)) {
redirect('/unauthorized');
}
return session;
}
// Usage in Server Components / Actions
export default async function AdminPage() {
const session = await requireRole('ADMIN');
// ... admin-only content
}
// app/login/page.tsx
import { signIn } from '@/auth';
export default function LoginPage({
searchParams,
}: {
searchParams: { callbackUrl?: string; error?: string };
}) {
return (
<div className="min-h-screen flex items-center justify-center px-4">
<div className="w-full max-w-md p-8 rounded-2xl bg-white shadow-lg space-y-6">
<div className="text-center">
<h1 className="text-2xl font-bold">Welcome back</h1>
<p className="text-text-secondary mt-2">Sign in to your account</p>
</div>
{searchParams.error && (
<div className="p-4 rounded-lg bg-red-50 text-red-700 text-sm">
{searchParams.error === 'CredentialsSignin'
? 'Invalid email or password.'
: 'Something went wrong. Please try again.'}
</div>
)}
{/* OAuth Providers */}
<div className="space-y-3">
<form
action={async () => {
'use server';
await signIn('github', { redirectTo: searchParams.callbackUrl ?? '/dashboard' });
}}
>
<button
type="submit"
className="w-full flex items-center justify-center gap-3 px-6 py-4 text-base rounded-lg border border-border hover:bg-gray-50 transition-all duration-200 focus-visible:ring-2 focus-visible:ring-offset-2"
>
Continue with GitHub
</button>
</form>
<form
action={async () => {
'use server';
await signIn('google', { redirectTo: searchParams.callbackUrl ?? '/dashboard' });
}}
>
<button
type="submit"
className="w-full flex items-center justify-center gap-3 px-6 py-4 text-base rounded-lg border border-border hover:bg-gray-50 transition-all duration-200 focus-visible:ring-2 focus-visible:ring-offset-2"
>
Continue with Google
</button>
</form>
</div>
<div className="relative">
<div className="absolute inset-0 flex items-center">
<div className="w-full border-t border-border" />
</div>
<div className="relative flex justify-center text-sm">
<span className="bg-white px-4 text-text-secondary">Or continue with email</span>
</div>
</div>
{/* Credentials Form */}
<form
action={async (formData) => {
'use server';
await signIn('credentials', {
email: formData.get('email'),
password: formData.get('password'),
redirectTo: searchParams.callbackUrl ?? '/dashboard',
});
}}
className="space-y-4"
>
<input
name="email"
type="email"
placeholder="Email"
required
className="w-full px-4 py-3 rounded-lg border border-border text-base focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-brand-500 focus-visible:outline-none transition-all duration-200"
/>
<input
name="password"
type="password"
placeholder="Password"
required
className="w-full px-4 py-3 rounded-lg border border-border text-base focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-brand-500 focus-visible:outline-none transition-all duration-200"
/>
<button
type="submit"
className="w-full px-6 py-4 text-base rounded-lg bg-brand-600 text-white font-medium hover:bg-brand-700 transition-all duration-200 focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-brand-500"
>
Sign in
</button>
</form>
</div>
</div>
);
}
id, role, and display fields via callbacks.auth() server-side instead of getServerSession (v5 pattern).signIn and error -- the default pages are not production-ready.AUTH_SECRET in production -- a 32+ character random string. Generate with openssl rand -base64 32.authorized callback in auth.ts for declarative route protection rather than per-page checks.useSession() alone for authorization; re-check in Server Actions and API routes.| Anti-Pattern | Problem | Fix |
|---|---|---|
| Client-only auth checks | Session can be spoofed in browser | Always verify with auth() on the server |
| Storing passwords in JWT | Token size bloat + security risk | Only store id and role in JWT |
Using getSession() in Server Components | Deprecated in v5, causes hydration issues | Use auth() from @/auth |
No callbackUrl on sign-in | Users land on homepage instead of their target page | Pass callbackUrl from searchParams |
| Skipping email verification | Fake accounts, OAuth account linking issues | Enable email verification flow |
| Hardcoded secrets in code | Credential leaks | Use environment variables exclusively |
Not setting AUTH_TRUST_HOST | Redirect URI mismatch behind proxies | Set AUTH_TRUST_HOST=true when behind a reverse proxy |
| Using Credentials provider without rate limiting | Brute force attacks | Add rate limiting middleware (e.g., upstash/ratelimit) |
| Scenario | Approach |
|---|---|
| SaaS with social login | OAuth providers (GitHub, Google) + Prisma adapter |
| Email/password auth | Credentials provider + bcrypt + email verification |
| Magic link (passwordless) | Email provider with Resend/Nodemailer |
| API-only auth | JWT strategy + Bearer token validation in API routes |
| Role-based pages | authorized callback in middleware + requireRole() helper |
| Multi-tenant | Add organizationId to session via JWT callback |
| Session refresh | JWT strategy with maxAge + updateAge in session config |
| Account linking | Prisma adapter handles linking OAuth accounts to same email |