eID API 集成指南：模式、代码与安全
以代码为先的指南，介绍如何通过 eID API 集成国家 eID：重定向、应用推送、二维码、NFC 卡片和 OpenID4VP 流程，需要自行构建的部分、结果字段、备用方案和安全检查清单。
要点
eID API 让您的注册流程请求某个国家电子身份（eID）方案对用户进行认证，并返回经签名的身份属性。每个方案都采用以下五种模式之一：浏览器重定向、带比对码的应用推送、二维码或应用唤起、通过近场通信（NFC）读取芯片卡，或通过 OpenID for Verifiable Presentations（OpenID4VP）进行的欧盟数字身份（EUDI）钱包出示。[2][6][8][14]
- 您仍需校验签名和保证级别。
- 大多数方案在首次调用前需要签订合同、取得证书或通过经认证的中介机构。[12][13][15]
本指南以代码为先，面向在用户开户流程中接入国家 eID 的工程师。
eID API 的工作原理：五种交互模式
您的系统是依赖方（RP）。它从不接触凭证本身，只接收关于该用户的签名应答。
| 模式 | 用户操作 | 后端如何获得结果 | 示例 |
|---|---|---|---|
| 重定向（OpenID Connect，OIDC） | 离开您的页面，进入方案的登录页，完成登录后返回 | 授权码，用于换取经签名的 ID 令牌 | ID Austria，其 OIDC 登录仅支持授权码流程[6] |
| 带比对码的应用推送 | 输入个人代码，将屏幕上的比对码与应用中的比对码进行核对，在应用中输入 PIN | 等待或轮询签名结果 | Smart-ID、Mobile-ID[10][20] |
| 二维码或应用唤起 | 在电脑上扫描动态二维码，或在同一部手机上打开应用 | 轮询方案直至订单完成 | 瑞典 BankID[8] |
| 芯片卡与 NFC | 将芯片卡贴近手机，输入卡片 PIN | 由 eID 服务器读取芯片并返回属性 | 德国 eID 卡[14] |
| 钱包出示（OpenID4VP） | 在钱包应用中确认要共享的属性 | 经签名、可选择性披露的属性的出示 | EUDI 钱包[2] |
部分方案位于公共网关之后：爱沙尼亚的 TARA 是一个授权码网关，前端对接身份证、Smart-ID、Mobile-ID 和欧盟 eID。[7]各方案采用哪种模式，请参阅各国 eID 方案。
您需要构建的部分与服务商处理的部分
先有准入，后写代码。在丹麦，每个服务提供商都必须通过经认证的 MitID 中介接入。[12]在瑞典，您需要从银行或经销商处购买 BankID，并申请依赖方证书。[15]在德国，您可以自建 eID 服务器，也可以使用托管 eID 服务并持有自己的证书，或者使用身份识别服务而自身不持有证书。[13]对于 EUDI 钱包，依赖方必须在其设立地所在的成员国进行注册。[1]
| 层级 | 直接对接，逐个方案 | 通过一个 eID API |
|---|---|---|
| 合同与证书 | 每个方案一份，按各方案的周期续期 | 由服务商持有；您只持有一份合同 |
| 协议代码 | OIDC、轮询 API、eID 服务器、OpenID4VP | 一个会话 API 和一种结果格式 |
| 界面 | 选择器、二维码、比对码、错误提示，每个方案各一套 | 托管流程或 SDK |
| 签名校验 | 由您负责，按各方案的密钥和格式处理 | 由服务商完成，以判定结果形式返回 |
| 保证级别 | 由您请求并校验 | 记录在结果中；策略仍由您设定 |
| 无 eID 用户的备用方案 | 第二家供应商或人工流程 | 同一流程中的证件验证路径 |
| 开户决策 | 由您负责 | 仍由您负责 |
大多数北欧和波罗的海方案都有经认证的中介。若只对接一个方案且业务量大，可直接对接；若用户来自多个国家，可使用一个 API。
重定向流程分步说明
这是 OIDC 授权码流程。您的后端将浏览器重定向出去，并附带随机的 state 和 nonce，然后用返回的授权码换取 ID 令牌并对其进行校验。
用户使用 eID 登录
校验 state、nonce、签名、acr
这是一种重定向登录。中介和网关会在第 2 步中增加跳转环节，但不会给您增加新的步骤。
第 5 步之后的校验最为关键。根据 Digdir 的 ID-porten 文档，客户端“必须验证安全级别（acr）足够高”。[5]请将 acr 理解为该方案声明的保证级别（LoA），并拒绝任何低于您政策要求的级别。
带比对码的应用推送流程
Smart-ID 和 Mobile-ID 全程不离开您的页面。用户输入个人身份识别码（Mobile-ID 还要求输入手机号码），您的页面显示一个简短比对码，同一比对码会出现在应用中。仅当两个比对码一致时，用户才在手机上输入 PIN 进行确认。[20]Smart-ID 还可以显示三个比对码，让用户选出正确的那一个。[10]
选择验证方式
使用您已在使用的电子身份登录。
Smart-ID
改用身份证件
1用户从您接受的 eID 中选择一种。
核对代码
4821
同一比对码会显示在您的 Smart-ID 应用中。
2您的验证页面会在当前使用的设备上显示比对码。同一比对码会出现在应用中。
输入您的 PIN
仅在比对码与屏幕上显示的比对码一致时输入。
3用户在应用中输入 PIN，绝不在您的页面上输入。
您已通过验证
- 全名已共享
- 出生日期已共享
- 个人代码已共享
- 地址未共享
4已签名的属性到达您的后端。
瑞典 BankID 的流程结构相同，只是用二维码代替手动输入的代码：用户在同一设备上通过 autostart token 打开应用，或扫描另一设备上显示的动态二维码，您的后端轮询 /collect，直到订单完成。完成的订单包含个人号码、姓名、名字和姓氏，以及设备、签名和可选的风险字段。[8] Smart-ID+ 将 Smart-ID 迁移到这一模式（桌面端使用动态二维码，移动端使用应用间跳转），用户不再需要在网站上输入个人代码。[11]
应用显示相同的比对码；用户输入 PIN
Smart-ID 或 Mobile-ID 登录，按用户看到的顺序：个人代码，您页面上的比对码，应用中的相同比对码，然后是 PIN。[20] 在 BankID 二维码方式中，第 1 步取消，第 2 步显示二维码。
芯片卡与 NFC，以及通过 OpenID4VP 使用 EUDI 钱包
使用德国电子身份证时，用户在 AusweisApp 中将卡片贴近支持 NFC 的手机。在输入 PIN 之前，法律要求应用显示服务提供方的名称、地址和所请求的数据类别，并且只发送这些类别。[14]
根据 OpenID Foundation 的说法，OpenID4VP 1.0 是最终版规范。[16] 架构与参考框架（ARF）列出的远程出示方式包括：通过重定向和自定义 URI 方案（如 openid4vp://）使用 OpenID4VP，通过 W3C Digital Credentials API 使用 OpenID4VP，或通过该 API 使用 ISO/IEC 18013-7。[2][17] 在共享任何数据之前，钱包会验证您的访问证书，检查您请求的属性没有超出您注册的范围，并让用户逐项批准。[2] 自2028年8月11日起，人像照片才成为个人身份识别数据（PID）中的必备项，用户明确选择不提供的情况除外。[18]
- 2026年7月23日ARF v3.0.0钱包框架的当前版本。
- 2026年12月24日钱包须到位每个成员国至少提供一个钱包。
- 2027年12月24日接受依法律或合同须使用强用户认证的私营依赖方，应用户请求接受该钱包。微型和小型企业豁免。
- 2028年8月11日人像照片PID 人像照片成为必备项，用户选择不提供的除外。
影响 eID API 路线图的 EUDI 钱包关键日期。[1][2][18]
EUDI 钱包指南介绍依赖方注册以及各国的就绪情况。
错误、回退与重试
一次登录的结果为完成、取消、超时或失败。后三种情况按同样方式处理，并按国家决定下一步操作。
1提供用户所在国家的 eID
按国家设定接受列表，由用户选择。
登录已完成，签名有效且达到要求的级别
存储已签名的属性
姓名、出生日期、标识符、保证级别。
回退或拒绝
改用读取芯片的证件验证，或结束会话。
2筛查并决定
对已验证的数据应用您自己的风险规则。
切勿自动重试已取消的登录。回调须设计为幂等，这样刷新页面或重复事件不会开立两个账户。为没有 eID 的用户保留一条替代路径，通常是身份证件验证，包括 NFC 芯片读取、活体检测和人脸比对。NFC eID 验证与芯片安全一文介绍了这条路径。
eID API 集成安全检查清单
- 每次登录都生成新的
state和nonce，并拒绝与之不匹配的回调。 - 在读取任何属性之前，先验证每个令牌或结果的签名。
- 核对结果中的保证级别，而不仅是请求中的保证级别。[5]
- 如果 AMLR 的 eID 路径适用于您，应要求实质级或高级。[3]
- 切勿在您的页面上收集 eID PIN。PIN 应在该方案的应用中输入。[20]
- 跨设备登录时，优先使用二维码或应用间跳转，而不是手动输入代码。[11]
- 只请求您已登记且确实需要的属性。[1]
- 在信任结果之前，先验证 webhook 的签名和时间戳。
法律依据是《反洗钱条例》(AMLR)，自2027年7月10日起适用。其第22(6)(b)条允许使用“符合条例(EU) No 910/2014关于‘实质’或‘高’保证级别要求的电子识别手段”。[3]并非所有方案都已通报：MitID 在欧盟已通报方案清单上，Smart-ID 不在其中。[4]
注意
ARF 警告，跨设备的自定义 URI 流程“容易受到网络钓鱼和中继攻击”，并且不建议在跨设备出示中使用自定义 URI 方案。[2]据 Computer Sweden 报道，警方在2019年7月表示，引入二维码后，BankID 电话诈骗下降了90%。[9]
Didit 如何帮助您完成 eID API 集成
Didit 通过一个会话 API 提供五种已上线的 eID（MitID、BankID Sweden、Finnish Trust Network、Smart-ID 和 Mobile-ID，覆盖七个国家），并在同一工作流中提供证件验证路径。更多方案已列入 Didit 的路线图，EUDI 钱包的接入即将推出。Didit 从不索取 PIN。详情请参阅数字身份钱包页面和钱包文档。[19]
按国家开启已上线的 eID
在控制台中：依次进入工作流 (Workflows)、ID Verification 步骤、国家 (Countries)、“可接受的钱包 (Wallets accepted)”。通过 API 操作时，ID Verification 功能 (OCR) 接受一个 methods 对象，以 ISO 3166-1 alpha-3 国家代码为键，随 POST /v3/workflows/ 一起发送。文档中丹麦的示例片段如下：[21]
{ "feature": "OCR", "config": { "methods": { "DNK": { "document": { "enabled": true }, "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" } } } } }
爱沙尼亚的示例如下，同时接受两种基于手机的 eID：[20]
{ "EST": { "document": { "enabled": true }, "wallet": { "enabled": true, "providers": ["smart_id", "mobile_id"], "on_failure": "fallback_to_document" } } }
providers 是接受列表，不是优先级排序。on_failure 的取值为 fallback_to_document 或 decline。如果某个钱包在您的环境中不可用，整个保存操作都会被拒绝，因此请先查看目录。[21]
截图待补：console-wallets-accepted
在 Didit 控制台中为某一国家选择可接受的 eID。
创建会话并读取结果
使用您的 workflow_id（以及可选的 vendor_data 和 callback）调用 POST /v3/session/，将返回 session_id、url 和 session_token。打开该 URL 或使用 SDK。[24] 结果通过 webhook 或 GET /v3/session/{id}/decision/ 返回，其中包含 verification_method: "wallet"、assurance: "cryptographic" 以及一个 wallet_verification 对象。[19]
| 字段 | 示例 | 含义 |
|---|---|---|
provider | mitid | 用户选择的 eID |
issuing_authority | 丹麦数字政府局 | 身份背后的担保方 |
issuing_country | DNK | 表示身份验证途径，而非国籍 |
level_of_assurance | substantial | 该方案声明的级别 |
signature_valid | true | 已签名的断言验证通过 |
attributes | full_name、date_of_birth、cpr_alias | 已验证的声明，名称因 eID 而异 |
portrait、face_match_score | null | 目前上线的 eID 均不共享人像照片 |
认证等级低于所要求的等级时，登录失败。仅对已完成的登录计费。[19] 价格：MitID、Finnish Trust Network $0.25；BankID Sweden、Smart-ID、Mobile-ID $0.20。
Webhook 与沙盒
使用目标端密钥验证 X-Signature-V2，拒绝早于 300 秒的 X-Timestamp，并以 event_id 作为幂等键；投递失败最多重试两次。[22] 沙盒应用可启用所有钱包，无需真实登录即可批准，并提供 wallet_cancelled、wallet_timeout 和 wallet_provider_error，用于测试您的备用流程。[23]
| eID | 国家 | Didit 级别 | Didit 状态 |
|---|---|---|---|
| MitID | 丹麦 | 实质级 | 已上线 |
| 瑞典 BankID | 瑞典 | 实质级 | 已上线 |
| Finnish Trust Network | 芬兰 | 实质级 | 已上线 |
| Smart-ID | 爱沙尼亚、拉脱维亚、立陶宛、比利时 | 高 | 已上线 |
| Mobile-ID | 爱沙尼亚、立陶宛 | 高 | 已上线 |
| 挪威 BankID | 挪威 | 未设定 | 即将推出 |
| Freja eID | 瑞典 | 未设定 | 即将推出 |
| itsme | 比利时 | 未设定 | 即将推出 |
| iDIN | 荷兰 | 未设定 | 即将推出 |
| 德国 eID 身份证 | 德国 | 未设定 | 即将推出 |
| FranceConnect | 法国 | 未设定 | 即将推出 |
| ID Austria | 奥地利 | 未设定 | 按需提供 |
| Cl@ve | 西班牙 | 未设定 | 按需提供 |
| SPID | 意大利 | 未设定 | 按需提供 |
| Swiss E-ID | 瑞士 | 未设定 | 按需提供 |
| EUDI 钱包 | 欧盟和欧洲经济区 | 未设定 | 即将推出 |
Didit 负责
- 方案接入、证书和签名校验
- 一个会话 API、托管流程和 SDK
- 为没有 eID 的用户提供证件验证路径，支持 NFC 芯片读取
由您负责
- 在每个国家接受哪些 eID
- 您的政策要求的保证级别
- 开户决定和相应责任
要点
- 每种 eID 都采用以下五种模式之一：重定向、带比对码的应用推送、二维码或应用唤起、芯片卡与 NFC，或 OpenID4VP。
- 接入是第一步：通过中介、合同、证书或注册。
- 对每个结果都要校验签名和保证级别。
- 依法律或合同要求必须使用强用户认证的私营依赖方，须在 2027年12月24日 前应用户请求接受 EUDI 钱包（微型和小型企业豁免）。
常见问题
什么是 eID API？
它是一个接口，让您的应用请求某个国家电子身份方案，或接入多个方案的服务商，对个人进行身份认证并返回经签名的身份属性。您仍需校验其返回结果中的签名和保证级别。
每个 eID 方案都需要单独集成吗？
如果直接对接，是的：每个方案都有各自的合同、证书和协议。在丹麦，您必须使用经认证的 MitID 中介，而瑞典的 BankID 需向银行或经销商购买。[12][15] 单一的 eID API 将这些差异隐藏在一个会话和一种结果格式之后。
国家 eID 使用哪种协议？
许多方案使用 OpenID Connect，通常通过 ID-porten 或 TARA 等网关接入。[5][7] 另一些方案使用各自的轮询 API（BankID Sweden、Smart-ID），或使用读取芯片卡的 eID 服务器（德国）。[8][13] EUDI Wallet 使用 OpenID4VP 或 ISO/IEC 18013-7。[2]
eID 登录会返回哪些数据？
这取决于具体方案。BankID Sweden 返回个人身份号码、姓名、名字和姓氏。[8]德国电子身份证只发送服务提供方证书中列明的数据类别（§ 18(5)），不发送该卡的身份证号码，因为 § 18(3) 的清单不包含这一项。[14]
我如何强制执行保证级别？
请求您所需的保证级别，并核对结果中声明的级别，例如 OIDC 中的 acr 声明。ID-porten 指出，客户端必须验证安全级别是否足够高。[5] 凡低于您政策要求的级别，一律视为不足，不得开立账户。
用户没有 eID 或中途取消时，应如何处理？
按国家决定采用备用方案还是拒绝。不要自动重试已取消的登录。
没有真实用户时，如何测试 eID 集成？
在服务商的沙盒中模拟批准、取消和超时。模拟批准不能证明真实身份可以登录：上线前须进行经授权的真机测试。[20]
企业何时必须接受 EUDI 钱包？
依法律或合同须使用强用户认证的私营依赖方，必须在 2027年12月24日前应用户要求接受 EUDI 钱包。微型企业和小型企业豁免。[1]
来源
- Regulation (EU) 2024/1183 (eIDAS 2)，EUR-Lex，2024年4月30日《欧盟官方公报》，第5a条、第5b条和第5f条。
- 架构与参考框架 v3.0.0，欧盟委员会 EUDI Wallet 项目，2026年7月23日发布，第4.4.3、5.7.1和6.6.3节。
- (EU) 2024/1624号条例 (AMLR)，EUR-Lex，第22(6)条。
- eIDAS 下已预通报和已通报的 eID 方案概览，欧盟委员会，2026年10月5日查阅。
- ID-porten ID 令牌，挪威数字化署 (Digdir)。
- Anbindung mit OpenID Connect，ID Austria 开发者文档。
- TARA 技术规范，爱沙尼亚信息系统管理局 (RIA)。
- 认证与签名：collect，BankID 开发者文档。
- QR-koden gjorde susen: BankID-bedrägerierna ned med 90 procent，Computer Sweden，2019年7月3日（二手来源）。
- 为什么我有时看到一个确认码，有时看到三个，Smart-ID。
- 新版 Smart-ID 如何保护我免受欺诈，Smart-ID。
- MitID 中介，丹麦数字政府署。
- 成为服务提供方，AusweisApp，德国联邦政府。
- 《护照和身份证法》（PAuswG）第18条，Gesetze im Internet。
- 将您的企业接入 BankID，BankID。
- OpenID for Verifiable Presentations 1.0 最终规范获批，OpenID Foundation。
- 数字凭证，W3C。
- 委员会实施条例 (EU) 2026/1731，EUR-Lex，自2028年8月11日起 PID 中包含人像照片。
- 数字身份钱包，Didit 文档。
- Smart-ID 和 Mobile-ID 集成，Didit 文档。
- 工作流功能配置，Didit 文档。
- Webhooks，Didit 文档。
- 沙盒与测试数据，Didit 文档。
- 快速入门，Didit 文档。
在 eID 验证页面查看每一种国家 eID、其等级及其状态。