身份验证API：集成与评估指南 (ZH)

身份验证API允许应用程序收集或提交身份证据，并接收关于声称身份的结构化结果。根据工作流，它可以验证身份文件、提取属性、将实时申请人与参考肖像进行比较、进行活体检测、核实数据或将多项检查编排到一个会话中。

API响应是证据，而非完整的业务决策。生产集成还必须定义可信捕获、客户状态所有权、状态转换、重试、审查、隐私、记录保存以及将技术结果转换为批准、重试、升级、审查或拒绝的策略。

主要收获

• 身份验证API不仅仅是一个端点。真正的契约包括捕获、异步状态、证据、事件、协调、审查和删除。
• 后端拥有决策权。客户端重定向或视觉成功屏幕并非权威；最终状态应在服务器端确认。
• 结果需要范围和原因。文档真实性、持有者关联、活体检测、质量和情境风险应保持可分离，而不是合并为一个未解释的布尔值。
• 可靠性体现在故障路径中。幂等性、网络钩子验证、事件重放、超时、重试、版本控制和沙盒对等性与正常路径同样重要。
• 评估必须使用类似生产环境的用户群体。覆盖范围、防欺诈能力、完成度、错误结果、审查负荷和隐私应按文档、设备、地理位置和相关用户细分进行衡量。

身份验证API有什么作用？

身份验证API提供了一个机器可读的接口，用于身份证明功能。典型的集成会创建一个验证尝试，引导申请人完成安全的捕获体验，接收进度或完成事件，检索最终证据，并应用依赖组织的策略。

NIST SP 800-63A-4身份证明模型将三个重要功能分开：

• 解析：在相关群体中区分声称的个人。
• 验证：确定身份证据和属性是否真实、准确和可接受。
• 核实：确定申请人是否与该证据相关联。

一个API可能执行其中一个、两个或全部三个功能。产品名称不能保证范围，因此需求应说明每个结果预期达到的确切结论。

身份验证API、文档API、KYC API和OCR对比

接口	主要目的	有用输出	它本身无法证明什么
OCR API	将文档像素转换为文本或字段	提取的姓名、日期、编号、地址	真实性、占有或客户风险
文档验证API	验证文档及其捕获的证据	真实性检查、有效期、字段一致性、篡改指示	当前申请人拥有它
人脸匹配API	将提交的人脸与参考进行比较	在阈值下的相似性或匹配决策	活体检测、文档真实性或合法身份
活体检测API	评估生物识别捕获时的活体存在	真实、攻击、重试或评分证据	此人的身份
身份验证API	结合证据验证和申请人关联	证据级别结果和工作流结果	完整的KYC或业务资格
KYC API	支持更广泛的客户尽职调查流程	身份、筛选、风险、工作流和记录	在没有组织策略的情况下自动合规

这种区分可以防止架构错误。例如，在上传表单中添加OCR可以加快数据输入，但不能验证文档。添加人脸匹配连接了两个图像，但无法确定任何一个图像是否通过可信的实时捕获获得。

有关这些接口周围的更广泛策略、筛选、风险和持续审查背景，请参阅KYC生命周期指南。本文停留在开发人员信任边界：捕获、API状态、证据、事件、协调和后端决策。

常见的集成模型

托管验证会话

应用程序的后端创建一个会话并接收一个短生命周期的URL或令牌。用户在提供商托管的流程中完成捕获，然后返回应用程序。此模型可以减少前端和设备复杂性，同时保留服务器端控制。

关键问题包括品牌、域名切换、可访问性、本地化、移动浏览器支持、会话过期、返回行为以及当用户切换设备时应用程序如何恢复。

嵌入式Web或移动SDK

SDK在应用程序内部运行捕获体验。它可以提供更严格的接口控制和对设备功能的访问，但集成质量会影响安全性。版本支持、应用程序完整性、相机权限、虚拟相机处理、更新策略和遥测都将成为审查的一部分。

独立的服务器到服务器检查

