企业 APP 接入专题

国家网络身份认证公共服务接入讲解

接入流程与实务答疑

注册申请材料填报技术对接联调上线

接入初衷

甬易数为何接入国家身份认证平台

合规保障

在满足实名要求的同时，遵循《个人信息保护法》“最小必要”原则。
数据安全

减少身份证等敏感信息在自有服务器的明文留存，降低隐私泄露风险。
成本优化

减少第三方身份核验及敏感数据存储支出，降低平台运营成本。
用户体验

简化认证流程，降低操作门槛，减轻用户对隐私泄露的顾虑。

甬易数研发成果

从甬易数研发到 Flutter 认证插件

w_client_flutter 由赖海波在甬易数研发中衍生开发，基于国家网络身份认证平台 iOS、Android SDK。

统一两端认证流程

专利申请将认证发起、完成后返回应用及结果获取统一为完整流程，减少 iOS、Android 分别适配的复杂度。

补足 Flutter 认证适配能力

提供可复用的认证入口与结果反馈，兼顾取消、超时等情况，减少重复开发，让团队更专注业务体验。

沉淀甬易数研发价值

甬易数对跨平台兼容与认证体验的扎实投入，沉淀为独立插件和专利申请成果，夯实产品基础，也为后续项目留下可复用的技术积累。

项目仓库 · NeverOvO/w_client_flutter ↗

发明专利申请公开文本

CN 121842676 A

1 / 9

一种基于国家网络身份认证APP的跨平台身份认证接口抽象方法及系统

接入路径

接入全流程总览

企业办理事项与平台审批节点

01

注册与准备
- 需求确认
- 平台注册
- 申请材料准备
明确场景，备齐材料
02

申请与审批
- 服务申请与接入初审
- 需求、技术、合规评估
- 资料审批
- 接入审批
提交申请，完成审批
03

技术接入与联调
- 发起联调与证书制作
- 安全接入与前后端对接
- 联调测试
完成对接，验证链路
04

生产开通
- 生产开通准备
- 开通生产线
- 确认开通正式服务
确认开通，投入使用

接入准备

认证前的必要资质确认

营业执照

确认已取得营业执照，备齐企业主体资质材料。
软件著作权

准备拟接入 APP 对应的软件著作权登记证书。
APP 上架

确认 APP 已正式上架，可在应用商店检索到应用详情页。

机构信息填报

机构简介与信息返回范围

* 机构简介

1、机构基本情况（必填）：机构性质，持牌照情况，为个人/企业提供什么服务等。

2、主要应用客户端情况（必填）：如，机构旗下有三款 App（**甲、**乙、**丙），一个官方网站（**网上系统），小程序（ABC、DEF），线下网点等。

3、技术能力（可选）：如拥有自主研发能力，研发团队人数等。

4、安全管理（可选）：如法规方面，技术方面（如等保三级）。

5、其他需要介绍的情况（可选）。

Android 与 iOS 接入

服务申请

应用信息

* 应用名称

示例游戏 APP

* 业务办理联系人

张某

* 电话

填写业务联系人电话

* 应用涉及领域

游戏

应用类型

* 程序包名

com.example.game

* 预计上线时间

填写预计接入上线日期

APK包签名V2

填写发布签名证书 SHA-1

APK包签名V3

按实际签名情况填写

* 版权方

示例科技有限公司

* 开发方

示例科技有限公司

* 开发联系人

李某

* 开发联系人电话

填写技术联系人电话

业务类型及认证模式

同一模式可同时选择两种返回信息，建议按需选择其中一项；不同模式分别填写服务量。

服务量预估

业务类型	认证模式	预估服务并发量（TPS）	预估日服务总量（次/日）
网证认证	网证（R01）	5	1000
网证认证	网证+口令（R02）	5	1000
网证认证	网证+人像（R03）	5	1000
网证认证	网证+口令+人像（R04）	5	1000
请先选择认证模式

需求性材料

接入需求说明

* 接入需求说明

1、应用基本情况（必填）：如该App是本机构面向个人用户的主要移动客户端，提供**、**等服务，App中的**、**、**等场景需要对用户的身份进行认证。App用户数量为2亿，日活跃数为8000万，身份认证需求量为50万/天。

