全部产品
弹性计算 会员服务 网络 安全 移动云 数加·大数据分析及展现 数加·大数据应用 管理与监控 云通信 阿里云办公 培训与认证 ET大脑 更多
存储与CDN 数据库 域名与网站(万网) 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 智能硬件

发起认证请求

更新时间:2018-07-25 09:53:13

描述

接口名称GetVerifyToken

功能描述: 每次开始认证前通过GetVerifyToken接口获取认证 Token,VerifyToken参数用来串联认证请求中的各个接口。

名词解释

  • 业务场景 Biz: 表示使用实人认证服务的业务场景,请先参考 业务设置 在控制台上完成创建。
  • 认证 ID TicketId: 标识一次认证任务的唯一 ID,通常由业务使用方指定,方便关联业务场景的其他内容。一次认证任务,系统支持无限次发起提交,直到最终认证通过该任务完结。

    注意:发起不同的认证任务时需要更换不同的认证 ID。

  • 图片地址格式: 用来告诉实人认证服务如何获取到图片,图片地址描述有以下几种模式:
    • http: 一个可访问的公网 HTTP 地址,例如 http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg
    • oss: 一个可公开访问的 OSS 文件地址,格式为 oss://<bucket>:<path_to_file>
    • base64: 一个 base64 编码的图片,格式为 base64://<图片 base64 字符串>

      注意

      • 不支持本地图片的相对路径或绝对路径。
      • 单张图片大小请控制在 2M 内,避免算法拉取超时。
      • 单个请求的 Body 有 8M 的大小限制,请计算好请求中所有图片和其他信息的大小,不要超限。
      • 使用 base64 传递图片的时候,SubmitMaterials的请求方法需要改成 POST;图片 base64 字符串需要去掉头部描述,如data:image/png;base64,

请求参数

名称 类型 是否必须 描述
Action String 系统规定参数。取值: GetVerifyToken
RegionId String 系统规定参数。取值: cn-hangzhou
Biz String 参看名词业务场景
TicketId String 参看名词认证 ID
Binding String 认证扩展材料(JSON 格式),请参考 扩展参数 Binding 说明
UserData String 业务数据(JSON 格式),通常用来传递业务上下文内容。

返回参数

名称 类型 是否必须 描述
VerifyToken Map VerifyToken 参数,用来串联认证请求中的各个接口。
StsToken Map STSToken 参数,如果业务方有额外的文件需要一并提交认证服务,可以使用STSToken参数上传到认证服务指定的地方。请参考 使用 STSToken 上传文件示例
CloudauthPageUrl String 认证流程页面入口 URL,H5+服务端接入的认证方案需要关心此字段,用作前端 H5 跳转到认证流程的 URL。

VerifyToken 参数结构

名称 类型 是否必须 描述
Token String 一次认证会话的标识。
DurationSeconds Integer 认证会话超时时间,单位秒(s),一般为1800s。

STSToken 参数结构

名称 类型 是否必须 描述
AccessKeyId String OSS access key ID。
AccessKeySecret String OSS access key secret。
Expiration String STS token 过期时间。
EndPoint String OSS endpoint。
BucketName String OSS bucket,认证服务指定的文件上传 Bucket。
Path String path 通常是一个认证请求生成的用来上传的目录,业务方需要将文件上传到这个目录。
Token String STS 访问 Token。

错误码说明

错误代码 英文描述 中文描述 HTTP 状态码
Error.InternalError The request processing has failed due to some unknown error. 服务内部出现未知错误,请联系技术支持排查。 500
InvalidParam.ParamMissing Please check if there is param empty in your imput 参数错误,请检查参数是否为空。 400
Error.NoPermissionAccess No permission to access our service 没有权限访问服务,请确认是否服务已开通。 403
InvalidParam.InvalidBiz The biz is not valid 参数Biz不合法,请与控制台上创建的保持一致。 400

示例

使用 SDK 开发包示例

参看 SDK 开发包使用文档中的认证方案示例:JavaPHPPython.NETNode.jsGo

拼接 HTTPS 请求示例

请求示例

  1. https://cloudauth.aliyuncs.com/?Action=GetVerifyToken
  2. &RegionId=cn-hangzhou
  3. &Biz=RPBasic
  4. &TicketId=39ecf51e-2f81-4dc5-90ee-ff86125be683
  5. &Binding=%7B%22Name%22%3A+%22%E6%9D%8E%E4%B8%89%22%7D
  6. &UserData=%7B%22orderId%22%3A+%221391012388%22%7D
  7. &<[公共请求参数]>

