> ## 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 为终端用户添加登录功能，支持托管登录页、通行密钥、验证码、社交登录和 SSO，并可对接身份验证与交易监控。

> [!WARNING]
>
> 身份验证功能是新推出的。Didit 会为您的应用开启该产品。在开启之前，该应用的所有运行时路由都会返回 `404`。身份验证 SDK 软件包尚未发布，因此请使用托管流程和本页面中的 HTTP 接口。

身份验证用于让您的客户登录**您的应用**。它与登录 Didit 控制台或创建 Didit 开发者账户是分开的，也与验证某人的身份是分开的。

您可以单独使用身份验证，也可以将其与身份证件验证和交易监控结合使用。登录并不代表批准验证，也不代表授权付款。您的后端应根据各产品自身的结果做出这些决定。

## 工作原理

每个应用都有自己的登录来源和自己的 token 颁发方。生产应用和沙盒应用是分开的：它们拥有各自的来源、设置和身份标识。

| 项目 | 值 |
| - | - |
| 默认来源 | 生产应用为 `https://<slug>.auth.didit.me`，沙盒应用为 `https://<slug>.sandbox.auth.didit.me`。控制台会显示您的来源。已验证的自定义域名可以替换它。 |
| 托管页面 | 该来源下的 `/sign-in`、`/magic`、`/invite` 和 `/reset`。 |
| 运行时 API | 同一来源，例如 `POST {origin}/token/` 和 `GET {origin}/session/`。 |
| 颁发方 | 来源本身。发现文档位于 `{origin}/.well-known/openid-configuration`。 |
| 可发布密钥 | `pk_live_...` 或 `pk_test_...`。它用于标识应用，不是机密（无需保密）。 |

该流程采用带 PKCE 的 OAuth 2.0 授权码模式（仅支持 `S256`）：

1. 您的应用使用 `redirect_uri`、`state`、`code_challenge` 和 `code_challenge_method=S256` 打开 `{origin}/sign-in`。
2. 托管页面使用您启用的方式让用户登录或注册，包括所需的第二因素验证。
3. 浏览器携带 `code` 和 `state` 返回您的 `redirect_uri`。
4. 您的应用在 `POST {origin}/token/` 处用授权码换取访问 token、ID token 和刷新 token。