2、安全措施（必填）：如该应用及后台系统按照网络安全等级保护定级要求进行安全防护，符合 GB/T22239 第二级安全保护能力的要求；个人信息授权使用符合 GB/T35273、GB/T42573、GB/T45574 中相关要求。

3、本次申请（必填）：如App的注册、登录场景使用网证服务模式；身份认证并绑定网络身份场景使用网证+口令+返信息（部分姓名）服务模式；修改个人信息场景使用网证+人像服务模式等。

4、如有其他情况需要说明写在此处（可选，如：**小程序没有申请软著，特此说明）。

1、应用基本情况：“示例游戏 APP”由示例科技有限公司运营，面向个人用户提供账号注册、登录及在线游戏服务。在实名注册、账号身份绑定及异常登录核验时使用身份认证。现有用户［实际人数］人，日活跃用户［实际人数］人，预计每日认证［预计次数］次。

2、安全措施（方案一：已完成等保）：本应用及后台系统已按第［实际等级］级完成定级、备案和测评，测评结论符合相应等级要求，备案编号［编号］，测评报告日期［日期］。依据 GB/T 22239-2019 落实访问控制、网络隔离、入侵防护、安全审计、漏洞修复和备份恢复；按最小必要原则及用户授权处理个人信息，采用加密传输、敏感信息加密存储、密钥分离管理和分级授权，定期开展安全检查与应急演练。

安全措施（方案二：小微企业使用商业云、尚未完成等保）：本公司为民营小微企业，本应用及后台部署于［阿里云／腾讯云，填写实际使用方及地域］，业务系统尚未完成等保备案和测评。已通过私有网络及安全组限制访问，仅开放必要端口，数据库不对公网开放；管理员启用多因素认证并按最小权限授权；启用主机防护、漏洞扫描及异常登录告警，及时安装补丁；接口使用 HTTPS，敏感数据加密存储，密钥单独管理；保留访问与操作日志，定期备份并验证恢复，由专人处理安全告警。个人信息按必要范围及用户授权使用。云平台资质不等同于本系统通过等保，后续按定级及接入要求落实相关工作。

3、本次申请：拟在上述认证场景采用“网证+口令”模式（R02），申请返回年龄段标识（NL），用于区分成年与未成年用户、实施相应游戏服务限制。本例不申请姓名、身份证号、性别及人像信息，认证模式和返回字段以审批结果为准。

4、其他情况：本应用版权方与申请主体一致，软件著作权证明随申请材料提交；本次仅申请 APP 接入，不涉及小程序。

游戏应用范文 · 安全措施二选一0/1000

填写范围与要求

第 1—3 点必填

说明应用用途、认证场景、用户规模与调用量；写明安全措施，以及拟申请的认证模式和返回字段用途。第 4 点按实际情况补充。

安全措施按实际状态选择

方案一适用于已完成相应等保备案、测评且结论符合要求的系统。方案二只描述商业云上已经启用的措施，未启用的内容应删除或如实标明计划。

使用商业云仍需落实自身责任

企业规模小、使用阿里云或腾讯云，不等于免除业务系统的等保责任。尚未完成等保时应如实说明，并按接入审核要求补齐材料。

联调准备

联调接入方式差异

接入方式设备平台（安全设备）安全接入平台

安全接入平台：无需自购专用设备

本单位后端 → 安全接入平台 → 国家公共服务平台

主要差异

由平台提供认证业务转发服务，机构无需自行部署安全接入设备。

优点

省去专用设备采购、上架和日常维护，前期准备较轻，适合并发需求在平台限额内的业务。

需要承担

依赖平台服务及网络连通性；仍需完成证书申请、密钥管理、接口对接和异常处理。

安全接入平台申请

账号、密钥与证书准备

01 领取账号

联系技术支持获取安全接入平台账号，首次登录后修改登录密码；核对机构信息及业务站点号。

技术支持

领取账号

核对机构与站点

1 / 5

后端对接 · Java

从认证密文到可信业务结果

01 前端回传，后端接棒

