本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。
在PC或移动端H5页面接入金融级实人认证方案时,开发者需要在后端服务器集成SDK,以便调用InitFaceVerify接口获取用于浏览器进行实人认证的认证链接CertifyUrl。本文将详细介绍服务端SDK的安装方式、所调接口的参数说明以及实际调用接口示例说明。
服务接入点
目前支持的接入地域如下表所示。
建议您参考本文示例代码,配置主备地域Endpoint。在主Endpoint发生故障时可以自动切换到备用Endpoint,保证系统的持续可用性。
地域 | 服务地址 | VPC地址 | 全局接入地址 |
华东2(上海) | IPv4:cloudauth.cn-shanghai.aliyuncs.com | cloudauth-vpc.cn-shanghai.aliyuncs.com |
|
IPv6:cloudauth-dualstack.aliyuncs.com | |||
华北2(北京) | IPv4:cloudauth.cn-beijing.aliyuncs.com | cloudauth-vpc.cn-beijing.aliyuncs.com | |
IPv6:cloudauth-dualstack.cn-beijing.aliyuncs.com |
请求方法
支持HTTPS POST或GET方式发送请求。
SDK安装与源码下载
您可根据业务实际的技术选型,选择合适的SDK语言进行集成。
支持语言 | Github源码地址 | SDK下载地址 |
Java | ||
Python | ||
Typescript | ||
Go | ||
PHP | ||
C# | ||
C++ |
服务端需要集成的OpenAPI
InitFaceVerify-发起认证请求
每次开始认证前通过调用本接口获取用于浏览器进行实人认证的认证链接CertifyUrl。
请求参数
名称 | 类型 | 是否必选 | 描述 | 示例值 |
SceneId | Long | 是 | 要接入的认证场景ID。该ID在控制台创建认证场景后自动生成。关于如何创建认证场景,请参见添加认证场景。 | 1000000006 |
OuterOrderNo | String | 是 | 您自定义的业务唯一标识,用于后续定位和排查问题使用。 支持长度为32位的字母和数字组合,请确保唯一。 | e0c34a77f5ac40a5aa5e6ed20c353888 |
ProductCode | String | 是 | 要接入的认证方案。 唯一取值:ID_PRO。详情方案说明,请参见PC或移动端H5网页接入方案介绍。 | 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 |
FaceGuardOutput | String | 否 | 人脸保镖标签种类。 DeviceRisk:设备风险标签。
说明 | DeviceRisk |
RarelyCharacters | String | 否 | 是否开启生僻字模式。
| Y |
返回数据
名称 | 类型 | 描述 | 示例值 |
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-获取认证结果
当您收到回调通知之后,可以在服务端通过该接口获取相应的认证状态和认证资料。
请求参数
名称 | 类型 | 是否必选 | 描述 | 示例值 |
SceneId | Long | 是 | 认证场景ID。 | 1000000006 |
CertifyId | String | 是 | 实人认证唯一标识。 | 91707dc296d469ad38e4c5efa6a0f24b |
返回数据
名称 | 类型 | 描述 | 示例值 |
RequestId | String | 请求ID。 | 130A2C10-B9EE-4D84-88E3-5384FF039795 |
Message | String | 请求消息的响应信息。 | success |
Code | String | 返回码。关于返回码的详细说明,请参见返回Code和Message。 | 200 |
ResultObject.Passed | String | 认证结果。取值:
说明 判断认证结果请以ResultObject.Passed字段为准。 | T |
ResultObject.SubCode | String | 认证结果描述。详情请参见返回Code和Message。 说明 判断认证结果请以ResultObject.Passed字段为准。 | 200 |
ResultObject.IdentityInfo | String | 认证的主体信息,一般的认证场景返回为空。 | null |
ResultObject.DeviceRisk | String | 设备风险标签。 | VirtualBrowser 说明 多个设备风险标签以半角逗号(,)分隔。如需了解更多设备风险标签及其含义,请参见人脸保镖标签说明。 |
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"}, "procedurePriorityResult":"keep"} |
ResultObject.UserInfo | String | 记录在生僻字模式下用户输入的身份信息与对应编码。返回数据为JSON格式字符串,姓名中无生僻字返回为空字符串。
| { "number":"610***********1110", "name":"王先生", "verifyName":"王先" } |
判断认证结果请以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 // 降级标识字段(仅当deviceType是h5时返回)Keep-未降级;url-该笔认证用户触发了URL降级完成认证;video-该笔认证用户触发了视频降级完成认证 "procedurePriorityResult":"keep" }, }
ResultObject.SubCode错误码说明,请参见ResultObject.SubCode错误码说明。
verifyScore阈值说明
千分之一误识率
万分之五误识率
万分之一误识率
十万分之五误识率
十万分之一误识率
70
71.5
75
76.5
80
说明如果您有个性化需求,您可以根据业务情况,参考返回的比对分和阈值,自定义认证结果。
返回Code和Message说明,请参见返回Code和Message。
SDK调用示例
在基于阿里云OpenAPI进行二次开发前,您可以通过OpenAPI门户提供的网页或命令行方式,预先验证OpenAPI请求方式,入参和查看OpenAPI的返回结果。当调用出错时,OpenAPI 门户会提示您如何解决,帮助您快速了解OpenAPI功能及使用方法。
在使用金融级实人认证服务之前,您需要开通服务。具体操作,请参见开通金融级实人认证服务。
在集成SDK前,您需要创建一个用户调用SDK的用户身份,获取身份关联的OpenAPI访问凭据,并授予访问云上资源的访问权限。如何创建和授权RAM用户,以及如何生成用于调用服务的AccessKey,请参见授权RAM用户访问服务。
认证场景指您的用户使用金融级实人认证服务完成用户实人认证的不同场景,例如,登录、支付等。您可以添加一个或多个场景,并为不同的场景配置不同的认证方案。调用InitFaceVerify发起认证请求时,需要传输认证场景ID。如何添加认证场景并获取认证场景ID, 请参见添加认证场景。
集成SDK并编写代码(以Java语言为例,要求JDK 1.8及以上版本)。
在pom.xml中添加如下依赖,即可在Maven工程中使用SDK。
Java SDK依赖。以下依赖版本仅供参考,建议在实际配置时获取最新依赖版本。
<dependency> <groupId>com.aliyun</groupId> <artifactId>cloudauth20190307</artifactId> <version>2.5.0</version> </dependency>
身份验证依赖。请查看ChangeLog.txt获取所有已发布的版本列表(建议使用最新的版本)。
<dependency> <groupId>com.aliyun</groupId> <artifactId>credentials-java</artifactId> <version>LATEST</version> </dependency>
说明本示例通过阿里云Credentials工具从环境变量中读取AccessKey,来实现API访问的身份验证。您需要提前在系统配置环境变量,具体操作,请参见身份验证配置。
接口调用示例。
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(100000xxxxL); // 设置商户请求的唯一标识。 request.setOuterOrderNo("xxxx"); // 认证方案。 request.setProductCode("ID_PRO"); // 模式。 request.setModel("LIVENESS"); request.setCertType("IDENTITY_CARD"); request.setCertName("张先生"); request.setCertNo("xxxx"); // MetaInfo环境参数。 request.setMetaInfo("{}"); //业务页面回跳的目标地址。 request.setReturnUrl("https://www.aliyundoc.com"); //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); } }
- 本页导读