token 协定请参阅 [token 与 JWKS](https://docs.didit.me/zh/authentication/tokens-and-jwks.md)，各登录方式请参阅 [登录方式](https://docs.didit.me/zh/authentication/sign-in-methods.md)。

## 选择您的平台

> [card] [JavaScript](https://docs.didit.me/zh/authentication/quickstarts/javascript.md)
>
> 托管登录、回调、会话和退出登录。

> [card] [React](https://docs.didit.me/zh/authentication/quickstarts/react.md)
>
> 客户端状态和受保护的应用视图。

> [card] [Next.js](https://docs.didit.me/zh/authentication/quickstarts/nextjs.md)
>
> 服务端会话、回调路由和 Cookie。

> [card] [iOS](https://docs.didit.me/zh/authentication/quickstarts/ios.md)
>
> 系统浏览器和安全的 token 存储。

> [card] [Android](https://docs.didit.me/zh/authentication/quickstarts/android.md)
>
> 浏览器授权和应用回调。

> [card] [React Native](https://docs.didit.me/zh/authentication/quickstarts/react-native.md)
>
> 原生身份验证封装的准备工作。

> [card] [Flutter](https://docs.didit.me/zh/authentication/quickstarts/flutter.md)
>
> 原生身份验证封装的准备工作。

## 准备您的应用

1. 请求 Didit 为您的应用开启身份验证。请先在沙盒应用中测试。
2. 注册您精确的[重定向 URL](#重定向-url)（最多 50 个），以及调用运行时 API 的浏览器 `allowed_origins`（最多 50 个）。
3. 启用您希望提供的[登录方式](https://docs.didit.me/zh/authentication/sign-in-methods.md)。Didit ID Wallet 始终处于开启状态。
4. 选择您的会话和密码设置（见下文）。
5. 正式上线前，请测试注册、登录、忘记密码、MFA、会话过期和退出登录。

通行密钥属于其所在的来源。如果您之后激活自定义域名，用户必须重新注册其通行密钥。

## 重定向 URL

Didit 只会将用户重定向到您已注册的地址。
请在控制台中注册您的地址，位置为 **Authentication > Security and sessions > Redirect URLs and allowed origins**。

登录请求中的 `redirect_uri` 必须与已注册的 URL 逐字符一致：协议、主机、端口、路径和查询参数都要相同。
端口不同、结尾多一个斜杠或字母大小写不同，都属于不同的地址。

| 应用 | 可以注册的内容 |
| - | - |
| 生产应用 | `https://` URL |
| 沙盒应用 | `https://` URL，以及 `localhost`、`127.0.0.1` 或 `[::1]` 上的 `http://` URL |

包含通配符、片段、URL 中的凭据以及自定义协议的地址会被拒绝。

如果地址未注册，Didit 绝不会重定向到该地址。
`{origin}/sign-in` 会返回 `400`，并显示一个页面，说明需要注册什么以及在哪里注册；`POST {origin}/authorize/` 会返回 `400 {"error": "invalid_redirect_uri"}`。

### 本地开发

请使用您的沙盒应用，在自己的计算机上进行测试：

1. 注册带端口的回调地址，例如 `http://localhost:3000/auth/callback`。
2. 如果浏览器代码会调用运行时 API，例如在 `POST {origin}/token/` 处用授权码换取 token，还需将该来源添加到 **允许的来源**：`http://localhost:3000`，不带路径，也不带结尾斜杠。
3. 使用您的 `pk_test_...` 密钥，从沙盒来源 `https://<slug>.sandbox.auth.didit.me` 开始登录。

`localhost`、`127.0.0.1` 和 `[::1]` 是不同的地址，每个端口也各不相同。
您使用的每一个都需要单独注册。

生产应用从不接受 `http://`。
正式上线前，请在您的生产应用上注册生产环境的 `https://` 回调地址。

## 应用设置

您可以在控制台中管理这些设置，也可以使用具有 `write:authentication` 权限的控制台会话进行管理。

| 设置 | 可选值 | 默认值 |
| - | - | - |
| `session_lifetime` | `86400`、`604800`、`2592000`、`7776000` 秒 | `2592000`（30 天） |
| `idle_timeout` | `1800`、`7200`、`86400`、`604800` 秒 | `86400`（1 天） |
| `multiple_sessions` | `false` 表示每次新登录时，该用户的其他会话都会退出登录 | `true` |
| `password_min_length` | `8`、`10`、`12`、`14` | `10` |
| `revoke_on_password_change` | 密码重置后结束所有会话 | `true` |
| `signup_policy` | `anyone`、`invited`、`allowed_domains`（需配合 `allowed_email_domains`，最多 100 个） | `anyone` |
| `allow_subaddresses` | 接受邮箱本地部分中的 `+` | `false` |
| `post_logout_redirect_uri` | 用户退出登录后，您的应用将其跳转到的地址 | 为空 |
| `mfa_policy` | `optional`、`everyone`、`organization_admins` | `organization_admins` |
| `sign_in_ui` | `hosted` 或 `own` | `hosted` |

## 在各产品间保持同一用户

每个身份都带有一个 `vendor_data` 值。如果您通过[导入](https://docs.didit.me/zh/authentication/migration.md)方式添加过该用户，它就是您提供的 `external_id`；否则为 Didit 身份 ID。它会出现在访问令牌、ID 令牌和 `GET session/` 中。

在创建验证会话和提交交易时，请使用相同的值作为 `vendor_data`。这样，认证事件就会在控制台中归入同一用户，与其验证和交易记录一起显示。请参阅[事件与 Webhook](https://docs.didit.me/zh/authentication/events-and-webhooks.md)。

请在后端从已验证的令牌中获取 `vendor_data`，切勿从未经校验的浏览器字段中获取。

| 产品组合 | 需要构建的内容 |
| - | - |
| 认证 | 登录、验证会话并退出登录。 |
| 身份验证 + 认证 | 在登录后，按照您的策略需要时，使用令牌中的 `vendor_data` 发起验证。 |
| 交易监控 + 认证 | 为已登录用户的 `vendor_data` 提交交易。登录事件会进入同一用户的时间线并参与规则判断。 |
| 以上三者 | 每位用户一个 `vendor_data`。分别处理各产品的决策。 |

任何组合都可以使用[共享集成提示词](https://docs.didit.me/zh/integration/integration-prompt.md)。有关登录时运行的策略，请阅读[机器人防护](https://docs.didit.me/zh/authentication/bot-protection.md)。


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