用户在国家网络身份认证 APP 完成操作后，客户端将 getAuthResult 返回的认证密文交给 Java 后端。后端核对登录会话与本次业务流水，继续使用同一个 bizSeq，bizSeq可由前端使用UUID生成32位随机字符。

客户端 SDK

认证密文

Java 后端

bizSeq · idCardAuthData · certPwdData（R02）

客户端回跳成功，只说明已取得后续请求材料；最终认证结论由后端核验。

Java核心逻辑 · 业务封装示意01 / 05

// 校验流水属于当前会话，且未过期、未完成
var pending = requirePending(session, input.bizSeq());
String bizSeq = pending.bizSeq();

// 保留 SDK 返回的密文，不接收明文口令
requireNotBlank(input.idCardAuthData());
requireNotBlank(input.certPwdData());

流水一致

前端拉起、后端请求和平台响应使用同一 bizSeq，不在后端重新生成。

02 组装业务包，用机构私钥签名

以游戏应用 R02+返年龄段为例。业务包填写应用名、站点号、时间戳、原 bizSeq、SDK 密文及返信息加密证书 cert；再封装转发地址，对 requestPackage 做 SM2 签名。

业务请求包

机构鉴权私钥

requestSign

requestPackage = customerNo + forwardUrl + bizPackage

mode、站点号、证书与目标地址从后端配置读取；NL 按获批权限返回。

Java核心逻辑 · 业务封装示意02 / 05

var biz = buildR02Package(config, pending, input);
var pkg = new SARequestPackageVO();
pkg.setCustomerNo(config.customerNo());
pkg.setForwardUrl(config.authForwardUrl());
pkg.setBizPackage(biz);
var req = new SARequestVO();
req.setRequestPackage(pkg);
req.setRequestSign(crypto.sm2Sign(
    signPrivateKey, JSONUtil.toJson(pkg)));

签名私钥留在后端

签名原文与发送的 JSON 必须一致；使用紧凑 JSON，签名后不再改包。

03 安全接入平台完成转发

Java 后端通过 HTTPS 调用安全接入平台。平台校验机构签名，并完成公共服务接口要求的签名与转发；国家网络身份认证公共服务平台处理业务认证。

Java 后端

安全接入平台

公共服务平台

HTTPS 请求 → 机构鉴权 → 业务认证 → 原路响应

安全接入平台负责安全转发，应用后端负责解释认证结果并执行自己的业务规则。

Java核心逻辑 · 业务封装示意03 / 05

// 初始化时已配置平台地址、验签公钥等
// 该工具方法同时执行平台响应验签
String responseJson = SecureAccess.unified_auth(
    bizSeq, JSONUtil.toJson(req));

// 空响应、通信或验签失败，终止业务放行
requireNotBlank(responseJson);

两层签名分工

机构请求使用 SM2 P1 签名；面向公共服务接口的 PKCS#7 签名由安全接入平台处理。

04 验签通过后，还要检查两层结果

工具先用平台验签公钥核验 responseSign。随后判断转发层 platformCode 为 200，再检查业务层 resultCode 为 C0000000，并核对响应 bizSeq 与原流水一致。

响应验签通过

认证 C0000000

验签有效 + 转发成功 + 认证成功 + 流水匹配

HTTP 200 或 platformCode = 200 均不能单独作为认证成功依据；失败时不进入解密与业务放行。

Java核心逻辑 · 业务封装示意04 / 05

// responseJson 已通过工具的 responseSign 验签
var response = parsePlatformResponse(responseJson);
require("200".equals(response.platformCode()));

var auth = readAuthResult(response.platformData());
require("C0000000".equals(auth.resultCode()));
require(bizSeq.equals(auth.bizSeq()));
requireNotNull(auth.data());

明确成功条件

解析函数按联调确认的返回层级读取业务结果，缺字段或异常状态均终止。

05 解密获批信息，再更新游戏业务

认证成功后，使用本次 cert 对应的返信息解密私钥打开 encryptedIdInfo。只读取获批的年龄段 NL，将核验结果关联当前账号，按业务规则更新年龄适配与功能权限。

encryptedIdInfo

返信息解密私钥

账号业务结果

