文档中心

身份认证接入全流程详解

最近更新时间：2024.04.19 17:03:42

首次发布时间：2024.04.19 17:03:42

效果展示

上传及输入步骤均可通过配置进行跳过

准备工作

火山账号注册、实名认证、新建角色、新建用户

账号注册

打开火山引擎官网，单击右上角【立即注册】
按照提示依次填入信息即可完成注册。更多详情，请参考火山引擎账号注册

实名认证

1个个人主体支持实名认证10个火山引擎账号；1个企业主体支持实名认证100个火山引擎账号。

使用已注册的火山引擎账号登录火山引擎官网
单击右上角账号名下拉框中的【账号管理】进入对应页面
单击左侧导航中的【实名认证】，根据实际情况选择个人或者企业，并填写对应表单或上传相关材料完成实名认证。更多详情，请参考实名认证

新建角色

打开火山引擎官网，单击右上角控制台，进入后再将鼠标移动到右上角用户头像，单击访问控制
在访问控制界面，点击左侧角色，再点击新建角色
信任身份类型选择账号，选择身份选择当前账号，点击下一步
填写角色名和其他信息，点击下一步
策略名选择STSAssumeRoleAccess和CVFullAccess，点击提交，完成角色创建

记录角色名，以备后续流程使用。

新建用户(子账号)

在访问控制界面，点击左侧身份管理，并点击用户，再点击新建用户
点击通过用户名创建，输入用户名并点击下一步完成用户创建
找到上述刚创建的用户，点击管理，进入管理页面
1. 点击权限->添加权限，权限选择STSAssumeRoleAccess和CVFullAccess
2. 点击密钥，再点击新建密钥，获取到子账户密钥

记录密钥(AK/SK)，以备后续流程使用。

身份认证能力开通

打开火山引擎官网，单击右上角控制台，进入后点击左上角导航栏列表，找到搜索框输入 人像人体，点击即可进入视觉智能控制台

进入视觉智能控制台后，点击 去创建，填写相应信息，接入能力勾选 身份认证，点击创建应用

点击左侧 产品服务->身份认证，确认服务状态已处于 免费试用 中。
1. 如有需要，点击 正式调用 即可付费调用
2. 若需要让用户上传身份证件正反面，则按需开通 身份证识别服务

至此，身份认证服务已成功开通完成，前置准备工作已完成，下面将进入接入阶段。

正式接入

支持两种接入形态：H5、SDK

H5接入(支持浏览器+小程序+APP)：https://www.volcengine.com/docs/6973/1209428
SDK(IOS+Android)接入详细方案：https://www.volcengine.com/docs/6973/337548

注：H5方案，因抖音限制暂不支持接入抖音小程序，如需接入抖音小程序，可使用抖音实名SDK接入

微信小程序H5实现活体认证

生成活体URL链接

URL示例：https://h5-v2.kych5.com?accessKeyId=xxx&secretAccessKey=xxx&sessionToken=xxx&configId=xxx&bytedToken=xxx&lng=xxx

确定认证流程

需要客户上传身份证正反面
- 使用火山提供的OCR身份证识别能力(单独计费)
  - OCR上传图片识别 + 输入身份证号和姓名 + 人脸认证
  - OCR上传图片识别 + 人脸认证
- 不使用火山OCR，使用已有OCR能力
  - 前置调用其他平台OCR + 输入身份证号和姓名 + 人脸认证
  - 前置调用其他平台OCR + 人脸认证
不需要客户上传身份证正反面
- 输入身份证号和姓名 + 人脸认证
- 人脸认证

以下过程以 **仅做人脸认证(活体) **为例

引入后端服务SDK或直接使用签名Demo

身份认证提供了多种主流语言接入，包含 Java、Python、Go 等，SDK及签名Demo地址：

使用SDK: (直接搜索Action或ReqKey即可找到对应方法)
- Java
- Python 
- Go
- php

直接API请求，签名Demo：https://github.com/volcengine/volc-openapi-demos/tree/main/signature

以 Java 为例：

SDK：推荐通过Maven依赖使用火山引擎SDK for Java

<dependency>
    <groupId>com.volcengine</groupId>
    <artifactId>volc-sdk-java</artifactId>
    <version>最新版本</version>