返回示例

XML 格式:

  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <GetVerifyTokenResponse>
  3. <Data>
  4. <StsToken>
  5. <AccessKeySecret>OSSAccessKeySecret</AccessKeySecret>
  6. <BucketName>verify-external-image</BucketName>
  7. <AccessKeyId>OSSAccessKeyID</AccessKeyId>
  8. <Expiration>2017-09-14T02:28:20Z</Expiration>
  9. <EndPoint>https://oss-cn-shanghai.aliyuncs.com</EndPoint>
  10. <Token> CAIS2QJ1q6Ft5B2yfSjIpojNLPyNqehJ4I7dUWLptzMUfs1qvaDDujz2IHpFenBqBuActP8xmWFW5v0Slol5QZFLHhecNZop4pkLoQj8M9fL5Zfq4+Rf0sb6EDafAUZiUXtL7KarIunGc9KBNno2/00amMkGHFfPdlihNoLzxvwDR98LXw6+QCNbDdNNXGVLo9MbMn2jUpTINQXx0FLNEG1iuAd3lRl1i8KFz9ab9wDVgXDj1+YRvP6RGJW/aNR2N5oNfbWZ1edtJK3ay3wSuVoY6qpsjaJVvDrXotyHBVBVphSDOuXZtddlIgEiPfBiSvdIoaSsnqAo5+aNzNv5k00XZr5cDSjVA8KCuJKeQ7P1aI9nKOigaimSgoC1W8Or419+UxUyLxhXftctEHh0BCE3RyvSQq3dowqbPF75FPjfivpojMsrnw6457uQLl3KXK+YzSsI3he3n9aLxnQagAGuwJ7ORAZMwZm0UqNZ9uICFM2L39GX6/H22KDq2BYGO4bMcS49V+CuBuzTK1MEgRE5ELfBq6ttk4/Arah6gUomug6Yi8ZZCl0Zghgl36j5FEHeOYMS/RGnyiLVhRb+biHoncq/PsD/m8bv3VVQIcKQQ9gF71+WzebokSmhSw3A7w==
  11. </Token>
  12. <Path>bbff330091de48c585b637f03237a6db/</Path>
  13. </StsToken>
  14. <VerifyToken>
  15. <DurationSeconds>1800</DurationSeconds>
  16. <Token>bbff330091de48c585b637f03237a6db</Token>
  17. </VerifyToken>
  18. <CloudauthPageUrl>https://h5.m.taobao.com/user_verify/cloudauth.html?token=1234567890abcdefg</CloudauthPageUrl>
  19. </Data>
  20. <Success>true</Success>
  21. <Code>1</Code>
  22. </GetVerifyTokenResponse>

JSON 格式:

  1. {
  2. "Code": "1",
  3. "Data": {
  4. "StsToken": {
  5. "AccessKeyId": "OSSAccessKeyID",
  6. "AccessKeySecret": "OSSAccessKeySecret",
  7. "BucketName": "verify-external-image",
  8. "EndPoint": "https://oss-cn-shanghai.aliyuncs.com",
  9. "Expiration": "2017-09-09T13:01:32Z",
  10. "Path": "92790974cd384f29a949b47f1c4ca3a5/",
  11. "Token": "CAIS2QJ1q6Ft5B2yfSjIpKaGDuzDqJpP5vWfNhLY1mMPPfxphvPa1Dz2IHpFenBqBuActP8xmWFW5v0SlokiEcAUHR2bMcB8tcQL/1nwatud6sbpsrJdg8GuEDOaVkZoDUsP7aarIunGc9KBNno2/00amMkGHFfPdlihNoLzxvwDR98LXw6+QCNbDdNNXGVLo9MbMn2jUpTINQXx0FLNEG1iuAd3lRl1i8KFz9ab9wDVgXDj1+YRvP6RGJW/aNR2N5oNfbWZ1edtJK3ay3wSuVoY6qpsjaJVvDrXotyHBVBVphSDOuXZtYw1c14hN/dmEKIf/KTyz6xx67CCndioxU9GYepcCC2CA8KCuJKeQ7P1aI9nKOigaimSgoC1W8Or419+UxUyLxhXftctEHh0BCE3RyvSQq3dowqbPF75FPjfivpojMsrnw6457uQLl3KXK+YzSsI3he3n9aLxnQagAGferYB1UMADL0LyW3Bd91xmtePTfJD8QszrYAladv2D7CxsqP7jdBoJ6gRQoE9U0NEibHGjFeNZ3C8VN5kmnU+aY6lnwgcz+7nEXBnrh4hl56ubNXb8Tkx5LDEbfXrZmnfv5LbuUn+79OkvQPQvfmL3xM+7ciWyAzmeBBGTIdf8w=="
  12. },
  13. "VerifyToken": {
  14. "Expire": 1800,
  15. "Token": "92790974cd384f29a949b47f1c4ca3a5"
  16. },
  17. "CloudauthPageUrl": "https://h5.m.taobao.com/user_verify/cloudauth.html?token=1234567890abcdefg"
  18. },
  19. "Success": true
  20. }