加密身份信息 → 数字信封解密 → NL → 业务规则

返回客户端的是必要的业务结果；私钥、原始身份密文及完整解密内容不进入前端或普通日志。

Java核心逻辑 · 业务封装示意05 / 05

String encrypted = auth.data().encryptedIdInfo();
requireNotBlank(encrypted);
var info = decryptEnvelope(encrypted, returnInfoPrivateKey);
String ageBand = requireApprovedAgeBand(info, "NL");

// 原子完成流水，重复回调不重复更新
return completeOnce(pending, () ->
    gamePolicy.applyAgeBand(session.accountId(), ageBand));

两把私钥用途不同

机构鉴权私钥用于请求签名；返信息私钥与请求中的 cert 配对，用于解密返回信息。

1 / 5

测试联调 · 工具使用

注册测试账号

01

注册机构下的测试账号

测试数据录入.apk

安装并打开工具，输入机构 ID，按提示完成当前机构下的测试账号注册。

02

国家网络身份认证测试App_Android_V1.2.39.5.apk或iOS包

安装并打开国家网络身份认证测试 App，登录刚注册的测试账号，再进行测试线的认证联调。

前端对接 · 跨平台流程

从业务 App 出发，带回认证材料

AndroidIntent · SDK 回调iOSUniversal Links · 异步回跳HarmonyOSApp Linking · 两种接收方式Flutter统一 Android / iOS 入口

01 配置 SDK 与包可见性

引入 WClient.aar，在 Manifest 声明国家认证 APP 的查询包名；使用与接入申请一致的应用配置。调用时需要有效的 Activity。

工程配置

业务 App

原生 SDK

WClient.aar

可查询

国家认证 App

构建时准备 · Android 6.0 及以上（手册要求）

Java关键入口与逻辑示意

<queries>
  <package android:name=
    "cn.cyberIdentity.certification" />
</queries>

先确认能找到目标 APP

安装检查、拉起异常或用户取消都应恢复页面操作状态，不把失败当作认证完成。

02 同一业务流水贯穿前后端

准备 orgID、当前 Android 的 appID 与 32 位 bizSeq，并保留本次会话。以 R02 为例，type 使用整数 1，表示需要网证及口令材料。

认证发起

业务 App

业务参数

WParams

保留 bizSeq

当前会话

R01 / R03 → type 0　　R02 / R04 → type 1

Java关键入口与逻辑示意

WParams params = new WParams(
    orgID, androidAppID, bizSeq, 1, null);
// 普通 App 场景不填小程序 extras
// orgID、appID 按本应用开通信息填写

type 不是 R02 字符串

type 只决定是否获取口令材料；R03 / R04 所需人脸材料另按业务接口准备。

03 SDK 通过 Intent 拉起认证 APP

调用 getAuthResult 并登记 OnCallBack。SDK 使用 Intent 打开国家认证 APP，用户在该 APP 内完成所需操作；业务 App 保持等待。

等待中

业务 App

跨应用拉起

Intent

用户操作

国家认证 App

getAuthResult → Intent → 国家认证 APP

Java关键入口与逻辑示意

WAuthService service =
    new WAuthService(activity, params);
service.getAuthResult(new OnCallBack() {
  public void onResult(Result result) {
    handleResult(result);
  }
});

一次操作对应一次等待

等待期间防止重复点击；材料回传之前，不提前显示“认证通过”。

04 在 onResult 中读取认证材料

先检查 resultCode 是否为 C0000000，再从 getResultData() 读取 idCardAuthData；R02 还必须取得 certPwdData。材料不完整时停止提交。

返回材料

国家认证 App

SDK 回调

onResult

收到密文

业务 App

读取的是认证请求材料，尚未得到后端业务结论

Java关键入口与逻辑示意

if (!"C0000000".equals(result.getResultCode())) {
  showFailure(result.getResultDesc());
  return;
}
var data = result.getResultData();
requireR02Materials(data);

判断 resultCode

成功码与结果描述分开；resultDesc 用于说明原因，不能拿来与 C0000000 比较。

05 材料交给后端，页面等待最终结论