客户系统直接将结构化数据或媒体发送到端点。这对于已受信任的捕获、批处理操作或单个模块非常有用。它还将捕获完整性、同意、质量、有效载荷安全性以及重放预防的责任转移给了集成商。

编排工作流

一个会话可以跨文档验证、数据库检查、活体检测、人脸匹配、筛选、设备信号和人工审查进行分支。API应公开工作流和策略版本，以便以后可以解释相同的状态。

安全的集成序列

1. 从后端创建尝试

受信任的后端生成一个内部客户引用，并使用所需的工作流、区域设置和策略上下文调用提供商。不要在浏览器或移动代码中暴露永久性API凭据。

为创建操作使用幂等性策略。客户端超时不应创建第二个计费尝试或将结果与原始客户分离。

2. 发布一个短生命周期的捕获交接

仅向前端提供该尝试所需的范围令牌或URL。将其绑定到预期的应用程序、客户引用、工作流和过期时间。避免在URL、分析事件或客户端日志中放置不必要的个人数据。

3. 捕获并验证证据

引导用户完成支持的证据和质量要求。将可恢复的质量问题与可疑攻击分开。“靠近一点”、“证件过期”和“捕获完整性失败”不应成为一个通用的错误。

4. 接收已认证事件

在验证之前，将网络钩子视为不可信输入。验证事件签名或消息认证、时间戳或新鲜度控制、预期目的地、内容类型和事件标识符。RFC 9421定义了HTTP消息签名的通用机制，尽管提供商可以使用不同的文档化签名方案。

存储事件标识符并幂等地处理它们。交付系统会重试；重复事件是正常的。不要假定到达顺序，并且不要让较旧的事件使客户从终止状态向后移动。

5. 检索规范结果

在完成事件后，从提供商API获取最终尝试。此协调步骤减少了对单个网络钩子内容的依赖，并可从错过或延迟的交付中恢复。

6. 应用组织策略

将结构化证据映射到组织自己的决策状态。提供商可能会推荐一个结果，但依赖组织了解产品、客户历史、法律依据、风险偏好和可用的恢复路径。

7. 记录转换

持久化内部客户参考、提供商尝试标识符、工作流和版本、相关证据或参考、原因代码、事件历史、策略版本、审查员操作和最终理由。在持久引用足够时，尽量减少复制敏感数据。

API应公开的状态模型

一个布尔型的verified字段对于真实的客户旅程来说太小了。有用的状态通常包括：

状态	含义	典型的应用程序操作
已创建	尝试存在但尚未开始捕获	呈现或重新发送安全交接
进行中	用户或异步检查正在进行	等待；不要授予最终访问权限
等待输入	需要更多证据或用户操作	显示精确的恢复指导
允许重试	捕获或质量可恢复失败	开始有界的新尝试
审查中	受过培训的审查员负责此案例	保持访问待定并公开预期下一步
已批准	所需证据符合配置的工作流	应用组织策略和状态转换
已拒绝	证据未能通过定义的控制	应用申诉、限制或替代路径
已过期或已放弃	尝试结束，没有决策	允许受控重启
技术错误	系统无法生成证据	重试或协调，不要将其视为欺诈

每个终止状态都应有结构化的原因。稳定的机器码允许策略和分析；本地化的人类消息有助于用户和审查员。RFC 9457为接口级别的机器可读HTTP问题详细信息提供了一种标准格式。

结果应包含哪些证据？

文档级证据

包括证据类型、签发国家、文档类别、有效期、字段一致性、质量以及与方法相关的验证指标。明确结果是来自光学检查、芯片数据、签发者或数据库核实，还是其他来源。

申请人关联证据

将人脸比较、活体检测、捕获完整性和身份属性关联分开。记录用于后续解释的参考和决策阈值或版本，而无需向每个消费者暴露不必要的生物识别材料。

风险和操作证据

设备、IP、速度、重复尝试或工作流信号可以指导升级和审查。它们不应默默地改变身份属性。保留生成每个原因的子系统。

