效果展示上传及输入步骤均可通过配置进行跳过
准备工作
火山账号注册、实名认证、新建角色、新建用户
账号注册打开火山引擎官网，单击右上角【立即注册】按照提示依次填入信息即可完成注册。更多详情，请参考 火山引擎账号注册
实名认证1个个人主体支持实名认证10个火山引擎账号；1个企业主体支持实名认证100个火山引擎账号。使用已注册的火山引擎账号登录火山引擎官网单击右上角账号名下拉框中的【账号管理】进入对应页面单击左侧导航中的【实名认证】，根据实际情况选择个人或者企业，并填写对应表单或上传相关材料完成实名认证。更多详情，请参考 实名认证
新建角色打开火山引擎官网，单击右上角控制台，进入后再将鼠标移动到右上角用户头像，单击访问控制在访问控制界面，点击左侧角色，再点击新建角色信任身份类型选择账号，选择身份选择当前账号，点击下一步填写角色名和其他信息，点击下一步策略名选择STSAssumeRoleAccess和CVFullAccess，点击提交，完成角色创建记录角色名，以备后续流程使用。
新建用户(子账号)在访问控制界面，点击左侧身份管理，并点击用户，再点击新建用户点击通过用户名创建，输入用户名并点击下一步完成用户创建找到上述刚创建的用户，点击管理，进入管理页面
点击权限->添加权限，权限选择STSAssumeRoleAccess和CVFullAccess点击密钥，再点击新建密钥，获取到子账户密钥记录密钥(AK/SK)，以备后续流程使用。
身份认证能力开通打开火山引擎官网，单击右上角控制台，进入后点击左上角导航栏列表，找到搜索框输入 人像人体，点击即可进入 视觉智能控制台进入 视觉智能控制台 后，点击 去创建，填写相应信息，接入能力勾选 身份认证，点击创建应用点击左侧 产品服务->身份认证，确认服务状态已处于 免费试用 中。
如有需要，点击 正式调用 即可付费调用若需要让用户上传身份证件正反面，则按需开通 身份证识别服务至此，身份认证服务已成功开通完成，前置准备工作已完成，下面将进入接入阶段。
正式接入支持两种接入形态：H5、SDK
H5接入(支持浏览器+小程序+APP)：https://www.volcengine.com/docs/6973/1209428SDK(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
签名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，config_ididcard_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组件。