发起认证请求

描述

接口名称： 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 传递图片的时候，接口的请求方法需要改成 POST；图片 base64 字符串需要去掉头部描述，如data:image/png;base64,。

请求参数

返回参数

VerifyToken 参数结构

STSToken 参数结构

错误码说明

示例

使用 SDK 开发包示例

参看 SDK 开发包使用文档中的认证方案示例：Java、PHP、Python、.NET、Node.js、Go

拼接 HTTPS 请求示例

请求示例

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

返回示例

XML 格式：

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

JSON 格式：

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

附录

扩展参数 Binding 说明

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

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

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

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

Binding内容：

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

使用 STSToken 上传文件示例

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

1. 使用 OSS SDK 上传图片

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

Java 语言：

String bucketName = uploadToken.bucketName;
String endpoint = uploadToken.endpoint;
String accessKeyId = uploadToken.accessKeyId;
String accessKeySecret = uploadToken.accessSecret;
String token = uploadToken.token;
// 初始化客户端
OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret, token);
String fileKey = uploadToken.path + "face.jpg";  //  c3fef70f36ca4b0d8203a499beaa9f80/face.jpg
byte[] content = getBytesOf("face.jpg");
// 上传图片
ossClient.putObject(bucketName, fileKey, content);
// 关闭client
ossClient.shutdown();

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

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

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

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