</dependency>

签名Demo：https://github.com/volcengine/volc-openapi-demos/blob/main/signature/java/Sign.java

后端调用AssumeRole获取临时密钥

https://www.volcengine.com/docs/6257/86374

使用SDK的调用Demo

获取到 ak、sk、sts_token(即AssumeRole返回的SessionToken)
RoleTrn取值说明：格式为trn:iam::${AccountId}:role/${RoleName}。其中${AccountId}需要填入角色所属的主账号ID，${RoleName}需要填入实际的角色名称。例如账号ID为2000012345的账号内角色名为myRole的角色对应的RoleTrn为trn:iam::2000012345:role/myRole

package com.volcengine.example.sts;

import com.alibaba.fastjson.JSON;
import com.volcengine.model.request.AssumeRoleRequest;
import com.volcengine.model.response.AssumeRoleResponse;
import com.volcengine.service.sts.ISTSService;
import com.volcengine.service.sts.impl.STSServiceImpl;

public class AssumeRoleDemo {

    public static void main(String[] args) throws Exception {
        ISTSService stsService = STSServiceImpl.getInstance();

        stsService.setAccessKey("your ak");
        stsService.setSecretKey("your sk");

        AssumeRoleRequest request = new AssumeRoleRequest();
        request.setRoleSessionName("just_for_test");
        request.setDurationSeconds(900);
        request.setRoleTrn("trn:iam::yourAccountID:role/yourRoleName");

        AssumeRoleResponse resp = stsService.assumeRole(request);
        System.out.println(JSON.toJSONString(resp));
    }
}

后端调用CertH5ConfigInit配置套餐

https://www.volcengine.com/docs/6973/1209467

特殊参数说明

**h5_config.type：**设置业务场景，此案例取值"3"，代表直接进入活体认证
- 0：火山OCR上传图片识别 + 输入身份证号和姓名 + 人脸认证
- 1：直接进入输入身份证号和姓名 + 人脸认证
- 2：直接进入火山OCR上传图片识别 + 人脸认证
- 3：直接进入人脸认证
liveness_config.ref_source：比对方式(有源取"1"or无源取"0")，此案例取值**"1"**
- 仅h5_config.type=="3"直接做活体才支持无源认证

// 完整请求入参示例：
{
    "req_key": "cert_h5_config_init",
    "h5_config": {
        "type": "3",
        "theme_color": "rgba(56, 123, 255, 1)",
        "show_guide": "1",
        "show_result": "1",
        "protocol_name": "测试协议",
        "protocol_link": "www.volcengine.com",
        "enable_record": "1",
        "redirect_url": "www.volcengine.com"
    },
    "liveness_config": {
        "ref_source": "1",
        "liveness_type": "motion",
        "liveness_timeout": 10,
        "motion_list": [
            "0",
            "1",
            "2",
            "3"
        ],
        "fixed_motion_list": [
            "0"
        ],
        "motion_count": 2,
        "max_liveness_trial": 10
    }
}

使用SDK的调用Demo

获取"config_id":"64490c8a-c7fa-440d-932b-901718bf0120"，有效期15min

package com.volcengine.example.visual;

import com.alibaba.fastjson.JSON;
import com.volcengine.service.visual.IVisualService;
import com.volcengine.service.visual.VisualDefaultClient;
import com.volcengine.service.visual.model.request.VisualCertConfigInitRequest;
import com.volcengine.service.visual.model.request.VisualCertH5ConfigInitRequest;
import com.volcengine.service.visual.model.response.VisualCertConfigInitResponse;
import com.volcengine.service.visual.model.response.VisualH5CertConfigInitResponse;

public class CertH5ConfigInitDemo {

