信息安全技术 居民身份网络认证服务接口要求

ICS34.040

CCSL80

中华人民共和国国家标准

GB/TXXXXX—XXXX

`

网络身份认证公共服务可信数字身份认证

服务接口技术要求

Networkidentityauthenticationpublicservice—Technicalrequirementsfortrusted

digitalidentityauthenticationservicesinterface

（征求意见稿）

XXXX-XX-XX发布XXXX-XX-XX实施

GB/TXXXXX—XXXX

前言

本文件按照GB/T1.1—2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定

起草。

本部分由中华人民共和国公安部提出并归口。

本部分起草单位：公安部第一研究所、公安部网络安全保卫局、北京中盾安信科技发展有限公司、

中国科学院大学。

本部分主要起草人：于锐、杨林、蒋文合、高爽、周卫东、贺嘉良、吴国英、王开林、颜挺、国伟、

荆继武、王琼霄、白培鑫、吴明明。

II

GB/TXXXXX—XXXX

网络身份认证公共服务可信数字身份认证服务接口要求

1范围

本文件规定了可信数字身份认证服务过程中接口作用、交互方式、总体框架和接口描述。

本文件适用于可信数字身份认证服务接口的设计、开发和调用。

2规范性引用文件

本文件没有规范性引用文件。

GB11643—1999公民身份号码

GA/TAAAAA网络身份认证服务通用术语

3术语、定义和缩略语

3.1术语和定义

GA/TAAAAA界定的术语和定义适用于本文件。

3.2缩略语

下列缩略语适用于本文件。

HTTP：超文本传输协议（HypertextTransferProtocol）

JSON：JavaScript标记（JavaScriptObjectNotation）

URL：统一资源定位符（UniformResourceLocator）

4概述

4.1接口作用

可信数字身份认证服务面向业务应用系统/第三方认证平台，提供网络身份认证凭证认证接口、网

络身份认证凭证二维码认证接口，根据不同的业务场景以及安全要求等级，提供了以网络身份认证凭证、

网络身份认证凭证口令、人脸等多种认证因子组合的多种认证模式，确保可信数字身份认证的真实性、

正确性和有效性。

4.2交互方式

接口交互中服务端（居民身份网络认证服务系统）与客户端（网证应用服务端）之间采用HTTP协议

进行传输，数据交换格式为JSON，请求头只允许Content-Type:application/json，网络身份认证公共

服务通过POST方式访问可信数字身份认证服务接口，调用方式如下：

http://[host]:[port]/uentrance/interf/[interface]

其中：

1

GB/TXXXXX—XXXX

——[host]：服务IP或者域名；

——[port]：服务端口号；

——[interface]：服务接口名称。

5总体框架

5.1概述

可信数字身份认证平台提供基于网络身份认证凭证的认证服务，对业务应用系统上传的网络身份认证

凭证或网络身份认证凭证二维码数据和其他认证因子（网络身份认证凭证口令、人脸等）进行真实性、正

确性和有效性的确认。

平台通过网络身份认证凭证或网络身份认证凭证二维码与口令、人脸等认证因子的多种组合进行认

证，认证模式包括：

a)网络身份认证凭证认证；

b)网络身份认证凭证+口令认证；

c)网络身份认证凭证+人脸认证；

d)网络身份认证凭证+口令+人脸认证；

e)网络身份认证凭证+口令认证返回身份信息；

f)网络身份认证凭证+人脸认证返回身份信息；

g)网络身份认证凭证+口令+人脸认证返回身份信息；

h)网络身份认证凭证二维码认证；

i)网络身份认证凭证二维码+人脸认证；

j)网络身份认证凭证二维码+人脸认证返回身份信息。

业务应用服务商可针对不同的使用场景、安全要求等级进行使用。

第三方应用使用网络身份认证凭证进行认证，需调用网络身份认证APP获取网络身份认证凭证，为防

止第三方在获取网络身份认证凭证后进行留存重复使用，网络身份认证APP对第三方应用完成调用权限校验后，

根据第三方上传业务序列号生成Token，网络身份认证APP使用Token对网络身份认证凭证和口令进行加密，

并返回给第三方应用，认证过程中需对Token的有效性进行核验。

第三方应用使用网络身份认证凭证二维码进行认证，用户通过网络身份认证APP出示本人网络身份认

证凭证二维码，第三方可通过扫码设备扫描网络身份认证凭证二维码，将网络身份认证凭证二维码和其他认

证因子（人脸）上传到平台进行认证。

5.2网络身份认证凭证认证

网络身份认证凭证认证模式，需要网络身份认证凭证参与认证，认证通过情况下返回网络身份认证

凭据。接口调用关系见图1。

2

GB/TXXXXX—XXXX

业务应用系统/可信数字身份认

第三方认证平台证平台

网络身份认证凭证

网络身份认证凭证认证响应

返回网络身份认证凭据

图1网络身份认证凭证接口调用关系图

5.3网络身份认证凭证+口令认证

网络身份认证凭证+口令认证模式，需要网络身份认证凭证、口令参与认证，认证通过情况下返回

网络身份认证凭据。接口调用关系见图2。

业务应用系统/可信数字身份认

第三方认证平台证平台

网络身份认证凭证+口令认证

网络身份认证凭证+口令认证响应

返回网络身份认证凭据

图2网络身份认证凭证+口令认证接口调用关系图

5.4网络身份认证凭证+人脸认证

网络身份认证凭证+人脸认证模式，需要网络身份认证凭证、人脸参与认证，认证通过情况下返回

网络身份认证凭据、人脸相似度分数，接口调用关系见图3。

3

GB/TXXXXX—XXXX

业务应用系统/可信数字身份认

第三方认证平台证平台

网络身份认证凭证+人脸

网络身份认证凭证+人脸认证响应

返回网络身份认证凭据、人脸相似度分数

图3网络身份认证凭证+人脸认证接口调用关系图

5.5网络身份认证凭证+口令+人脸认证

网络身份认证凭证+口令+人脸认证模式，需要网络身份认证凭证、口令、人脸参与认证，认证通过

情况下返回网络身份认证凭据、人脸相似度分数，接口调用关系见图4。

业务应用系统/可信数字身份认

第三方认证平台证平台

网络身份认证凭证+口令+人脸

网络身份认证凭证+口令+人脸认证响应

返回网络身份认证凭据、人脸相似度分数

图4网络身份认证凭证+口令+人脸认证接口调用关系图

5.6网络身份认证凭证+口令认证返回身份信息

网络身份认证凭证+口令认证返回身份信息认证模式，需要网络身份认证凭证、口令认证返回身份

信息参与认证，认证通过情况下返回网络身份认证凭据和身份信息，接口调用关系见图5。

4

GB/TXXXXX—XXXX

业务应用系统/可信数字身份认

第三方认证平台证平台

网络身份认证凭证+口令

网络身份认证凭证+口令认证响应

返回网络身份认证凭据和身份信息

图5网络身份认证凭证+口令认证返回身份信息认证接口调用关系图

5.7网络身份认证凭证+人脸认证返回身份信息

网络身份认证凭证+人脸认证返回身份信息认证模式，需要网络身份认证凭证、人脸认证返回身份

信息参与认证，认证通过情况下返回网络身份认证凭据、人脸相似度分数和身份信息，接口调用关系见

图6。

业务应用系统/可信数字身份认

第三方认证平台证平台

网络身份认证凭证+人脸

网络身份认证凭证+人脸认证响应

返回网络身份认证凭据、人脸相似度分数和身份信息

图6网络身份认证凭证+人脸认证返回身份信息认证接口调用关系图

5.8网络身份认证凭证+口令+人脸认证返回身份信息

网络身份认证凭证+口令+人脸认证返回身份信息认证模式，需要网络身份认证凭证、口令、人脸认

证返回身份信息参与认证，认证通过情况下返回网络身份认证凭据、人脸相似度分数和身份信息，接口

调用关系见图7。

5

GB/TXXXXX—XXXX

业务应用系统/可信数字身份认

第三方认证平台证平台

网络身份认证凭证+口令+人脸

网络身份认证凭证+口令+人脸认证认证响应

返回网络身份认证凭据、人脸相似度分数和身份信息

图7网络身份认证凭证+口令+人脸认证返回身份信息证接口调用关系图

5.9网络身份认证凭证二维码认证

网络身份认证凭证二维码认证模式，需要网络身份认证凭证二维码参与认证，认证通过情况下返回

网络身份认证凭据，接口调用关系见图8。

业务应用系统/可信数字身份认

第三方认证平台证平台

网络身份认证凭证二维码

网络身份认证凭证二维码认证响应

返回网络身份认证凭据

图8网络身份认证凭证二维码认证接口调用关系图

5.10网络身份认证凭证二维码+人脸认证

网络身份认证凭证二维码+人脸认证模式，需要网络身份认证凭证二维码、人脸参与认证，认证通过

情况下返回网络身份认证凭据、人脸相似度分数，接口调用关系见图9。

6

GB/TXXXXX—XXXX

业务应用系统/可信数字身份认

第三方认证平台证平台

网络身份认证凭证二维码+人脸

网络身份认证凭证二维码+人脸认证响应

返回网络身份认证凭据、人脸相似度分数

图9网络身份认证凭证二维码+人脸认证接口调用关系图

5.11网络身份认证凭证二维码+人脸认证返回身份信息

网络身份认证凭证二维码+人脸认证返回身份信息认证模式，需要网络身份认证凭证二维码、人脸

认证返回身份信息参与认证，认证通过情况下返回网络身份认证凭据、人脸相似度分数和身份信息，接

口调用关系见图10。

业务应用系统/可信数字身份认

第三方认证平台证平台

网络身份认证凭证二维码+人脸

网络身份认证凭证二维码+人脸认证返回信息响应

返回网络身份认证凭据、人脸相似度分数和身份信息

图10网络身份认证凭证二维码+人脸认证返回身份信息认证接口调用关系图

6接口描述

6.1网络身份认证凭证认证接口

6.1.1接口说明

网络身份认证凭证认证接口说明见表1。

7

GB/TXXXXX—XXXX

表1网络身份认证凭证认证接口说明

项目内容

接口地址http://ip:port/uentrance/interf/auth/request

接口调用方式POST

接口描述网络身份认证凭证认证接口

所属服务凭证认证接入服务

6.1.2请求数据

网络身份认证凭证认证接口请求数据见表2。

表2网络身份认证凭证认证接口请求数据表

字段名字段描述选项数据类型长度约束与说明

调用签名验签服务器对bizPackage进行PKCS#7签

sign签名必选String2k

名

bizPackage业务数据必选Object--

表2中bizPackage字段说明见表3。

表3网络身份认证凭证认证接口请求数据bizPackage说明表

字段名字段描述选项数据类型长度约束与说明

appName应用名称必选String32长度小于等于32

timestamp时间戳必选String17东八区（UTC/GMT+08:00）“YYYYMMddHHmmssSSS”

bizSeq业务序列号必选String32—

R01：网络身份认证凭证；

R02：网络身份认证凭证+口令；

R03：网络身份认证凭证+人脸；

R04：网络身份认证凭证+口令+人脸；

R05：网络身份认证凭证+口令返回身份信息；

mode认证模式必选String3

R06：网络身份认证凭证+人脸返回身份信息；

R07：网络身份认证凭证+口令+人脸返回身份

信息。

非上面的模式，会返回“接入权限核验失

败”

签名验签服务器公钥证书主体名称，长度小

customerNo业务站点号必选String16

于等于16

mode=R03、R04、R06、R07时，值不为空。

photoEncData是用接收方的加密证书对数据

包{“photoData”：照片原文数据的Base64编码}

photoEncData照片数据可选String-

进行数字信封加密后的BASE64数据。

非R03、R04、R06、R07模式，不传

photoEncData，如果需传输，则只能传正确格式

8

GB/TXXXXX—XXXX

字段名字段描述选项数据类型长度约束与说明

的photoEncData数据

mode=R02、R04、R05、R07时，值不为空。

网络身份认证凭证口

certPwdData可选String通过调用网络身份认证APP调用的SDK中

令加密数据

“getAuthResult”接口生成

通过调用网络身份认证APP调用的SDK中

idCardAuthData认证请求数据必选String

“getAuthResult”接口生成

表3网络身份认证凭证认证接口请求数据bizPackage说明表（续）

字段名字段描述选项数据类型长度约束与说明

该字段与权限有关，R01～R04模式不能上传，

R05～R07模式，在需要返回身份信息的情况下上

传：

1)各个返回数据项使用英文“,”分隔；

expectData期望返回数据项可选String2002)只能包含英文大写字母；

3)返回数据项包括：GMSFHM、NL，其中：

——GMSFHM：公民身份号码；

——NL：年龄。

GMSFHM、NL不能同时返回

cert加密证书可选String5KR05～R07模式，在返回身份信息的情况下必传

表3中photoEncData字段说明见表4。

表4网络身份认证凭证认证接口请求数据photoEncData说明表

字段名字段描述选项数据类型长度约束与说明

照片原文数据的Base64编码，图像格式为

photoData照片数据必选String10K～70K

jpg，png等

表3中certPwdData字段说明见表5。

表5网络身份认证凭证认证接口请求数据certPwdData说明表

字段名字段描述选项数据类型长度约束与说明

网络身份认证凭证口mode=R02/R04时，值不为空1)只能包含0～

certPwd必选String64

令9A～F（网络身份认证凭证口令hash值）

网络身份认证凭证口

certPwdAuthToken必选String96mode=R02/R04/R05/R07时，值不为空

令认证Token

表3中idCardAuthData字段说明见表6。

表6网络身份认证凭证认证接口请求数据idCardAuthData说明表

字段名字段描述选项数据类型长度约束与说明

网络身份认证凭证认

idcardAuthToken必选String96-

证Token

9

GB/TXXXXX—XXXX

certData网络身份认证凭证必选String128Base64编码，解Base64后为95字节

orgID机构ID必选String8只能包含数字

appID应用ID必选String4只能包含数字

deviceID设备ID必选String64长度小于等于64

packageName包名必选String256长度小于等于256

deviceBrand设备品牌必选String64长度小于等于64

deviceModel设备型号必选String64长度小于等于64

1：Android；

osType操作系统必选String12：iOS；

3：Windows。

示例：

{

"sign":"XXXXXXXXX",

"bizPackage":{"bizSeq":"hfjdksdnksde","mode":"R01","customerNo":"ywzd111","appName":"X",

"timestamp":"20210101121212111",

"photoEncData":"asfafasf","certPwdData":"afsafasfafsa","idCardAuthData":"asfafasfafafsa"

}

}

6.1.3应答数据

网络身份认证凭证认证接口应答数据见表7。

表7网络身份认证凭证认证接口应答数据说明表

字段名字段描述选项数据类型长度约束与说明

调用签名验签服务器对bizPackage进行PKCS#7签

sign签名必选String2k

名

bizPackage业务数据必选Object——

表7中bizPackage字段说明见表8。

表8网络身份认证凭证认证接口应答数据bizPackage说明表

字段名字段描述选项数据类型长度约束与说明

bizSerialNo业务流水号必选String24只能包含0～9A～Z

resultCode响应码必选String8见5.1.4返回码说明

resultDesc响应描述必选String256对应的响应信息描述

bizSeq业务序列号必选String32—

响应结果码为C0000000时，值不

data响应数据必选Object—

为空。

表8中data字段说明见表9。

表9data字段说明

10

GB/TXXXXX—XXXX

字段名字段描述选项数据类型长度约束与说明

164～

PID网络身份认证凭据可选StringBASE64编码

172

photoCompareScore人脸相似度分数可选String8范围0～1000分，人脸比对通过时返回

JSON格式，R05～R07模式认证通过后返回，解密

encryptedIdInfo加密身份信息可选String—后格式如下：

{"GMSFHM":}

encryptedIdInfo字段说明见表10。

表10EncryptedIdInfo明文说明

字段名字段描述选项数据类型长度约束与说明

长度为18；前17位只允许数字，第18位可以为数字或者

GMSFHM公民身份号码可选String18

“X”；按照GB11643—1999进行校验

NL年龄可选String5小于等于5位，保留一位小数

示例：

{

"sign":"XXXXXXXXX",

"bizPackage":{

"bizSeq":"XXXXXXXXX",

"bizSerialNo":"XXXXXXXXX",

"resultCode":"XXXXXXXXX","resultDesc":"请求成功","data":{

"PID":"asdfwrawuifhj","photoCompareScore":"XXXXXXXX","encryptedIdInfo":"XXXXXXXX"

}

}

}

6.1.4返回码说明

网络身份认证凭证认证接口返回码说明见表11。

表11网络身份认证凭证认证接口返回码resultCode说明

编号代码描述

1C0000000请求成功

2S0200001系统异常

3C0299002业务超时

4C0201004模式异常

5C0201009机构ID异常

6C0201010应用ID异常

11

GB/TXXXXX—XXXX

编号代码描述

7C0207002人脸图像不合格

8C0208001网络身份认证凭证未查到

9C0208002无效网络身份认证凭证

11C0207001人脸比对未通过

12C0210001网络身份认证凭证口令错误

13C0201003业务序列号异常

14C0201032加密证书异常

15C0201027期望返回数据项异常

16C0206004身份信息未查到

17C0201999参数异常

18C0204001验签失败

19C0203001接入权限核验失败

20C0203002服务并发达到上限

21C0203003服务当日调用次数已耗尽

22C0201999接口地址错误

23C0201999不支持的请求协议

24C0201999Content-Type非法

25C0201999customerNo值不正确

26C0201999请求包大小超出限制

6.2网络身份认证凭证二维码认证接口

6.2.1接口说明

网络身份认证凭证二维码认证接口说明见表12。

表12网络身份认证凭证二维码认证接口说明

项目内容

接口地址http://ip:port/uentrance/interf/qrcode-auth/request

接口调用方式POST

接口描述网络身份认证凭证二维码认证接口

所属服务二维码认证接入服务

6.2.2请求数据

网络身份认证凭证二维码认证接口请求数据见表13。

表13网络身份认证凭证二维码认证接口请求数据表

字段名字段描述选项数据类型长度约束与说明

12

GB/TXXXXX—XXXX

调用签名验签服务器对bizPackage进行PKCS#7

sign签名必选String2k

签名

bizPackage业务数据必选Object——

表13中bizPackage字段说明见表13。

表14网络身份认证凭证二维码认证接口请求数据bizPackage说明表

字段名字段描述选项数据类型长度约束与说明

appName应用名称必选String32长度小于等于32

timestamp时间戳必选String17东八区（UTC/GMT+08:00）“YYYYMMddHHmmssSSS”

bizSeq业务序列号必选String32—

R21：网络身份认证凭证二维码；

R23：网络身份认证凭证二维码+人脸；

mode认证模式必选String3R27：网络身份认证凭证二维码+人脸返回身份信

息。

非以上模式，会返回“接入权限核验失败”

最大长度16。

customerNo业务站点号必选String16

签名服务器公钥证书主体名称

—mode=R23、R27时，值不能为空。

hotoEncData是用接收方的加密证书对数据包

{"photoData"：照片原文数据的Base64编码}进行数

photoEncData照片数据可选String

字信封加密后的Base64数据。非R23模式，

photoEncData不传，传只能传正确格式的

photoEncData数据

—qrcodeAuthData是用接收方的加密证书对数据包：

网络身份认证凭证二{"orgID"：机构ID,"appID"：应用ID,"qrCode"：网

qrcodeAuthData必选String

维码认证数据络身份认证凭证二维码数据}进行数字信封加密后的

Base64数据

该字段与权限有关，R27模式，在需要返回身份

信息的情况下上传，其他模式不能传：

1)各个返回数据项使用英文“,”分隔；

expectData期望返回数据项可选String200

2)只能包含英文大写字母；

3)返回数据项包括：NL；

NL：年龄

cert加密证书可选String5KR27模式，在返回身份信息的情况下必传

表14中字段photoEncData说明见表15。

表15网络身份认证凭证二维码认证接口请求数据photoEncData说明表

字段名字段描述选项数据类型长度约束与说明

photoData照片数据必选String10K-70K照片原文数据的Base64编码，图像格式