服务端接入
本文介绍了PC或移动端H5网页认证方案的接入流程。
发起认证请求
接口名:InitFaceVerify。
服务地址:cloudauth.aliyuncs.com(IPv4)或cloudauth-dualstack.aliyuncs.com(IPv6)
请求方法:POST和GET。
传输协议:HTTPS。
接口说明:每次开始认证前通过本接口获取CertifyId,用来串联认证请求中的各个接口。
请求参数
名称 | 类型 | 是否必选 | 描述 | 示例值 |
SceneId | Long | 是 | 要接入的认证场景ID。该ID在控制台创建认证场景后自动生成。关于如何创建认证场景,请参见添加认证场景。 | 1000000006 |
OuterOrderNo | String | 是 | 您自定义的业务唯一标识,用于后续定位排查问题使用。 支持长度为32位的字母和数字组合,请确保唯一。 | e0c34a77f5ac40a5aa5e6ed20c353888 |
ProductCode | String | 是 | 要接入的认证方案。 唯一取值:ID_PRO。 | ID_PRO |
Model | String | 是 | 要进行活体检测的类型。
| MULTI_ACTION |
CertType | String | 是 | 用户证件类型。支持的证件类型,请参见方案概述。 唯一取值:IDENTITY_CARD。 | IDENTITY_CARD |
CertName | String | 是 | 您的终端用户的真实姓名。 | 张三 |
CertNo | String | 是 | 您的终端用户的证件号码。 | 330103xxxxxxxxxxxx |
ReturnUrl | String | 是 | 您业务页面回跳的目标地址。 | https://www.aliyun.com |
MetaInfo | String | 是 | MetaInfo环境参数。实际环境需要通过JS文件,调用函数 | {"zimVer":"3.0.0","appVersion": "1","bioMetaInfo": "4.1.0:1150****,0","appName": "com.aliyun.antcloudauth","deviceType": "ios","osVersion": "iOS 10.3.2","apdidToken": "","deviceModel": "iPhone9,1"} 说明 该示例仅供参考,实际集成中不能直接应用,否则会导致无法正常获取到认证URL。 |
Mobile | String | 否 | 您终端用户的手机号码。 | 130xxxxxxxx |
Ip | String | 否 | 您终端用户的IP。 | 47.100.XX.XX |
UserId | String | 否 | 您自定义的用户ID,请保持唯一。 | 123456789 |
CallbackUrl | String | 否 | 认证结果的回调通知地址,回调请求方式默认为GET,回调地址必须以 说明 仅当认证完成(包含认证通过和认证未通过)时才会触发回调,若认证中放弃、异常中断或未进行认证均不会通知。建议您收到回调通知时,若有需要可通过查询接口获取认证详情信息。 | https://www.aliyun.com |
CallbackToken | CallbackToken | 否 | 安全Token,由您自行生成,用于防重复、防篡改校验。 如果设置了该值会在回调地址显示CallbackToken字段。 | NMjvQanQgplBSaEI0sL86WnQplB |
CertifyUrlType | String | 否 | Web SDK设备类型。取值WEB或者H5。 说明 只支持Web SDK设备类型。 | WEB |
CertifyUrlStyle | String | 否 | 返回certifyUrl类型,包括:
| L |
AuthId | String | 否 | 用户授权ID,最大长度为64位字符。 | 92d46b9e9e2d703f2897f350d5bd4149 |
EncryptType | String | 否 | 加密类型。为空表示不加密。 如开启加密传输,需传入加密算法。目前仅支持SM2国密算法。 如需传入加密算法,需对CertName和CertNo进行加密,并传入加密后的密文。有关参数加密的更多信息,请参见参数加密说明。 | SM2 |
ProcedurePriority | String | 否 | 移动端H5方式认证出现WebRTC或者Webassembly不兼容时的降级配置。默认值:url。
说明 仅移动端H5认证方式支持降级。 本功能目前处于试用阶段,此配置默认不生效,如果您想试用此功能,请通过智能在线联系阿里云工程师。 | url |
返回数据
名称 | 类型 | 描述 | 示例值 |
RequestId | String | 请求ID。 | 130A2C10-B9EE-4D84-88E3-5384FF039795 |
Message | String | 返回信息。 | success |
Code | String | 返回码:200为成功,其他为失败。 | 200 |
ResultObject.CertifyId | String | 实人认证唯一标识。 警告 CertifyId字段为计费统计字段,为了方便后续核对账单,请您在本地留存该字段信息。 初始化接口返回的认证CertifyId在30分钟有效且仅能认证提交一次,请您在有效期内应用,避免重复使用。 | 91707dc296d469ad38e4c5efa6a0f24b |
ResultObject.CertifyUrl | String | Web认证URL,认证结束后根据入参ReturnUrl进行跳转。 说明 初始化接口返回的认证CertifyUrl在30分钟有效且仅能认证提交一次,请您在有效期内应用,避免重复使用。 | http://m.alyms.cn/**** |
返回Code和Message说明
Code | Message | 描述 |
200 | success | 成功。 |
400 | 参数不能为空 | 参数不能为空。 |
401 | 参数非法 | 非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。 |
402 | 应用配置不存在 | 应用配置不存在。 |
404 | 认证场景配置不存在 | 认证场景配置不存在,请先在控制台上创建认证场景。 |
410 | 未开通服务 | 未开通OSS产品或未完成OSS读写授权,请登录控制台完成授权。 |
411 | RAM无权限 | 需要给RAM用户授予AliyunAntCloudAuthFullAccess的操作权限。 |
412 | 欠费中 | 金融级实人认证或OSS存在欠费,请充值后操作。 |
414 | 设备类型不支持 | 当前移动设备不支持刷脸认证,请更换设备后操作。 |
415 | SDK版本不支持 | 当前认证SDK版本不支持刷脸认证,请升级SDK后操作。 |
416 | 系统版本不支持 | 当前操作系统版本不支持刷脸认证,请升级系统或更换设备操作。 |
417 | 无法使用刷脸服务 | 当前身份信息比对源不可用。若信息正确,建议人工审核。 |
418 | 刷脸失败次数过多 | 当天刷脸认证次数过多,请明天再试。 |
500 | 系统错误 | 系统内部错误,请反馈工程师排查。 |
查询认证结果
接口名:DescribeFaceVerify。
服务地址:cloudauth.aliyuncs.com(IPv4)或cloudauth-dualstack.aliyuncs.com(IPv6)
请求方法:POST和GET。
传输协议:HTTPS。
接口说明:当您收到回调通知之后,可以在服务端通过该接口获取相应的认证状态和认证资料。
请求参数
名称 | 类型 | 是否必选 | 描述 | 示例值 |
SceneId | Long | 是 | 认证场景ID。 | 1000000006 |
CertifyId | String | 是 | 实人认证唯一标识。 | 91707dc296d469ad38e4c5efa6a0f24b |
返回数据
名称 | 类型 | 描述 | 示例值 |
RequestId | String | 请求ID。 | 130A2C10-B9EE-4D84-88E3-5384FF039795 |
Message | String | 请求消息的响应信息。 | success |
Code | String | 返回码。关于返回码的详细说明,请参见下文ResultObject.SubCode错误码说明。 | 200 |
ResultObject.Passed | String | 认证结果。取值:
说明 判断认证结果请以ResultObject.Passed字段为准。 | T |
ResultObject.SubCode | String | 认证结果描述。具体请参见下文ResultObject.SubCode错误码说明。 说明 判断认证结果请以ResultObject.Passed字段为准。 | 200 |
ResultObject.IdentityInfo | String | 认证的主体信息,一般的认证场景返回为空。 | null |
ResultObject.MaterialInfo | String | 认证主体附件信息,主要为图片类材料。 本参数取值中涉及的字段解释,请参见下文的返回示例。 | {"faceAttack": "F","faceOcclusion":"F","facialPictureFront": {"faceAttackScore": 0.00008597839769208804,"qualityScore": 88.3615493774414,"verifyScore": 50.28594166529785,"pictureUrl": "https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/verify/xxxxx/xxxxx.jpeg","ossBucketName": "cn-shanghai-aliyun-cloudauth-1260051251634779","ossObjectName": "verify/1260051251634779/6ba7bcfccf33f56cdb44ed086f36ce3e0.jpeg"}} |
判断认证结果请以ResultObject.Passed字段为准。
返回示例
ResultObject.MaterialInfo的JSON格式示例:
{
// 是否为攻击:攻击为T,非攻击为F。
"faceAttack": "T",
// 是否有脸部遮挡:有脸部遮挡为T,否则为F。
"faceOcclusion": "F",
// 认证的照片信息。
"facialPictureFront": {
//人脸攻击分。
"faceAttackScore": 0.00008597839769208804,
// 照片存放客户上海区域的OSS里,此为照片的bucket名。
"ossBucketName": "cn-shanghai-aliyun-cloudauth-1260051251634779",
// 照片存放客户上海区域的OSS里,此为照片的文件名。
"ossObjectName": "verify/1260051251634779/03a081bd96328aedf83f635f39a50c57_0.jpeg",
// 照片https地址,有效期15分钟,从查询时开始计时。
"pictureUrl": "http://cn-shanghai-aliyun-cloudauth-1260051251634779.oss-cn-shanghai.aliyuncs.com/verify/1260051251634779/03a081bd96328aedf83f635f39a50c57_0.jpeg?Expires=1625371140&OSSAccessKeyId=STS.NTX1ngfr6Acg2Pmnn2RYM****&Signature=Hw5BF9WxJs6wI68IxKs41cxCU8****&security-token=CAISjgJ1q6Ft5B2yfSjIr5ftetTTi60X9qGMMHbcim5nXtZhu7GT1Dz2IH1PdXFgA%2Bgds%2Fswmm5U7vgalrkqEcEdHRGdN5YpsM8LrlzwO1h2TGRsq%2B5qsoasPETOITyZtZagToeUZdfZfejXGDKgvyRvwLz8WCy%2FVli%2BS%2FOggoJmadJlNWvRL0AxZrFsKxBltdUROFbIKP%2BpKWSKuGfLC1dysQcO4gEWq4bHm5fCskKD1Qenk7FO%2B9uuc6LJNZc8YM1NNP6ux%2FFze6b71ypd1gNH7q8ejtYfpGyW5oHHWwIMvErYbbaMrIV1WwZ9Z7knHaVAq%2BXwnOBkuuXYnIns0BdLMuZOSD7YQI2wYWEwgBcxt78agAF%2FHZbelNLYWtipAu5X5oG1t22SqIr1p3TMK5FrjDIVeWOppcxeRXtU%2BjR7hGcwd25scGhiraoxTXV3sxw%2F6dhFSswQ37O4j%2B%2FrCPtiGauqn2ZMdMj%2FvYwKb6KmpQqa%2BtR%2F9cxhS6hoIQRq0SUIfyXl5ZUiZbTjW22iwuX%2BPwzVCw%3D%3D",
// 活体人脸质量分数。
"qualityScore": 99.93476867675781,
// 人脸和公安比对分数,阈值可参考下表详细说明。
"verifyScore": 57.678396649466755
},
}
ResultObject.SubCode错误码说明
错误码 | 认证描述文案 | 是否计费 | 可能原因和处理建议 |
200 | 认证通过 | 是 | 成功。 |
201 | 姓名和身份证不一致 | 是 | 可能是用户的信息有误或用户的信息为假信息,建议用户确认后重新操作。若同一身份信息重新发起认证,服务端初始化将会返回417错误。 |
202 | 查询不到身份信息 | 是 | 可能是用户户口迁移等特殊状态导致,建议预留人工审核入口,进行人工审核。若同一身份信息重新发起认证,服务端初始化将会返回417错误。 |
203 | 查询不到照片或照片不可用 | 是 | 可能是公安库数据问题导致,建议预留人工审核入口,进行人工审核。若同一身份信息重新发起认证,服务端初始化将会返回417错误。 |
204 | 人脸比对不一致 | 是 | 可能不是同一人或活体照片质量较低,建议根据业务情况分层处理,若为同一人可重新操作。 |
205 | 活体检测存在风险 | 是 | 可能存在攻击风险,建议人工审核分层处理,若为真人可重新操作。 |
206 | 业务策略限制 | 是 | 为了保证认证的安全性,会对认证的设备、身份、人脸等环境进行安全检测,若检测到可能存在风险会判定认证结果不通过。您可以按照如下方法排查处理:
|
210 | 认证通过 | 是 | 通过产品安全策略综合判断,建议认证通过。 |
verifyScore阈值说明
千分之一误识率 | 万分之五误识率 | 万分之一误识率 | 十万分之五误识率 | 十万分之一误识率 |
70 | 71.5 | 75 | 76.5 | 80 |
如果您有个性化需求,您可以根据业务情况,参考返回的比对分和阈值,自定义认证结果。
返回Code和Message说明
Code | Message | 描述 |
200 | success | 成功。 |
400 | 参数不能为空 | 参数不能为空。 |
401 | 参数非法 | 非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。 |
403 | 认证未完成 | 认证未完成。 |
404 | 认证场景配置不存在 | 认证场景配置不存在,请先在控制台上创建认证场景。 |
406 | 无效的CertifyId | 无效的CertifyId。 |
410 | 未开通服务 | 未开通OSS产品或未完成OSS读写授权,请登录控制台完成授权。具体操作,请参见授权金融级实人认证访问OSS存储空间。 |
411 | RAM无权限 | 需要给RAM用户授予AliyunAntCloudAuthFullAccess的操作权限。 |
424 | 身份认证记录不存在 | 当前CertifyId还未完成认证,建议您客户端收到认证回调为1000或2006时,再请求查询接口获取详情。 说明 如果出现CertifyId未认证、认证过程中放弃、认证处理中的情况,均会导致查询接口返回此错误码。 |
427 | 业务策略限制 | 仅在使用ID_PLUS方案时出现,指该身份因触发内部风控策略未完成认证。 |
500 | 系统错误 | 系统内部错误,请通过智能在线联系阿里云工程师协助排查。 |
Java调用示例
如需其他语言的SDK示例代码,您可以通过OpenAPI在线调试工具调试API接口。该工具会自动生成相应API的SDK调用示例代码。更多信息,请参见:
使用Maven引入SDK
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>cloudauth20190307</artifactId>
<version>2.0.6</version>
</dependency>
InitFaceVerify接口调用示例
import java.util.Arrays;
import java.util.List;
import com.aliyun.cloudauth20190307.Client;
import com.aliyun.cloudauth20190307.models.*;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;
public class InitFaceVerify {
public static void main(String[] args) throws Exception {
InitFaceVerifyRequest request = new InitFaceVerifyRequest();
// 请输入场景ID+L。
request.setSceneId(0L);
// 设置商户请求的唯一标识。
request.setOuterOrderNo("xxxx");
// 认证方案。
request.setProductCode("ID_PRO");
// 模式。
request.setModel("LIVENESS");
request.setCertType("IDENTITY_CARD");
request.setCertName("张先生");
request.setCertNo("xxxx");
// MetaInfo环境参数。
request.setMetaInfo("{}");
//request.setMobile("130xxxxxxxx");
//request.setIp("114.xxx.xxx.xxx");
//request.setUserId("12345xxxx");
//request.setCallbackUrl("https://www.aliyundoc.com");
//request.setCallbackToken("xxxxx");
// 如需开启个人信息加密传输。
//request.setEncryptType("SM2");
//request.setCertName("BCRD/7ZkNy7Q*****M1BMBezZe8GaYHrLwyJv558w==");
//request.setCertNo("BMjsstxK3S4b1YH*****Pet8ECObfxmLN92SLsNg==");
// 推荐,支持服务路由。
InitFaceVerifyResponse response = initFaceVerifyAutoRoute(request);
// 不支持服务自动路由。
//InitFaceVerifyResponse response = initFaceVerify("cloudauth.cn-shanghai.aliyuncs.com", request);
response.getBody().getRequestId();
response.getBody().getResultObject().getCertifyId();
System.out.println(response.getBody().getRequestId());
System.out.println(response.getBody().getCode());
System.out.println(response.getBody().getMessage());
System.out.println(response.getBody().getResultObject() == null ? null
: response.getBody().getResultObject().getCertifyId());
}
private static InitFaceVerifyResponse initFaceVerifyAutoRoute(InitFaceVerifyRequest request) {
// 第一个为主区域Endpoint,第二个为备区域Endpoint。
List<String> endpoints = Arrays.asList("cloudauth.cn-shanghai.aliyuncs.com", "cloudauth.cn-beijing.aliyuncs.com");
InitFaceVerifyResponse lastResponse = null;
for (int i=0; i<endpoints.size(); i++) {
try {
InitFaceVerifyResponse response = initFaceVerify(endpoints.get(i), request);
lastResponse = response;
// 服务端错误,切换到下个区域调用。
if(response != null){
if(500 == response.getStatusCode()){
continue;
}
if(response.getBody() != null){
if("500".equals(response.getBody().getCode())){
continue;
}
}
}
// 正常返回
return lastResponse;
}catch (Exception e) {
e.printStackTrace();
if(i == endpoints.size()-1){
throw new RuntimeException(e);
}
}
}
return lastResponse;
}
private static InitFaceVerifyResponse initFaceVerify(String endpoint, InitFaceVerifyRequest request)
throws Exception {
// 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。
// 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。
// 本示例通过阿里云Credentials工具从环境变量中读取AccessKey,来实现API访问的身份验证。如何配置环境变量,请参见https://help.aliyun.com/document_detail/378657.html。
com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
Config config = new Config();
config.setCredential(credentialClient);
config.setEndpoint(endpoint);
// 设置http代理。
//config.setHttpProxy("http://xx.xx.xx.xx:xxxx");
// 设置https代理。
//config.setHttpsProxy("https://xx.xx.xx.xx:xxxx");
Client client = new Client(config);
// 创建RuntimeObject实例并设置运行参数。
RuntimeOptions runtime = new RuntimeOptions();
runtime.readTimeout = 10000;
runtime.connectTimeout = 10000;
return client.initFaceVerifyWithOptions(request, runtime);
}
}
DescribeFaceVerify接口调用示例
import java.util.Arrays;
import java.util.List;
import com.aliyun.cloudauth20190307.Client;
import com.aliyun.cloudauth20190307.models.DescribeFaceVerifyRequest;
import com.aliyun.cloudauth20190307.models.DescribeFaceVerifyResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;
public class DescribeFaceVerify {
public static void main(String[] args) throws Exception {
// 通过以下代码创建API请求并设置参数。
DescribeFaceVerifyRequest request = new DescribeFaceVerifyRequest();
// 请输入场景ID+L。
request.setSceneId(0L);
request.setCertifyId("xxxx");
// 推荐,支持服务路由。
DescribeFaceVerifyResponse response = describeFaceVerifyAutoRoute(request);
// 不支持服务自动路由。
//DescribeFaceVerifyResponse response = describeFaceVerify("cloudauth.cn-shanghai.aliyuncs.com", request);
System.out.println(response.getBody().getRequestId());
System.out.println(response.getBody().getCode());
System.out.println(response.getBody().getMessage());
System.out.println(
response.getBody().getResultObject() == null ? null : response.getBody().getResultObject().getPassed());
System.out.println(
response.getBody().getResultObject() == null ? null : response.getBody().getResultObject().getSubCode());
System.out.println(
response.getBody().getResultObject() == null ? null
: response.getBody().getResultObject().getIdentityInfo());
System.out.println(
response.getBody().getResultObject() == null ? null
: response.getBody().getResultObject().getDeviceToken());
System.out.println(
response.getBody().getResultObject() == null ? null
: response.getBody().getResultObject().getMaterialInfo());
}
private static DescribeFaceVerifyResponse describeFaceVerifyAutoRoute(DescribeFaceVerifyRequest request) {
// 第一个为主区域Endpoint,第二个为备区域Endpoint。
List<String> endpoints = Arrays.asList("cloudauth.cn-shanghai.aliyuncs.com", "cloudauth.cn-beijing.aliyuncs.com");
DescribeFaceVerifyResponse lastResponse = null;
for (int i = 0; i < endpoints.size(); i++) {
try {
DescribeFaceVerifyResponse response = describeFaceVerify(endpoints.get(i), request);
lastResponse = response;
// 服务端错误,切换到下个区域调用。
if (response != null) {
if (500 == response.getStatusCode()) {
continue;
}
if (response.getBody() != null) {
if ("500".equals(response.getBody().getCode())) {
continue;
}
}
}
return lastResponse;
} catch (Exception e) {
if (i == endpoints.size() - 1) {
throw new RuntimeException(e);
}
}
}
return lastResponse;
}
private static DescribeFaceVerifyResponse describeFaceVerify(String endpoint, DescribeFaceVerifyRequest request)
throws Exception {
// 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。
// 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。
//本示例通过阿里云Credentials工具从环境变量中读取AccessKey,来实现API访问的身份验证。如何配置环境变量,请参见https://help.aliyun.com/document_detail/378657.html。
com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
Config config = new Config();
config.setCredential(credentialClient);
config.setEndpoint(endpoint);
// 设置http代理。
//config.setHttpProxy("http://xx.xx.xx.xx:xxxx");
// 设置https代理。
//config.setHttpsProxy("http://xx.xx.xx.xx:xxxx");
Client client = new Client(config);
// 创建RuntimeObject实例并设置运行参数。
RuntimeOptions runtime = new RuntimeOptions();
runtime.readTimeout = 10000;
runtime.connectTimeout = 10000;
return client.describeFaceVerifyWithOptions(request, runtime);
}
}