将原 bizSeq、idCardAuthData 与 R02 所需 certPwdData 通过本单位业务接口提交后端。后端完成签名转发、验签、认证判断与按需解密，再返回业务结果。

提交密文

业务 App

核验与解密

业务后端

更新状态

当前页面

衔接后端流程 · 失败时不更新为认证通过

业务流程关键入口与逻辑示意

// 业务职责示意，非官方 SDK 方法
submitToBackend(
  bizSeq, idCardAuthData, certPwdData
);
// 后端确认后，再更新页面认证状态

密文留给后端核验

姓名、年龄段 NL 等返信息由后端按获批权限处理；SDK 的 C0000000 仅表示本阶段材料获取成功。

01 先配置认证结束后的返回入口

集成 WClientSDK.framework 并设置 Embed & Sign。优先配置 Universal Links 返回地址；需要 URL Scheme 时，按手册配置 ncidas + orgID + appID。

原生工程

业务 App

SDK 依赖

Framework

Links / Scheme

回跳入口

返回入口必须与所采用的方式对应

Objective-C关键入口与逻辑示意

// Universal Links：配置本应用的链接关联
// 调用时通过 uLink 传入返回地址
// URL Scheme：ncidas + orgID + appID
// 安装检查白名单：cyberidentity

拉起与回跳分开配置

拉起国家认证 APP 使用 Universal Links；认证结束后的回跳支持 Universal Links 或 URL Scheme。

02 业务参数中带上返回地址

orgID、iOS appID 和 bizSeq 与本次会话对应；R02 的 type 使用字符串 "1"。使用 Universal Links 回跳时，uLink 填本应用配置的返回链接。

原 bizSeq

当前会话

业务参数

parameters

本应用入口

uLink

uLink 未填时，按手册使用 URL Scheme 返回

Objective-C关键入口与逻辑示意

NSDictionary *params = @{
  @"orgID": orgID, @"appID": iosAppID,
  @"bizSeq": bizSeq, @"type": @"1",
  @"uLink": returnUniversalLink
};

不要把 appID 跨端混用

Android 与 iOS 按各自获批的应用配置填写；bizSeq 在这一笔业务中保持一致。

03 同步返回仅反映调用阶段状态

调用 getAuthResult 通过 Universal Links 拉起国家认证 APP。方法立即返回同步状态字典；认证材料需要等待用户完成操作后的异步回跳。

调用 SDK

业务 App

打开目标

Universal Links

用户操作

国家认证 App

Objective-C关键入口与逻辑示意

WClientSDK *sdk = [[WClientSDK alloc] init];
NSDictionary *launchStatus =
    [sdk getAuthResult:params];
// 检查启动阶段状态，随后等待异步回跳
// 不从 launchStatus 读取认证密文

两次返回，职责不同

同步返回用于处理本次调用状态；异步返回携带 resultCode 和认证材料。

04 在应用生命周期入口接收回跳

按宿主配置从 SceneDelegate 或 AppDelegate 接收 Universal Link／URL Scheme。核对回跳入口与来源字段，再解析 resultCode 和两项 R02 密文。

返回链接

国家认证 App

接收 URL

Scene / AppDelegate

解析材料

业务 App

链接参数可能包含 Base64 的 =，不可逐个等号拆散

Objective-C关键入口与逻辑示意

// Universal Links：continueUserActivity
// URL Scheme：openURLContexts / openURL
NSDictionary *data = parseAuthReturn(url);
// 每个键值对仅按第一个 = 分割，再解码
requireSuccessAndR02Materials(data);

来源字段不替代后端验签

回跳入口、来源和等待状态均需检查；最终仍由后端验证材料并判断认证结果。

05 材料交给后端，页面等待最终结论

将原 bizSeq、idCardAuthData 与 R02 所需 certPwdData 通过本单位业务接口提交后端。后端完成签名转发、验签、认证判断与按需解密，再返回业务结果。

提交密文

业务 App

核验与解密

业务后端

更新状态

当前页面

衔接后端流程 · 失败时不更新为认证通过

业务流程关键入口与逻辑示意

// 业务职责示意，非官方 SDK 方法
submitToBackend(
  bizSeq, idCardAuthData, certPwdData
);
// 后端确认后，再更新页面认证状态

