SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场sumsub-integrate-id-connect

sumsub-integrate-id-connect

安全与审计

查看项目

更新于 10-15 02:21

技能介绍

用途

Sumsub ID Connect 集成技能用于把“Verify with Sumsub ID”这一基于 OIDC 的流程端到端嵌入到应用中。它让业务方能够向终端用户的 Sumsub ID 账户请求特定的已验证身份声明，例如年龄、姓名、国籍、邮箱、居住国家、真人性等。Sumsub 托管整个面向用户的流程，包括登录、账户创建、邮箱 OTP、缺失的验证步骤以及针对每个接收方的同意页面。应用最终会收到一个签名的 OIDC 令牌，并可选地通过 Reusable KYC 在工作区中生成申请人记录。

该技能明确说明：这不是 WebSDK。WebSDK 在页面内执行完整的 KYC 采集，而 ID Connect 把整个用户体验委托给 Sumsub。

主要能力

技能覆盖从准备到落地的完整链路：

  • 前置条件检查（Stage 0a）：确认 Sumsub 支持团队已为工作区启用 ID Connect、已生成沙箱 App Token 与 secret、已在 Dashboard 的 Dev Space → OIDC Settings 注册 OIDC 客户端并配置 redirect_uri 允许列表、工作区中至少存在一个验证级别、至少有一个带已验证数据的 Sumsub ID 账户用于端到端测试。
  • 预检脚本（Stage 0b）：运行 scripts/preflight.sh，对可在不生成 OIDC 授权码、不创建申请人的情况下探测的前置条件进行机器校验，包括 connect_token、oidc_discovery、levels 三项检查。全部通过或通过加警告时退出码为 0，任一失败为 10。
  • 前端按钮（Stage 1）：提供三种接入方式。方法一为使用 @sumsub/id-connect 的 createButton 预构建按钮（推荐）；方法二为自有触发元素配合库的 openModal；方法三为不依赖库的原始 OIDC 重定向，适用于 CSP 禁止第三方脚本、仅 SSR 环境或维护通用 OIDC 客户端的场景。
  • 后端编排（Stage 2-4）：前端把 code 与 codeVerifier POST 到自有后端，后端使用 App Token 与 secret 签名调用 Sumsub API，依次完成 code → access_token、access_token → share token、共享允许性判断、shareLink 重定向与重试、reuse/preview 与 reuse/commit，最终在工作区中生成申请人。

使用方式

技能强调严格的执行顺序：在两道门禁（Stage 0a 前置条件全部确认、Stage 0b 预检退出码为 0）都通过之前，不得编写任何前端或后端代码、不得创建演示项目、不得搭建脚手架。客户端侧的 Sumsub 配置（Stage 0a）是手动操作，无法由 AI 代劳，必须逐项与用户确认。

关键端点包括：

  • 浏览器重定向：https://id.sumsub.com/api/snsId/oauth/authorize（Stage 1，无需认证）
  • GET https://id.sumsub.com/.well-known/openid-configuration（Stage 0b，无需认证）
  • GET https://id.sumsub.com/.well-known/jwks.json（id_token 验证，无需认证）
  • POST https://id.sumsub.com/api/snsId/oauth/token（Stage 2，client_secret_basic）
  • POST https://api.sumsub.com/resources/accessTokens/sumsubIdShareToken（Stage 3a，App Token + HMAC）
  • POST https://api.sumsub.com/resources/snsId/oauth/shareLink（Stage 3b，App Token + HMAC + Bearer）
  • GET https://api.sumsub.com/resources/api/reusableIdentity/reuse/preview（Stage 4，App Token + HMAC）
  • POST https://api.sumsub.com/resources/api/reusableIdentity/reuse（Stage 4，App Token + HMAC）

前端使用 PKCE（S256），自行生成 code_verifier 与 code_challenge，并把 verifier 存在自有 sessionStorage 键下，以便后端在 Stage 2 换取访问令牌。Sumsub 只接受 code_challenge_method=S256，redirect_uri 必须与允许列表逐字节匹配。

本地开发不能使用 http://localhost，因为 Sumsub 要求 redirect_uri 为公开 HTTPS 且逐字节匹配允许列表。技能建议使用 ngrok 建立公开 HTTPS 隧道，并优先使用保留（静态）域名以避免每次重启后重新编辑允许列表。需要同时允许两个回调：authorize 回调与 shareLink 回调。

适用场景

适用于需要向用户请求已验证身份声明、并希望把整个验证与同意体验委托给 Sumsub 的业务应用。典型场景包括需要复用已有 Sumsub ID 验证结果的注册、登录或权限开通流程。技能也适用于需要在自有设计系统中嵌入触发按钮、或在无打包器、CSP 受限、仅 SSR 等环境下接入 OIDC 的团队。

限制

  • 必须使用沙箱令牌，不得在生产 App Token / secret 上接线。预检通过 sbx: 前缀检查强制这一点。
  • “Enable Sumsub ID Connect”开关、OIDC 客户端注册（client_secret + redirect_uri 允许列表）以及共享伙伴注册均为 Sumsub 仪表盘 UI 操作，没有公开 API 等价物，无法由 AI 代为完成。
  • 启用 ID Connect 需要联系 Sumsub 支持或 CSM，不是自助开关。
  • Stage 4 需要至少一个验证级别，否则无法生成申请人；若没有，需先转交 sumsub-create-level。
  • 仅邮箱账户（未完成 KYC）会导致 Stage 4 失败，错误码为 10521 reusable-kyc-inactive-sumsub-id-account。
  • onSuccess 不是验证结论信号，它只确认用户完成了 OIDC 同意步骤且 Sumsub 签发了授权码。实际验证结论来自 Stage 4 的 applicant.review.reviewStatus 或 applicantReviewed webhook。不得基于 onSuccess 触发授予访问或解锁功能。
  • 本地开发必须使用公开 HTTPS 隧道，裸 localhost 无法工作；使用临时 ngrok URL 时每次重启都需更新允许列表与 PUBLIC_BASE_URL。
  • 关于收费、价格、平台支持范围等更多细节，资料中暂未提供。