    public static void main(String[] args) {
        //获取IVisualService新实例
        //IVisualService visualService = VisualServiceImpl.getInstance();
        //获取全局的IVisualService实例
        IVisualService visualService = VisualDefaultClient.iVisualService;

        // call below method if you dont set ak and sk in ～/.vcloud/config

        visualService.setAccessKey("");
        visualService.setSecretKey("");

        VisualCertH5ConfigInitRequest request=new VisualCertH5ConfigInitRequest();
        request.setReqKey("cert_h5_config_init");
        VisualCertH5ConfigInitRequest.H5Config h5Config=new VisualCertH5ConfigInitRequest.H5Config();
        h5Config.setType("3");
        h5Config.setThemeColor("rgba(56, 123, 255, 1)");
        h5Config.setShowGuide("1");
        h5Config.setProtocolName("测试协议");
        h5Config.setProtocolLink("www.volcengine.com");
        h5Config.setEnableRecord("1");
        h5Config.setRedirectUrl("www.volcengine.com");
        request.setH5Config(h5Config);

        VisualCertH5ConfigInitRequest.LivenessConfig livenessConfig=new VisualCertH5ConfigInitRequest.LivenessConfig();
        livenessConfig.setRefSource("1");
        livenessConfig.setLivenessType("motion");
        request.setLivenessConfig(livenessConfig);
        request.setTosConfig(null);
        request.setCallbackInfo(null);
        try {
            VisualH5CertConfigInitResponse response = visualService.certH5ConfigInit(request);
            System.out.println(JSON.toJSONString(response));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

后端调用CertToken获取byted_token(唯一认证标识)

https://www.volcengine.com/docs/6973/1209468

特殊参数说明

h5_config_id：第三步生成的套餐ID，confi_id
idcard_name 和idcard_no：身份证姓名及身份证号，有源比对时必须填写
ref_image：基准图Base64，无源比对时必须填写

// 完整请求参数示例：
{
    "req_key":"cert_h5_token",
    "h5_config_id":"d6f04739-644e-4ff0-axxe-0299a852a2cc",
    "sts_token":"nCgdqdEROend3.Chxxx",
    "idcard_name":"xxxx",
    "idcard_no":"xxx"
    //"ref_image":"/9xxx"
}

使用SDK的调用Demo

"byted_token":"202401312053219F6F6C25DD5C087C5EE9"，有效期为60分钟(仅支持认证一次，禁止重复认证)

package com.volcengine.example.visual;

import com.alibaba.fastjson.JSON;
import com.volcengine.service.visual.IVisualService;
import com.volcengine.service.visual.VisualDefaultClient;
import com.volcengine.service.visual.model.request.VisualCertTokenRequest;
import com.volcengine.service.visual.model.request.VisualH5TokenRequest;
import com.volcengine.service.visual.model.response.VisualCertTokenResponse;
import com.volcengine.service.visual.model.response.VisualH5TokenResponse;

import java.util.ArrayList;

public class CertH5TokenDemo {

    public static void main(String[] args) {
        //获取IVisualService新实例
        //IVisualService visualService = VisualServiceImpl.getInstance();
        //获取全局的IVisualService实例
        IVisualService visualService = VisualDefaultClient.iVisualService;

        visualService.setAccessKey("");
        visualService.setSecretKey("");

        VisualH5TokenRequest visualCertTokenRequest=new VisualH5TokenRequest();
        visualCertTokenRequest.setReqKey("cert_h5_token");
        visualCertTokenRequest.setH5ConfigId("64490c8a-c7fa-440d-932b-901718bf0120");
        visualCertTokenRequest.setStsToken("xxx");
        visualCertTokenRequest.setIdcardName("your-name");
        visualCertTokenRequest.setIdcardNo("your-id");
        //visualCertTokenRequest.setRefImage("/xxxx");
        try {
            VisualH5TokenResponse response = visualService.certH5Token(visualCertTokenRequest);
            System.out.println(JSON.toJSONString(response));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

拼接H5链接

https://h5-v2.kych5.com?accessKeyId=xxx&secretAccessKey=xxx&sessionToken=xxx&configId=xxx&bytedToken=xxx&lng=xxx

https://h5-v2.kych5.com?accessKeyId=AKTP07erCjIaHo6QbfbbKn5JgYlz5boXl71Y54aEKkF3S&secretAccessKey=IChCiaXLaCvJR9E54ACe7Q2aOuhUk6Q0d8CURezzIUD&sessionToken=nCgdqdEROend3.ChsKBzNzX056d3cSEKBEK-Ie4EE1geeeEk5qhiIQ2s6EsAYYmqCHsAYg4a226QcoBDDytlI6FkFkbWluL0x6aFRlbXBBY2Nlc3NLZXlCBFVzZXJSEEx6aFRlbXBBY2Nlc3NLZXlYAg.eKU2dNYr6IsPjK0H8VG5qy8YtXFYPH4VNMmVC9sX4196-sKlkYUV4T64ibFQpti3PxMRG_ran1cZboTm9W1nMA&configId=7b208cb3-f434-41c7-b325-05fed0064830&bytedToken=202403251527226B0CC945517FEDD7A5B8&lng=zh

使用小程序`web-view`组件承载H5页面

在微信小程序、支付宝小程序环境中，接入身份认证H5增强版比较特殊，需要使用小程序web-view组件的方式来承载H5页面。

配置业务域名

登录小程序后台 -> 开发管理->开发设置->业务域名（业务自有域名），点击新增，按照要求配置业务域名。
如果有任何问题可以查询相关的文档：微信小程序 web-view 组件官方文档

请求转发配置

无法直接使用身份认证服务提供的h5-v2.kych5.com域名，因此需要将该域名下的资源转发到可访问的业务域名。
方案一：通过Nginx转发服务

location ^~/ {
    proxy_set_header Accept-Encoding "";
    proxy_set_header Referer "https://h5-v2.kych5.com/";
    proxy_pass https://h5-v2.kych5.com/;
    add_header Access-Control-Allow-Origin *;
}
nginx

方案二：通过Nodejs转发服务

const express = require("express");
const https = require("https");
const http = require("http");
const fs = require("fs");
const request = require("request");

// 业务域名
const HOST = "xxx.com";
// 目标域名
const TargetHost = "h5-v2.kych5.com";
// 完整域名
const Target = `https://${TargetHost}`;

// 读取SSL密钥和签名证书
const options = {
    cert: fs.readFileSync("./https/cert.pem", "utf8"),
    key: fs.readFileSync("./https/key.pem", "utf8"),
};

// 创建web服务
const app = express();
// 注册https监听
const httpsServer = https.createServer(options, app);
// 注册http监听
const httpServer = http.createServer(app);

app.use(express.urlencoded({ extended: true }));

app.all("*", (req, res) => {
    const options = {
        url: `${Target}${req.originalUrl}`,
        method: req.method,
        headers: {
            ...req.headers,
            host: TargetHost,
            origin: req.headers.origin ? Target : undefined,
            referer: req.headers.referer?.replace(HOST, TargetHost),
            "accept-encoding": undefined,
        },
        form: req.rawHeaders.includes(
            "application/x-www-form-urlencoded"
        )
            ? req.body
            : undefined,
    };
    request(options, (err, response, body) => {
        res.send(body);
    })
})

// https监听
httpsServer.listen(443, () => {
    console.log("https://" + HOST);
});
// http监听
httpServer.listen(80, () => {
    console.log("http://" + HOST);
});

小程序加载访问

将生成的H5链接配置到小程序中即可。

认证结束

当结束认证后，身份认证H5会在redirect_url地址后面拼接相关的参数，业务侧可解析参数获取认证结果。

/** 拼接示例 **/
${redirect_url}?resultCode=xxx&algorithmBaseRespCode=xxx&reqMeasureInfoValue=xxx&bytedToken=xxx

认证结束后的回调参数方案
**方案一：**认证结束后将认证结果拼接到redirect_url参数上，H5内部会调用小程序JS API对应的redirectTo方法，关闭web-view组件并返回小程序页面（推荐使用）

微信小程序redirect_url格式，以wxmini:开头：wxmini:/pages/path1/path2?query1=xx

**方案二：**使用https链接（不建议使用）

业务侧需要单独提供一个H5页面，并将其作为redirect_url参数。
认证结束跳转到redirect_url页面，由业务侧主动调用小程序API关闭web-view组件。

效果展示

准备工作

火山账号注册、实名认证、新建角色、新建用户

账号注册

实名认证

新建角色

新建用户(子账号)

身份认证能力开通

正式接入

微信小程序H5实现活体认证

生成活体URL链接

使用小程序web-view组件承载H5页面