编辑“︁Next.js OAuth集成”︁

= Next.js OAuth集成 =

'''OAuth集成'''是Next.js应用中实现第三方身份验证的核心技术，允许用户通过Google、GitHub等平台账号安全登录。本指南将系统讲解其原理、实现步骤及实际应用场景。

== 概述 ==
OAuth（开放授权）是一种行业标准协议，使应用能在不获取用户密码的情况下，通过授权服务器获取有限的访问权限。Next.js通过[[API路由]]和[[Auth.js]]（原NextAuth.js）等工具简化此流程。

=== 核心概念 ===
* '''OAuth 2.0流程'''：包含授权码（Authorization Code）、隐式（Implicit）等模式，Next.js常用授权码模式
* '''角色划分'''：
** 资源所有者（用户）
** 客户端（Next.js应用）
** 资源服务器（如GitHub API）
** 授权服务器（如GitHub OAuth服务）

<mermaid>
sequenceDiagram
    participant User
    participant Next.js App
    participant OAuth Provider
    User->>Next.js App: 点击"使用GitHub登录"
    Next.js App->>OAuth Provider: 重定向到授权页面
    OAuth Provider->>User: 显示授权请求
    User->>OAuth Provider: 同意授权
    OAuth Provider->>Next.js App: 返回授权码
    Next.js App->>OAuth Provider: 用授权码交换令牌
    OAuth Provider->>Next.js App: 返回访问令牌
    Next.js App->>User: 建立认证会话
</mermaid>

== 实现步骤 ==

=== 1. 创建OAuth应用 ===
以GitHub为例：
1. 进入[Settings > Developer settings > OAuth Apps]
2. 填写回调URL：<code>http://localhost:3000/api/auth/callback/github</code>

=== 2. 安装依赖 ===
<syntaxhighlight lang="bash">
npm install next-auth @next-auth/prisma-adapter @prisma/client
</syntaxhighlight>

=== 3. 配置NextAuth.js ===
创建<code>/pages/api/auth/[...nextauth].ts</code>：

<syntaxhighlight lang="typescript">
import NextAuth from "next-auth"
import GitHubProvider from "next-auth/providers/github"

export default NextAuth({
  providers: [
    GitHubProvider({
      clientId: process.env.GITHUB_ID,
      clientSecret: process.env.GITHUB_SECRET,
    }),
  ],
  callbacks: {
    async jwt({ token, account }) {
      if (account) {
        token.accessToken = account.access_token
      }
      return token
    },
    async session({ session, token }) {
      session.accessToken = token.accessToken
      return session
    }
  }
})
</syntaxhighlight>

=== 4. 环境变量配置 ===
<code>.env.local</code>文件：
<syntaxhighlight lang="ini">
GITHUB_ID=your_client_id
GITHUB_SECRET=your_client_secret
NEXTAUTH_SECRET=your_random_string
NEXTAUTH_URL=http://localhost:3000
</syntaxhighlight>

=== 5. 添加会话管理 ===
在组件中使用钩子：
<syntaxhighlight lang="tsx">
import { useSession, signIn, signOut } from "next-auth/react"

export default function Component() {
  const { data: session } = useSession()
  
  if (session) {
    return (
      <>
        欢迎 {session.user?.name}!
        <button onClick={() => signOut()}>登出</button>
      </>
    )
  }
  return <button onClick={() => signIn("github")}>GitHub登录</button>
}
</syntaxhighlight>

== 高级配置 ==

=== 多提供商集成 ===
同时配置多个OAuth提供商：
<syntaxhighlight lang="typescript">
providers: [
  GitHubProvider({ /*...*/ }),
  GoogleProvider({
    clientId: process.env.GOOGLE_ID,
    clientSecret: process.env.GOOGLE_SECRET,
  }),
  // 可添加更多...
]
</syntaxhighlight>

=== 自定义回调 ===
实现权限控制：
<syntaxhighlight lang="typescript">
callbacks: {
  async signIn({ user, account, profile }) {
    // 只允许特定域名邮箱登录
    const allowedDomains = ["company.com"]
    const emailDomain = user.email?.split("@")[1]
    return allowedDomains.includes(emailDomain)
  }
}
</syntaxhighlight>

== 安全最佳实践 ==
* 始终使用HTTPS
* 设置<code>NEXTAUTH_SECRET</code>（32位随机字符串）
* 限制OAuth应用的权限范围（scopes）
* 实现CSRF保护（NextAuth.js已内置）
* 定期轮换客户端密钥

== 实际案例 ==
'''企业知识管理系统'''通过OAuth实现：
1. 员工使用公司GitHub账号登录
2. 根据GitHub组织成员身份分配权限
3. 访问令牌用于调用GitHub API获取仓库数据

<mermaid>
graph TD
    A[用户登录] --> B{验证GitHub组织成员?}
    B -->|是| C[授予编辑权限]
    B -->|否| D[仅查看权限]
    C --> E[访问内部API]
    D --> F[受限视图]
</mermaid>

== 常见问题 ==

=== 如何处理令牌刷新？ ===
NextAuth.js自动处理OAuth 2.0刷新令牌流程，需确保provider配置包含<code>offline_access</code> scope。

=== 如何获取用户额外信息？ ===
通过扩展scope并修改回调：
<syntaxhighlight lang="typescript">
GitHubProvider({
  clientId: "...",
  clientSecret: "...",
  authorization: { params: { scope: "user:email read:org" } }
})
</syntaxhighlight>

=== 如何测试OAuth流程？ ===
使用mock服务：
* [mockoon](https://mockoon.com/)模拟OAuth提供商
* 测试回调URL：<code>http://localhost:3000/api/auth/callback/mock</code>

== 数学原理 ==
OAuth的安全性基于[[哈希算法]]和[[非对称加密]]。令牌有效期计算：

<math>
T_{valid} = T_{issue} + \Delta T_{expiry} - \delta_{clock\_skew}
</math>

其中：
* <math>T_{issue}</math> = 令牌签发时间
* <math>\Delta T_{expiry}</math> = 配置的过期时间（通常3600秒）
* <math>\delta_{clock\_skew}</math> = 时钟偏差容限（通常300秒）

== 延伸阅读 ==
* [[OAuth 2.0规范RFC 6749]]
* [[OpenID Connect]]
* [[JWT (JSON Web Tokens)]]

[[Category:后端框架]]
[[Category:Next.js]]
[[Category:Next.js身份验证与授权]]