附录

扩展参数 Binding 说明

部分场景中,业务方在发起认证请求前已经收集了一部分认证资料,需要传递给实人认证服务,这种情况下就需要使用Binding扩展参数,目前支持 Binding 的认证资料有如下几种:

  • Name: 姓名,取值为字符串,例如 李三
  • IdentificationNumber: 身份证号,取值为字符串,例如 630546198009090099
  • IdCardFrontPic: 身份证人像面照片,取值为字符串,格式请参考图片地址格式
  • IdCardBackPic: 身份证国徽面照片,取值为字符串,格式请参考图片地址格式
  • FacePic: 人像照,取值为字符串,格式请参考图片地址格式
  • IDPic: 二代身份证芯片中存储的头像照片,取值为字符串,格式请参考图片地址格式

    注意:以上传入哪几个字段,视您选择的认证方案和实际业务需求而定,请参看 认证方案 中的说明。

应用举例:业务方在自己的业务流程中已经采集了用户的姓名身份证号身份证人像面照片身份证国徽面照片,而希望使用实人认证服务对用户进行活体检测并确认是本人操作。在这种情况下,就需要在发起认证请求时使用Binding参数指定这些采集到的数据:

Binding内容:

  1. {
  2. \"Name\": \"李三\",
  3. \"IdentificationNumber\": \"584129192830192233\",
  4. \"IdCardFrontPic\": \"http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg\",
  5. \"IdCardBackPic\": \"base64:///9j/4AAQSkZJRgABAQEASABIAAD/2...\"
  6. }

使用 STSToken 上传文件示例

为了让业务方能够将图片上传到实人认证服务指定的 OSS Bucket 中,需要使用 OSS 提供的安全凭证管理(Security Token Service,简称 STS)功能来完成。STS 能够依据 bucket owner 指定的访问策略生成一个临时的 STS token 给业务方作为临时上传文件使用的凭据。关于 STS 的更多信息,请参考 OSS访问控制

1. 使用 OSS SDK 上传图片

例如,有一张人脸图片名字为 face.jpg,需要上传到实人认证服务进行比对,可以参考以下处理流程:

Java 语言:

  1. String bucketName = uploadToken.bucketName;
  2. String endpoint = uploadToken.endpoint;
  3. String accessKeyId = uploadToken.accessKeyId;
  4. String accessKeySecret = uploadToken.accessSecret;
  5. String token = uploadToken.token;
  6. // 初始化客户端
  7. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret, token);
  8. String fileKey = uploadToken.path + "face.jpg"; // c3fef70f36ca4b0d8203a499beaa9f80/face.jpg
  9. byte[] content = getBytesOf("face.jpg");
  10. // 上传图片
  11. ossClient.putObject(bucketName, fileKey, content);
  12. // 关闭client
  13. ossClient.shutdown();

2. 使用 SubmitMaterials 接口上传 OSS 文件给实人认证服务

在与 OSS 对接成功上传图片后,获取到图片的文件路径(例如,c3fef70f36ca4b0d8203a499beaa9f80/face.jpg)。然后,需要将此图片的文件路径地址告知实人认证服务端。

对于已成功上传至 OSS 的图片,传递给实人认证服务端的格式应为oss://<uploadToken.bucketName>:c3fef70f36ca4b0d8203a499beaa9f80/face.jpg

将此完整的图片文件名通过 提交认证资料(SubmitMaterials) 接口提交给实人认证服务即可。

本文导读目录