密文留给后端核验

姓名、年龄段 NL 等返信息由后端按获批权限处理；SDK 的 C0000000 仅表示本阶段材料获取成功。

01 导入 HAR，确定结果接收方式

导入 w_auth.har，并在 module.json5 配置 querySchemes: ["https"]。提前选择直接回调，或使用 App Linking 返回本应用。

鸿蒙工程

业务 App

原生 SDK

w_auth.har

回调 / Linking

接收方式

HarmonyOS 5.0 及以上（手册要求）

ArkTS关键入口与逻辑示意

// oh-package.json5：声明本地 HAR 依赖
"w_auth": "file:./libs/w_auth.har"

// module.json5：
"querySchemes": ["https"]

两种方式都由 SDK 接收

linking 留空走直接回调；填写本应用链接则走 App Linking 回跳。

02 用 linking 参数选择返回路径

准备 orgID、鸿蒙 appID、bizSeq 与字符串 type。R02 使用 "1"；填写 linking 时，需要完成本应用的 App Linking 配置。

保留流水

当前会话

type 为 1

JSON 参数

选择返回方式

linking

不填 linking → 直接回调　　填写 linking → 链接回跳

ArkTS关键入口与逻辑示意

const params = {
  orgID: orgID, appID: harmonyAppID,
  bizSeq: bizSeq, type: "1",
  linking: returnLink
};
const json = JSON.stringify(params);

返回路径在发起前确定

使用链接回跳时，还需在 Ability 生命周期中把接收到的 Want 交给 SDK。

03 openWHApp 拉起，回调路径提前准备

调用 openWHApp(context, json)，SDK 通过 App Linking 打开国家认证 APP。直接回调方式应先注册监听；链接回跳方式则准备好 Ability 接收入口。

发起请求

业务 App

打开目标

App Linking

用户操作

国家认证 App

先准备接收路径，再发起跨应用调用

ArkTS关键入口与逻辑示意

const wauth = new WAuthService();
// 直接回调方式：先注册监听
wauth.setAuthCallBack(callBack);
wauth.openWHApp(context, json);
// App Linking 方式在生命周期中传入 Want

避免结果回来却无人接收

回调方式不传 Want；App Linking 方式在 onCreate / onNewWant 中转交 Want。

04 回调取出 resultData，再解析 JSON

App Linking 方式在 onCreate 和 onNewWant 中核对调用来源，再执行 setAuthCallBack(callBack, want)。OnCallBack 收到结果后先判成功，再解析 resultData。

返回结果

国家认证 App

接收数据

OnCallBack

解析 JSON

业务 App

直接回调同样进入 OnCallBack；无需转交 Want

ArkTS关键入口与逻辑示意

// 链接方式：生命周期中核对来源后
wauth.setAuthCallBack(callBack, want);

// onResult 中：
require(result.resultCode === "C0000000");
const data = JSON.parse(result.resultData);
requireR02Materials(data);

处理冷启动和已有实例

onCreate 与 onNewWant 均接入回跳处理；防止应用状态变化导致认证材料丢失。

05 材料交给后端，页面等待最终结论

将原 bizSeq、idCardAuthData 与 R02 所需 certPwdData 通过本单位业务接口提交后端。后端完成签名转发、验签、认证判断与按需解密，再返回业务结果。

提交密文

业务 App

核验与解密

业务后端

更新状态

当前页面

衔接后端流程 · 失败时不更新为认证通过

业务流程关键入口与逻辑示意

// 业务职责示意，非官方 SDK 方法
submitToBackend(
  bizSeq, idCardAuthData, certPwdData
);
// 后端确认后，再更新页面认证状态

密文留给后端核验

姓名、年龄段 NL 等返信息由后端按获批权限处理；SDK 的 C0000000 仅表示本阶段材料获取成功。

01 统一调用入口，保留两端原生配置

w_client_flutter 将 Android 与 iOS 的拉起、回跳和结果封装为 Dart 接口。宿主仍需正确配置应用标识、Android 包可见性及 iOS 回跳。

统一接口

Flutter 页面

Android / iOS

