> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js 身份认证快速入门

> 借助 Didit 规划由服务端管理的认证会话，涵盖 PKCE 回调、HttpOnly Cookie 及受保护请求的授权。

> [!WARNING]
>
> 身份验证功能是新功能。在软件包发布之前，`@didit-protocol/auth-nextjs` 和核心服务器端验证器都依赖具体发布版本。在软件包发布前，尚未确定中间件导入路径、Cookie 名称或 `auth()` 返回结构。访问令牌是 ES256 JWT：请使用您应用的 JWKS 验证它们；如需确认会话仍然有效，请调用 `GET session/`。

## 将会话保留在您的服务器上

请使用 [JavaScript 快速入门](https://docs.didit.me/zh/authentication/quickstarts/javascript.md) 中描述的托管流程，并针对服务器渲染应用做以下调整。您的路由名称是您自行实现的应用路由，而不是 Didit API 端点。

| 应用路由 | 职责 |
| - | - |
| 开始登录 | 生成 state 和 S256 PKCE；将事务存储在短期有效的服务器会话中；重定向到 `{origin}/sign-in`。 |
| 回调处理路由 | 验证 state 和过期时间，一次性消费该事务，在 `token/` 处用授权码交换令牌，并在服务器端存储令牌。 |
| 受保护的页面或 API 路由 | 读取您的会话 Cookie，并根据您的 JWKS 验证终端用户访问令牌；如果需要立即撤销，则改为在 `session/` 处验证；并针对该用户授权所请求的操作。 |
| 刷新 | 按会话串行执行刷新，调用 `token/`，并原子性地替换令牌对。 |
| 退出登录 | 受 CSRF 保护的变更操作，撤销 `session/` 并清除应用会话。 |

仅在 Cookie 中发送随机的应用会话引用，该 Cookie 需设置 `Secure`、`HttpOnly`、`SameSite=Lax` 属性，并限定路径范围。请设置合适的过期时间，并在登录后轮换该引用。不要在渲染的 props、客户端组件或浏览器存储中暴露 Didit 刷新令牌。对令牌和回调响应使用 `Cache-Control: no-store`。

不要仅依赖布局或中间件检查：应在每次数据访问和变更操作时进行授权。对基于 Cookie 的变更操作，请防范 CSRF 攻击。只允许已配置的登录后目标地址，切勿接受查询字符串中任意的 `returnTo` URL。

## 软件包发布预览

计划中的软件包将新增中间件、服务器端 `auth()`、回调路由，以及用于服务器渲染的 HttpOnly Cookie 支持。核心 `/server` 入口计划提供带缓存 JWKS 的 `verifyToken()`。请等待经过验证的正式版本导出内容后再使用这些符号。在此之前，请按照 [令牌与 JWKS](https://docs.didit.me/zh/authentication/tokens-and-jwks.md) 中的说明，使用任意 JOSE 库自行验证令牌。

## 连接其他产品

在服务器上创建验证会话，并签发限定范围的监控令牌。根据已验证的人员映射推导 `vendor_data`。仅向浏览器返回验证会话 URL 或短期有效的 SDK 令牌。请勿将 `DIDIT_API_KEY` 放入公开的环境变量中。

使用现有的 [Web 验证 SDK](https://docs.didit.me/zh/integration/web-sdks/javascript-sdk.md) 进行验证，使用 [交易提交指南](https://docs.didit.me/zh/transaction-monitoring/sdk-transaction-submission.md) 进行监控。两者都不是身份验证会话管理器。

上线前请测试回调重放、错误的 state、过期的 state、刷新竞争、已撤销的会话、CSRF 拒绝以及退出登录。验证约定请参阅 [令牌与 JWKS](https://docs.didit.me/zh/authentication/tokens-and-jwks.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.