来源和版本

当模型、文档模板、观察列表或策略发生变化时，结果可能会发生变化。存储提供商版本、工作流版本、决策时间、源参考以及案例是否经过人工审查。

API安全要求

身份API处理有价值的个人和生物识别数据，并暴露攻击者可以自动化的业务流程。OWASP API安全十大风险直接强调了此处相关的风险：损坏的对象授权、损坏的身份验证、过度属性暴露、不受限制的资源消耗、敏感流程自动化、糟糕的API清单以及对第三方API的不安全信任。

身份验证和授权

为测试和生产使用单独的凭据和应用程序。应用最小权限、轮换、撤销、环境隔离和对象级别授权。一个经过身份验证的组织不应该通过更改标识符来检索另一个组织的尝试。

上传和资源控制

验证媒体类型、大小、尺寸、结构和预期来源。设置超时、并发限制、速率控制和尝试限制。验证调用会消耗计算资源，并且可能产生每次检查的成本，这使得无边界的端点既是拒绝服务风险又是成本风险。

数据暴露

仅返回消费者所需的字段。分离操作角色，以便支持人员、分析师、开发人员和管理员默认情况下不会都收到完整的身份证据。从日志和可观察性工具中编辑敏感有效载荷。

网络钩子和重放控制

验证事件，保留签名验证所需的原始正文，拒绝过时或格式错误的交付，对事件标识符进行去重，并获取规范状态。轮换网络钩子密钥，同时不中断正在进行的交付。

清单和版本控制

记录每个活动的端点、版本、主机、凭据、回调、SDK和弃用日期。带有生产数据的影子测试端点或旧的未维护SDK可能会破坏已审查的路径。

如何测试身份验证API

契约和状态测试

执行每个文档化的状态、原因、重试、超时和终端转换。验证分页、过滤、错误正文、向后兼容性和未知字段行为。模拟重复和乱序的网络钩子。

证据测试

使用预期人群中文件类型、国家、脚本、过期条件、设备、摄像头和网络中的允许的代表性样本。分别跟踪不受支持、不可读、不匹配、被篡改和真实证据。

欺诈测试

构建一个授权攻击集，用于重放、打印证据、修改文档、虚拟摄像头、模拟器、注入媒体、重复身份和自动化尝试。NIST远程证明要求区分捕获传感器置信度、伪造媒体分析、受保护通道和生物识别比较，因为没有一种机制可以覆盖完整路径。

操作测试

衡量完成率、重试次数、放弃率、人工审查率、解决时间、支持联系人、网络钩子延迟、协调和可用性。按文档、设备、网络、语言和相关客户群分解结果。

决策质量测试

不要用一个“准确性”数字来比较提供商。在预期阈值下审查误接受和误拒绝、针对特定攻击的结果、样本数量、置信度、无响应情况以及下游确认结果。

隐私和删除测试

验证保留配置、导出、删除、访问日志、区域处理、子处理器控制以及在开放审查或法律要求保留期间收到删除请求时的行为。

如何评估提供商

范围和保证

包含哪些证明功能？适用哪些保证模型和独立测试？测试了哪些组件和版本？提供商能否解释通过意味着什么，不意味着什么？

覆盖范围

请求国家和文件矩阵，而不仅仅是总数。测试您的客户提交的证据，包括旧设备、多种脚本、低质量摄像头以及不常见但合法的文档。

开发者体验

审查API一致性、OpenAPI质量、SDK维护、示例、沙盒场景、网络钩子工具、变更日志纪律、迁移策略、状态页面和支持升级。五行快乐路径示例不是生产集成指南。

操作和可解释性

检查审查队列、证据视图、角色权限、审计日志、原因代码、申诉和导出。确认人类可以区分技术故障、质量重试、可能的攻击和身份不匹配。

商业和可移植性