插件适配

分别完成

原生配置

本插件资料覆盖 Android / iOS，不表示支持鸿蒙

Dart关键入口与逻辑示意

import 'package:w_client_flutter/w_client_flutter.dart';

// Android / iOS 采用各自的 appID
// iOS 回跳按插件文档配置 uLink 条目

插件处理适配，宿主保留会话

业务账户、bizSeq、重复提交与页面状态由宿主和后端管理，不能假定插件自动补齐。

02 用同一份 Dart 参数发起本次认证

按当前系统选择 appID，传入本次 bizSeq 与字符串 type。以 R02 为例使用 "1"；iOS 返回地址依插件约定配置，不直接照搬原生 SDK 的默认 Scheme。

原 bizSeq

当前会话

统一参数

Dart Map

分别选择

平台 appID

原生 SDK 与 Flutter 插件的回跳配置约定不同

Dart关键入口与逻辑示意

final params = {
  "orgID": orgID,
  "appID": platformAppID,
  "bizSeq": bizSeq, "type": "1",
};

iOS 按插件文档配置

插件文档使用 CFBundleURLName = uLink 的回跳条目；宿主需保留插件正常的 URL 处理链。

03 一次 Future 等待，插件适配原生调用

调用 getAuthResult 后，插件分别走 Android Intent 或 iOS Universal Link 拉起流程。业务页面显示等待状态，让原生回跳完成这一次 Future。

await 等待

Flutter 页面

Intent / Links

原生适配层

用户操作

国家认证 App

Dart 统一入口 → 原生平台 → 国家认证 APP

Dart关键入口与逻辑示意

final result =
    await WClientFlutter.getAuthResult(params);
// 调用前禁用重复提交，异常后恢复交互
// Future 返回后继续检查材料

原生流程仍然存在

插件减少重复适配；安装状态、宿主生命周期和回跳配置仍需在两端分别验证。

04 从 Map 读取材料，避免重复消费

先检查 resultCode，再读取 idCardAuthData 与 certPwdData。以 getAuthResult 的 Future 承接一次业务；如同时监听 authResultStream，需去重，避免重复提交。

返回事件

原生回跳

统一结果

Future / Map

检查材料

Flutter 页面

同一次结果只提交一次，保留发起时的 bizSeq

Dart关键入口与逻辑示意

if (result["resultCode"] != "C0000000") {
  showFailure(result["resultDesc"]);
  return;
}
requireR02Materials(result);
// 不从回调中假定取得年龄段或姓名

插件回调成功不等于业务放行

认证密文还要交给后端；前端不保存机构鉴权私钥或返信息解密私钥。

05 材料交给后端，页面等待最终结论

将原 bizSeq、idCardAuthData 与 R02 所需 certPwdData 通过本单位业务接口提交后端。后端完成签名转发、验签、认证判断与按需解密，再返回业务结果。

提交密文

业务 App

核验与解密

业务后端

更新状态

当前页面

衔接后端流程 · 失败时不更新为认证通过

业务流程关键入口与逻辑示意

// 业务职责示意，非官方 SDK 方法
submitToBackend(
  bizSeq, idCardAuthData, certPwdData
);
// 后端确认后，再更新页面认证状态

密文留给后端核验

姓名、年龄段 NL 等返信息由后端按获批权限处理；SDK 的 C0000000 仅表示本阶段材料获取成功。

1 / 5

后端对接 · 身份信息解密

解开数字信封，读懂身份字段

先完成认证校验，再取 encryptedIdInfo

在响应验签、转发状态、认证成功码与 bizSeq 均核对通过后，从业务响应 data 中取出 encryptedIdInfo。Base64 解码后得到数字信封字节，尚未得到明文身份信息。

encryptedIdInfo

Base64 解码

数字信封字节

String encrypted = auth.data().encryptedIdInfo();
requireNotBlank(encrypted);
byte[] envelope =
    Base64.getDecoder().decode(encrypted);

Base64 解码不是解密；缺少返信息时，不能推断年龄或身份字段。

先用 SM2 私钥解出 SM4 密钥

