> ## 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.

# Didit 身份认证集成指南：架构与上线

> Didit 身份认证生产环境集成的完整架构：托管页或自定义界面、令牌存储、后端校验、会话、原生应用与上线流程。

本指南说明生产环境中的 Didit Authentication 集成如何协同工作，从首次重定向到上线检查清单。
如果您尚未对用户完成登录，请先阅读[快速入门](https://docs.didit.me/zh/authentication/quickstart.md)；各 SDK 的代码示例请参阅各平台的快速入门。

## 架构

```mermaid theme={null}
sequenceDiagram
    participant App as Your app (browser or mobile)
    participant Hosted as Your Didit sign-in origin
    participant API as Your backend
    participant Webhook as Your webhook endpoint

    App->>Hosted: Open /sign-in (redirect_uri, state, PKCE challenge)
    Note over Hosted: Sign-in method, MFA,<br/>bot protection, verification
    Hosted-->>App: Redirect to redirect_uri with code and state
    App->>Hosted: POST /token/ (code, PKCE verifier)
    Hosted-->>App: Access token (5 min), ID token, refresh token
    App->>API: Request with Authorization: Bearer access token
    Note over API: Verify the signature<br/>with the cached JWKS
    API->>Hosted: GET /session/ before a sensitive action
    Hosted-->>API: Live session, or 401
    Hosted->>Webhook: auth.signup, auth.login, auth.new_device ...
```

涉及四个部分：

| 组成部分 | 职责 |
| - | - |
| 您的应用 | 发起登录，保存 PKCE 验证器和 `state`，持有令牌，并将访问令牌发送给您的后端。SDK 会完成所有这些操作。 |
| 您的登录源 | `https://<slug>.auth.didit.me`（或您的[自定义域名](https://docs.didit.me/zh/authentication/branding-and-custom-domain.md#自定义域名)）：托管页面、令牌端点、会话、发现文档和签名密钥。 |
| 您的后端 | 在每个受保护的请求中验证访问令牌，在执行敏感操作前检查会话，并决定该用户可以执行哪些操作。 |
| Didit 控制台和 Webhook | 配置、用户及其会话、登录事件，以及您的服务器订阅的 `auth.*` Webhook。 |

Didit API 密钥和任何秘密信息都绝不能放在您的应用中：可发布密钥本身是公开的，授权码交换则由 PKCE 而非客户端密钥来保护。

## 托管页面还是您自己的界面

选择用户在哪里输入电子邮件、密码或验证码。
设置项为 `sign_in_ui`（默认为 `hosted`，也可设为 `own`），您之后可以随时更改。

| | 托管页面（推荐） | 您自己的界面 |
| - | - | - |
| 您需要构建什么 | 一个登录按钮和一个回调页面。 | 所有界面以及每个中间步骤。 |
| 登录方式 | 全部方式，包括魔法链接、企业 SSO 和通行密钥。 | 密码、电子邮件验证码、手机验证码、MFA 以及防护挑战，通过 SDK 的无界面方法实现。魔法链接仅在托管页面上可用。 |
| 后续步骤 | 由我们为您处理：MFA、MFA 注册、防护挑战以及注册时的验证。 | 您的界面需要处理 `mfa_required`、`mfa_enrollment_required`、`protection_required` 和 `verification_required`。请参阅 [登录方式](https://docs.didit.me/zh/authentication/sign-in-methods.md)。 |
| 品牌 | 您的 Logo、颜色和文案来自 [品牌设置](https://docs.didit.me/zh/authentication/branding-and-custom-domain.md)。 | 完全由您自定义。 |
| 设置 | 重定向 URL。 | 重定向 URL，以及在 **Allowed origins** 中添加您的 Web 来源。 |

通行密钥与您应用的登录源相关联。
SDK 的通行密钥方法仅在从该源提供的页面上有效，因此如果您的自定义界面位于其他域名，请将用户引导至托管页面进行通行密钥登录。

## 选择 SDK

| 您的应用 | 包 | 令牌存储位置 |
| - | - | - |
| 单页 Web 应用 | [`@didit-protocol/auth`](https://docs.didit.me/zh/authentication/quickstarts/javascript) 或 [`@didit-protocol/auth-react`](https://docs.didit.me/zh/authentication/quickstarts/react) | 浏览器中的 Web 存储或内存。请保持严格的内容安全策略。 |
| 服务端渲染的 Web 应用 | [`@didit-protocol/auth-nextjs`](https://docs.didit.me/zh/authentication/quickstarts/nextjs) | 由您的服务器设置的带有 HttpOnly 标志的 Cookie。页面永远无法读取令牌。 |
| iOS | [`DiditAuth`](https://docs.didit.me/zh/authentication/quickstarts/ios) | Keychain（钥匙串）。 |
| Android | [`me.didit:didit-auth`](https://docs.didit.me/zh/authentication/quickstarts/android) | 受 Android Keystore（密钥库）保护的存储。 |
| React Native 或 Flutter | [`@didit-protocol/auth-react-native`](https://docs.didit.me/zh/authentication/quickstarts/react-native) 或 [`didit_auth`](https://docs.didit.me/zh/authentication/quickstarts/flutter) | 通过原生模块使用平台提供的受保护存储。 |
| 任意后端 | [服务端 SDK](https://docs.didit.me/zh/integration/server-sdks/overview.md)、来自 `@didit-protocol/auth/server` 的 `verifyToken`，或任意 JWT 库 | 无需存储任何内容：它只验证收到的 token。 |

如果不使用 SDK，请自行实现带 PKCE 的授权码流程：[JavaScript 快速入门](https://docs.didit.me/zh/authentication/quickstarts/javascript.md#不使用-sdk)展示了完整的协议约定。

## 保护你的后端

仅在前端检查会话状态，只能控制你展示的内容。你的后端应基于经过验证的 token 做出每一项决定。

1. **每次请求都验证访问 token。** 使用你的颁发方 JWKS 检查 ES256 签名，然后检查 `iss`、`aud`、`exp` 和 `typ: at+jwt`。除非路由允许 [AI 智能体](https://docs.didit.me/zh/authentication/agent-access.md)访问，否则拒绝 `act` 不为 `null` 的 token。参见[在服务器上验证 token](https://docs.didit.me/zh/authentication/tokens-and-jwks.md#在服务器上验证令牌)。
2. **在敏感操作前检查实时会话。** 访问 token 会一直有效直到过期，过期时间在 5 分钟之内。当会话已被撤销、闲置或过期，当用户被封禁，或当会话不再满足你的 MFA 策略时，`GET /session/` 会立即失败。参见[检查会话](https://docs.didit.me/zh/authentication/tokens-and-jwks.md#检查会话)。
3. **在操作存在风险时要求 step-up 验证。** 在打款、添加新银行账户或更改邮箱或手机号之前，向 Didit 询问该用户是否需要重新验证。只根据你的后端自行读取的 `approved` step-up 结果采取行动。参见[敏感操作前的 step-up 验证](https://docs.didit.me/zh/authentication/verified-identity.md#敏感操作前的升级验证)。
4. **从经过验证的 token 中获取 `vendor_data`**，切勿从浏览器发送的字段中获取，并将其用于该用户的验证和交易。

## 会话

| 事件 | 会发生什么 |
| - | - |
| 登录 | 会话开始。会话时长由您的 `session_lifetime` 决定（默认 30 天）。如果在 `idle_timeout` 时长内没有任何活动（默认 1 天），会话会提前结束。 |
| 每隔几分钟 | SDK 会刷新访问令牌，其有效期最长为 5 分钟。刷新令牌会轮换：每个只能使用一次。 |
| 已使用的刷新令牌被再次发送 | Didit 会将其视为盗用并结束会话。每个会话同一时间只能运行一次刷新。 |
| 在另一台设备上登录 | 当 `multiple_sessions: false` 时，该用户的其他会话会结束。 |
| 重置密码 | 开启 `revoke_on_password_change`（默认开启）后，所有会话都会结束。 |
| 退出登录 | `DELETE /session/` 会结束会话，您的应用会将用户带到您的 `post_logout_redirect_uri`。 |
| 您的团队进行操作 | 控制台可以撤销单个会话、让用户在所有地方退出登录，或封禁该用户。请参阅[控制台指南](https://docs.didit.me/zh/authentication/console.md#登录与会话)。 |

在 **Authentication > Security and sessions** 中修改时长，或通过 API 在[应用设置](https://docs.didit.me/zh/authentication/overview.md#应用设置)中修改。

![Didit 商业控制台中的 Active sessions 视图，列出已登录会话的设备、位置、开始时间、最后活动时间、结束时间，以及 Revoke 按钮](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-active-sessions.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=098f6be31804b0af7c680e569f341bfb)

Authentication > Sign-ins > Active sessions，其中每个会话旁都有 Revoke 按钮。

## 原生应用

Didit 仅通过 HTTPS 重定向将用户返回到原生应用，不接受任何自定义 URL 方案。

* **iOS：** 将重定向设置为关联域名，并在您的 `apple-app-site-association` 中添加 `webcredentials`。
* **Android：** 将重定向设置为 App Link，并配置您的 `assetlinks.json`。
* 将每个重定向 URL 都注册到 **Authentication > Security and sessions** 下，与 Web 回调的注册方式相同。

如果您希望应用中使用通行密钥，请通过[身份验证管理 API](https://docs.didit.me/zh/authentication/set-up-by-api.md)，使用 `PUT native-apps/` 注册与您的应用共享通行密钥的应用。
Didit 随后会在您的登录源上提供的 `apple-app-site-association` 和 `assetlinks.json` 中列出这些应用。
`MANAGEMENT_BASE` 是您应用的管理 API 地址。具有 `authentication` 范围且权限为 **write** 的 API 密钥可以发起该调用。
该调用会替换这两个列表，因此请同时发送：

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}native-apps/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ios_app_ids": ["ABCDE12345.com.example.app"],
    "android_apps": [
      {
        "package_name": "com.example.app",
        "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
      }
    ]
  }'
```

| 字段 | 规则 |
| - | - |
| `ios_app_ids` | 最多 10 项，每项为您的 Team ID 与 Bundle ID，例如 `ABCDE12345.com.example.app`。 |
| `android_apps` | 最多 10 个应用，每个应用包含其 `package_name` 以及 1 到 5 个 SHA-256 签名证书指纹。 |

[iOS](https://docs.didit.me/zh/authentication/quickstarts/ios.md) 和 [Android](https://docs.didit.me/zh/authentication/quickstarts/android.md) 快速入门介绍了应用端的设置。

## 连接身份验证与交易监控

每位用户在其 token 和会话中都有一个 `vendor_data` 值。
在[创建验证会话](https://docs.didit.me/zh/sessions-api/create-session.md)或[提交交易](https://docs.didit.me/zh/transaction-monitoring/transactions.md)时，将其用作 `vendor_data`，控制台即可显示为同一位用户的登录、验证和交易。

* 若要在注册时或打款前再次验证用户，而无需自行搭建验证流程，请使用[已验证身份](https://docs.didit.me/zh/authentication/verified-identity.md)。
* 登录事件会自动进入[事件规则](https://docs.didit.me/zh/transaction-monitoring/event-rules.md)和欺诈视图。请勿为相同的登录再发送您自己的 `auth.login` 事件。
* 成功登录绝不会批准验证或交易：请分别处理各产品的决策。

请参阅[跨产品识别同一用户](https://docs.didit.me/zh/authentication/overview.md#在多个产品之间保持同一用户)。

## 接收登录事件

请为您需要的 `auth.*` 类型订阅一个 [Webhook 目标](https://docs.didit.me/zh/integration/webhooks.md)，例如 `auth.new_device` 或 `auth.account_locked`。
请使用 `auth_event.event_id` 进行去重，并像验证所有 Didit Webhook 一样验证签名。
各类型及其 payload 的完整说明，请参阅[事件与 Webhook](https://docs.didit.me/zh/authentication/events-and-webhooks.md)。

## 迁移现有用户

如果您的用户已在其他身份认证平台或您自己的数据库中拥有账户，请在切换登录方式之前[导入这些用户](https://docs.didit.me/zh/authentication/migration.md)。
如果来源方提供密码哈希，请一并导入；保留用户的社交账号关联，并将您自有的用户 ID 保留为 `external_id`，它会成为其 `vendor_data`。
在您将应用切换到 Didit 之前，用户不会受到任何影响。

## 上线检查清单

1. 已在 **Products** 页面为您的 Live 应用开启身份认证。
2. 您的生产环境 `https://` 重定向 URL 和允许的来源已注册到 Live 应用。Live 应用不接受 `http://` 地址。
3. 每种社交登录方式都使用您自己应用的客户端 ID 和客户端密钥：Didit 的测试凭据仅适用于沙盒。
4. 您的生产配置包含 Live 可发布密钥（`pk_live_`）和 Live 颁发者。
5. 您的多因素认证（MFA）策略、会话有效期、空闲超时、密码长度和注册策略均已按您的需求设置。请参阅[应用设置](https://docs.didit.me/zh/authentication/overview.md#应用设置)。
6. 已开启[机器人防护](https://docs.didit.me/zh/authentication/bot-protection.md)，并包含泄露密码检查。
7. 您的后端会验证每个访问令牌，并在敏感操作之前调用 `GET /session/`。
8. 您的品牌设置、页面文案以及服务条款和隐私政策链接已配置完成。如果您计划使用[自定义域名](https://docs.didit.me/zh/authentication/branding-and-custom-domain.md#自定义域名)，请在用户开始添加通行密钥之前激活它。
9. 您的 Webhook 目标已订阅您需要处理的 `auth.*` 类型。
10. 您已在 Live 应用上测试了以下场景：注册、再次登录、取消操作、忘记密码、MFA、会话过期、退出登录以及已撤销的会话。

## 故障排查

| 现象 | 原因与解决方法 |
| - | - |
| 所有运行时路由都返回 `404` | 应用未开启身份认证，或地址混用了沙盒和生产环境来源。请在 **Products** 页面开启身份认证，并使用您的可发布密钥所指定的来源。 |
| 登录页面返回 `400` 并要求您注册地址，或 `POST /authorize/` 返回 `invalid_redirect_uri` | `redirect_uri` 未被精确注册：协议、主机、端口、路径和查询参数必须逐字符一致。请参阅[重定向 URL](https://docs.didit.me/zh/authentication/overview.md#重定向-url)。 |
| 浏览器对您的登录来源的调用返回 `403` 和 `origin_not_allowed` | 您的 Web 来源不在 **Allowed origins** 中。请添加该来源，不含路径，末尾不加斜杠。 |
| `POST /token/` 返回 `invalid_grant` | 授权码已被使用、超过 60 秒，或发送时使用了其他 PKCE 验证器或 `redirect_uri`。若是刷新，则刷新令牌已被使用，这会结束会话。请重新开始登录。 |
| 使用正确密码登录时返回 `invalid_credentials` | 邮箱未验证，或账户已被锁定或封禁。Didit 有意返回相同的结果。请在 **Users** 中查看该用户。 |
| `GET /session/` 返回 `401` | 会话已被撤销、因闲置或过期而失效、用户已被封禁、令牌已因刷新而被替换，或会话不再符合您的 MFA 策略。请刷新令牌，或让用户重新登录。 |
| 添加通行密钥或身份验证器时返回 `403 reauthentication_required` | 这些操作需要在过去 5 分钟内创建的会话。请先让用户重新登录。 |
| 手机验证码返回 `503 delivery_unavailable` | 验证码无法投递。请让用户重试，或提供其他验证方式。 |
| 调用返回 `429` | 您触发了速率限制。请在 `Retry-After` 所示的时间之后重试。请参阅[速率限制](https://docs.didit.me/zh/authentication/bot-protection.md#速率限制)。 |
| 使用 API 密钥的设置调用返回 `409 product_disabled` | 应用未开启身份认证。用户需要在控制台中开启。 |
| 调用返回 `403 plan_required` | 该功能（例如自定义角色或企业 SSO 设置链接）需要 Scale 或 Enterprise 套餐。沙盒应用无论使用哪种套餐都已开启该功能。 |
| 激活自定义域名后，令牌验证失败 | 颁发者和可发布密钥已变更。请将新密钥复制到您的应用中，并更新后端校验的颁发者。 |


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