了解基于成功与基于尝试的计费、审查费用、最低限额、限制、存储、区域选项和退出条款。保持您的内部客户参考和策略边界可移植，以便提供商更改不需要重写账户状态。

常见的集成错误

从返回URL授予访问权限

用户控制浏览器路径。成功重定向是接口状态，而不是证明。从受信任的后端确认最终状态。

将每次失败都视为欺诈

权限拒绝、超时、不支持的证据、模糊、以及可疑篡改是不同的。将它们混淆会造成错误拒绝和无法使用的分析。

仅处理一次网络钩子

网络无法保证仅处理一次交付。设计用于至少处理一次事件，并进行去重、单调转换和规范检索。

记录完整的有效载荷

方便的调试日志记录可以将文档和生物识别数据复制到具有更广泛访问权限和更长保留期的系统中。使用标识符、结构化原因和受控证据访问。

仅测试沙盒成功案例

生产故障发生在重试、旧设备、边缘文档、事件延迟、版本更改和审查中。将故障场景作为验收套件的一部分。

外包策略决策

供应商结果无法了解每个司法管辖区、客户类型、产品风险或业务限制。保留组织的决策逻辑和问责制。

实施清单

在生产之前，确认以下事项：

• API凭据保留在服务器端，并按环境和角色进行范围限定；
• 创建调用是幂等的，并映射到稳定的内部客户参考；
• 捕获令牌是短生命周期的，并绑定到预期的尝试；
• 每个状态和原因都有明确的客户和后端操作；
• 网络钩子签名、新鲜度、重复和排序已测试；
• 规范检索可协调错过或延迟的事件；
• 证据级输出与最终客户决策保持分离；
• 速率、上传、并发和尝试控制可抵御自动化滥用；
• 文档、设备、欺诈、隐私、可访问性和审查测试使用类似生产环境的样本；
• 保留、删除、事件响应、版本控制和迁移有负责人。

使用Didit进行身份验证

Didit 提供身份验证作为一个可组合模块，并允许团队通过工作流编排器添加活体检测、设备和IP分析以及条件路径。已发布的独立身份验证价格为0.15美元，而已发布的0.33美元KYC捆绑包结合了身份验证、被动活体检测、人脸匹配和IP分析。

定价页面列出了当前的模块费率，免费套餐为每月500次免费验证。这些产品结果应作为后端自有策略和客户状态的输入，而非取代它们。

常见问题

什么是身份验证API？

它是一个编程接口，用于收集或提交身份证据，并接收关于证据有效性和申请人与所声称身份关联的结构化结果。

身份验证API与KYC API相同吗？

不一定。身份验证侧重于身份证据和持有者关联。KYC API还可能包括筛选、客户风险、工作流、审查、记录和持续刷新。

身份验证应该从前端运行吗？

捕获界面可以在前端运行，但永久凭据、会话创建、最终结果检索、策略决策和客户状态更改属于受信任的后端。

为什么需要网络钩子？

许多检查和审查都是异步的。网络钩子通知应用程序更改，而检索端点提供规范状态以进行协调。

如何处理重复的网络钩子？

验证每个事件，存储其标识符，幂等地处理它，防止旧状态覆盖新终止状态，并在必要时检索规范尝试。

沙盒应该包含什么？

它应该重现生产契约，并提供成功、重试、拒绝、审查、过期、技术错误、重复事件、延迟事件和相关原因代码的确定性案例。

API能让公司合规吗？

不能。API可以提供证据和工作流结果。组织仍负责法律分析、策略、客户决策、例外情况、记录、隐私和持续控制。

主要参考资料

• NIST SP 800-63A-4：身份证明和注册
• OWASP API安全十大风险 — 2023
• RFC 9110：HTTP语义
• RFC 9421：HTTP消息签名
• RFC 9457：HTTP API问题详情

强大的身份验证集成明确了每个信任边界：谁创建尝试、如何捕获证据、哪个结果是规范的、如何验证事件、每个原因的含义以及哪个系统拥有最终客户决策。