架构
涉及四个部分:
Didit API 密钥和任何秘密信息都绝不能放在您的应用中:可发布密钥本身是公开的,授权码交换则由 PKCE 而非客户端密钥来保护。
托管页面还是您自己的界面
选择用户在哪里输入电子邮件、密码或验证码。 设置项为sign_in_ui(默认为 hosted,也可设为 own),您之后可以随时更改。
通行密钥与您应用的登录源相关联。
SDK 的通行密钥方法仅在从该源提供的页面上有效,因此如果您的自定义界面位于其他域名,请将用户引导至托管页面进行通行密钥登录。
选择 SDK
如果不使用 SDK,请自行实现带 PKCE 的授权码流程:JavaScript 快速入门展示了完整的协议约定。
保护你的后端
仅在前端检查会话状态,只能控制你展示的内容。你的后端应基于经过验证的 token 做出每一项决定。- 每次请求都验证访问 token。 使用你的颁发方 JWKS 检查 ES256 签名,然后检查
iss、aud、exp和typ: at+jwt。除非路由允许 AI 智能体访问,否则拒绝act不为null的 token。参见在服务器上验证 token。 - 在敏感操作前检查实时会话。 访问 token 会一直有效直到过期,过期时间在 5 分钟之内。当会话已被撤销、闲置或过期,当用户被封禁,或当会话不再满足你的 MFA 策略时,
GET /session/会立即失败。参见检查会话。 - 在操作存在风险时要求 step-up 验证。 在打款、添加新银行账户或更改邮箱或手机号之前,向 Didit 询问该用户是否需要重新验证。只根据你的后端自行读取的
approvedstep-up 结果采取行动。参见敏感操作前的 step-up 验证。 - 从经过验证的 token 中获取
vendor_data,切勿从浏览器发送的字段中获取,并将其用于该用户的验证和交易。
会话
在 Authentication > Security and sessions 中修改时长,或通过 API 在应用设置中修改。

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 回调的注册方式相同。
PUT native-apps/ 注册与您的应用共享通行密钥的应用。
Didit 随后会在您的登录源上提供的 apple-app-site-association 和 assetlinks.json 中列出这些应用。
MANAGEMENT_BASE 是您应用的管理 API 地址。具有 authentication 范围且权限为 write 的 API 密钥可以发起该调用。
该调用会替换这两个列表,因此请同时发送:
iOS 和 Android 快速入门介绍了应用端的设置。
连接身份验证与交易监控
每位用户在其 token 和会话中都有一个vendor_data 值。
在创建验证会话或提交交易时,将其用作 vendor_data,控制台即可显示为同一位用户的登录、验证和交易。
- 若要在注册时或打款前再次验证用户,而无需自行搭建验证流程,请使用已验证身份。
- 登录事件会自动进入事件规则和欺诈视图。请勿为相同的登录再发送您自己的
auth.login事件。 - 成功登录绝不会批准验证或交易:请分别处理各产品的决策。
接收登录事件
请为您需要的auth.* 类型订阅一个 Webhook 目标,例如 auth.new_device 或 auth.account_locked。
请使用 auth_event.event_id 进行去重,并像验证所有 Didit Webhook 一样验证签名。
各类型及其 payload 的完整说明,请参阅事件与 Webhook。
迁移现有用户
如果您的用户已在其他身份认证平台或您自己的数据库中拥有账户,请在切换登录方式之前导入这些用户。 如果来源方提供密码哈希,请一并导入;保留用户的社交账号关联,并将您自有的用户 ID 保留为external_id,它会成为其 vendor_data。
在您将应用切换到 Didit 之前,用户不会受到任何影响。
上线检查清单
- 已在 Products 页面为您的 Live 应用开启身份认证。
- 您的生产环境
https://重定向 URL 和允许的来源已注册到 Live 应用。Live 应用不接受http://地址。 - 每种社交登录方式都使用您自己应用的客户端 ID 和客户端密钥:Didit 的测试凭据仅适用于沙盒。
- 您的生产配置包含 Live 可发布密钥(
pk_live_)和 Live 颁发者。 - 您的多因素认证(MFA)策略、会话有效期、空闲超时、密码长度和注册策略均已按您的需求设置。请参阅应用设置。
- 已开启机器人防护,并包含泄露密码检查。
- 您的后端会验证每个访问令牌,并在敏感操作之前调用
GET /session/。 - 您的品牌设置、页面文案以及服务条款和隐私政策链接已配置完成。如果您计划使用自定义域名,请在用户开始添加通行密钥之前激活它。
- 您的 Webhook 目标已订阅您需要处理的
auth.*类型。 - 您已在 Live 应用上测试了以下场景:注册、再次登录、取消操作、忘记密码、MFA、会话过期、退出登录以及已撤销的会话。