解析信封中的接收者信息与加密密钥。使用本次请求 cert 对应的返信息解密私钥，经 SM2 解密得到本封数据使用的 SM4 对称密钥；身份内容此时仍是密文。

信封中的加密密钥

返信息 SM2 私钥

SM4 密钥

// decodeEnvelop 内部完成：
// 1. 解析 ASN.1 数字信封
// 2. 读取接收者的 encryptedKey
// 3. 转换 SM2 密文结构并解密
// 4. 得到用于解密身份内容的 SM4 密钥

不能使用机构鉴权签名私钥替代；私钥须与请求 cert 配对，编码也须符合工具要求。

再用 SM4 还原身份信息 JSON

使用解出的 SM4 密钥解密信封中的身份内容。配套 SM2Utils.decodeEnvelop 已封装前一步与本步；调用一次即可获得明文字节，再按 UTF-8 转为 JSON。

身份内容密文

SM4 解密

JSON 明文

// 一次调用：SM2 解密钥 + SM4 解内容
byte[] plain = SM2Utils.decodeEnvelop(
    returnInfoPrivateKey, envelope);
String json = new String(
    plain, StandardCharsets.UTF_8);

解密失败、证书私钥不匹配或 JSON 异常时停止处理，不记录完整明文。

按获批字段解释，再进入业务判断

解密后是 JSON 对象，只读取获批且实际返回的字段。以 {"NL":"09"} 为例，可判断年龄落在 22 至未满 45 周岁区间，无法得到准确年龄或生日。

{"NL":"09"}

NL 年龄段映射

年龄适配规则

JsonNode info = objectMapper.readTree(json);
JsonNode nl = info.get("NL");
if (nl == null || !nl.isTextual()) {
  return handleMissingAgeBand();
}
return applyAgeBand(requireKnownAgeBand(nl.asText()));

字段都是可选 String；缺失或未知编码按异常分支处理，不能默认判为成年人。

1 / 4

以下字段均为可选 String，按获批权限及实际响应使用。

字段	含义	说明
NL	年龄段标识	两位编码，如 09：22 至未满 45 周岁
XM	姓名	外国人永久居留身份证为英文姓名
XB	性别	0 未知；1 男；2 女；9 未说明
ZJHM	证件号码	完整证件号码
TMZJHM	部分证件号码	部分位置以 * 隐藏
XMSZ	姓名第一个字	保留首字，如张**
XMMZ	姓名最后一个字	保留末字，如 *三
SJHM	申领时的手机号	指申领时信息，不等同于当前验证号码
SLZJLX	最近一次申领的证件类型	三位编码，详见“证件类型”

SLZJLX 表示最近一次申领使用的证件类型，保留三位字符串编码。

编码	证件类型
001	居民身份证
003	港澳居民居住证
004	台湾居民居住证
516	港澳居民来往内地通行证
511	台湾居民来往大陆通行证
414	中国公民普通护照（华侨）
553	外国人永久居留身份证

联调验收 · 正式上线

验收通过后，确认完成并切换正式线

01

提交报文，等待验收

联调完成后，将测试联调报文发送给平台工作人员，配合完成联调验收。

02

验收通过，网页确认

平台工作人员验收通过后，在接入管理网页上确认“联调完成”。

03

切换地址，进入正式线

安全接入平台：将 forwardUrl 切换为正式线转发目标地址。安全设备：按正式线配置切换设备地址。

后端留存 PID，供后续追溯与网安协调

PID 是认证服务凭据数据。后端可保存认证响应中的 data.PID，并关联本次业务流水与用户账号，作为后续网安协调时提供的认证凭据。

PID 与 encryptedIdInfo 同在认证响应的 data 中；按实际返回保存 PID 原始值。

认证响应中的字段位置

"data": {
  "PID": "认证服务凭据数据",
  "encryptedIdInfo": "加密身份信息"
}

交流与支持

感谢聆听，欢迎交流

如需商务合作或技术支持，欢迎扫码联系。

商务支持

叶凌志

技术支持

网证认证	网证（R01）	网证+口令（R02）	网证+人像（R03）	网证+口令+人像（R04）
返回网络身份认证凭据
返回网络身份认证凭据+年龄段标识