阿里云实人认证对接使用完全指南：从产品选型到代码落地

apphuang2026年07月04日 20:45:322

一、前言

在数字化浪潮席卷各行各业的今天，线上身份核验已经成为互联网业务合规运营的关键一环。从金融开户、网约车司机认证，到直播平台的主播实名、电商平台的支付验证，几乎每一个涉及资金或敏感信息的线上场景，都需要一套可靠的身份核验机制来回答三个核心问题：这个人是不是一个真实存在的人？这个人的身份信息是否与本人一致？这个操作是否由本人知情并自愿完成？阿里云实人认证服务正是为了解决这些场景应运而生的产品体系。

然而不少开发者在初次接触阿里云实人认证产品时，往往会被其较为庞杂的产品家族所困扰。实人认证、增强版实人认证、金融级实人认证这些名称之间究竟有什么区别？为什么有的叫eKYC有的叫活体检测？不同的接入方式如App SDK、H5网页、纯服务端API之间应该如何选择？本文将从零开始，系统梳理阿里云实人认证产品的全貌，并提供从开通、配置到代码落地的完整实操指南，帮助开发者少走弯路，快速完成身份核验能力的集成。

需要先登录阿里云控制台，点击：阿里云控制台

二、产品家族梳理与选型指南

在开始对接之前，首先需要搞清楚阿里云实人认证产品家族的整体架构。目前阿里云在身份核验领域提供了多款产品，但其中真正在售、功能持续更新的是金融级实人认证。旧版的实人认证和增强版实人认证均已停止售卖，功能也已收敛，建议新接入的业务统一使用金融级实人认证系列产品。

金融级实人认证产品在算法支持方面更为全面，支持眨眼活体、多动作活体、炫彩反光活体以及声纹活体等多种检测手段，同时还支持App SDK、PC或移动端H5网页、纯服务端API、支付宝小程序等多种接入方式。而旧版实人认证仅支持眨眼动作活体，在安全效果、个人隐私数据保护以及认证通过率方面，金融级版本均有显著提升，目前已广泛应用于互联网娱乐社交、政务、出行等行业。

金融级实人认证家族下主要包含以下几种核心产品方案，开发者需要根据自身业务场景进行选择：

金融级实人认证方案：功能最完整的方案，依托活体检测、生物识别、证件OCR识别等多项技术，配合权威数据源验证接口，完整校验终端用户的真实身份。这套流程涵盖了证件信息采集、活体检测、人脸比对、权威库核验等多个环节，输出最终的身份一致性结论。适合金融开户、主播实名、落实实名制等首次认证场景。
金融级多因子意愿认证方案：在身份认证的基础上增加了用户知情确认环节，用户在刷脸过程中需要回答系统提出的问题或朗读风险说明文件，从而验证操作是用户知情且自愿的。适用于高风险投资开户、大额交易、反电信诈骗等对意愿确认有强要求的场景。
金融级活体人脸验证方案：二次验证方案，不核验身份信息的真实性，而是通过活体检测技术确认当前操作用户是真人，并与系统内已经留底的历史人脸进行1:1比对。适合登录验证、支付确认等已实名用户的二次核验场景。
金融级活体检测方案：仅做活体检测，不涉及身份信息核验和人脸比对，适用于只需要确认操作者为真人的轻量级场景。
金融级NFC认证方案：通过读取证件内置芯片信息进行认证，安全性极高，适用于对防伪要求极高的场景。

三、开通服务与前置准备

3.1 开通金融级实人认证服务

接入实人认证服务的第一步是开通服务。具体操作步骤如下：

确保已注册阿里云账号并完成企业实名认证。实人认证服务面向企业客户提供，个人账号无法开通使用。
登录实人认证产品页面，点击立即开通金融级实人按钮。
在金融级实人认证（按量计费）页面，勾选服务协议并点击立即开通。
确保账号未欠费，如有需要可购买金融级实人认证流量包以享受更优惠的价格。

3.2 获取AccessKey

AccessKey是调用阿里云API的身份凭证，由AccessKeyId和AccessKeySecret组成。访问AccessKey管理页面，获取或创建所需的AccessKey。强烈建议使用RAM子账号的AccessKey而非主账号，以降低密钥泄露的风险。

3.3 创建RAM子账号并授权

为了安全调用实人认证API，需要创建RAM子账号并授予相应权限：

登录RAM控制台，点击创建用户，进入创建用户页面。
输入用户账号信息，选择编程访问方式以生成AccessKey。
授权策略至少需要AliyunYundunCloudAuthFullAccess（实人认证全量访问权限）。
如果认证结果需要保存人脸图片到OSS，还需授予OSS相关权限。

3.4 添加认证场景

认证场景是实人认证服务的核心配置单元，每个场景可以独立配置认证方案、活体检测方式、是否保存人脸图片等参数。在金融级实人认证控制台中，点击添加认证场景，根据业务需求填写场景名称、选择认证方案（如实人认证方案、活体人脸验证方案等），并配置相应的认证参数。

四、接入方式详解

阿里云金融级实人认证支持多种接入方式，主要包括App（SDK）接入、H5网页接入和纯服务端API接入三大类。开发者需要根据自身业务形态和技术栈选择合适的接入方式。

4.1 App（SDK）接入

App（SDK）接入适用于自身已有手机App应用，且希望通过该App对用户进行线上认证的场景。这种接入方式用户体验最佳，活体检测效果也最好，是大多数移动端业务的首选方案。

4.1.1 接入流程时序

App（SDK）接入的完整流程如下：

用户通过商家App发起业务流程。
App调用认证SDK获取MetaInfo环境参数。
认证SDK返回MetaInfo给App。
App向应用服务端发起认证请求并传递MetaInfo。
应用服务端向阿里云服务端调用Initialize接口发起认证请求。
阿里云服务端返回TransactionId给应用服务端。
应用服务端将TransactionId传递给App。
App调用认证SDK启动刷脸认证流程。
认证SDK将用户提交的认证资料（人脸视频、证件照片等）传递给阿里云服务端。
阿里云服务端根据资料判定认证结果，并将认证结果返回给SDK。
SDK通过回调函数指引App获取认证状态。
App向应用服务端查询认证状态。
应用服务端向阿里云服务端调用CheckResult接口查询认证结果。
阿里云服务端将认证结果及相关认证资料返回给应用服务端。
应用服务端对获取到的认证信息进行处理，将非敏感信息传递给App。

4.1.2 服务端代码示例（Java）

以下是一个完整的Java服务端实现示例，涵盖初始化认证和查询认证结果两个核心接口。

首先，在项目的pom.xml中添加依赖：

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>cloudauth20221125</artifactId>
    <version>1.2.0</version>
</dependency>
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>4.6.3</version>
</dependency>

服务端初始化接口调用示例：

import com.aliyun.cloudauth20221125.Client;
import com.aliyun.cloudauth20221125.models.InitFaceVerifyRequest;
import com.aliyun.cloudauth20221125.models.InitFaceVerifyResponse;
import com.aliyun.teaopenapi.models.Config;

public class RealNameAuthService {
    
    private static Client createClient(String accessKeyId, String accessKeySecret) throws Exception {
        Config config = new Config()
            .setAccessKeyId(accessKeyId)
            .setAccessKeySecret(accessKeySecret);
        config.setEndpoint("cloudauth.aliyuncs.com");
        return new Client(config);
    }
    
    public static InitFaceVerifyResponse initFaceVerify(
            String accessKeyId, 
            String accessKeySecret,
            String certifyId,
            String certifyUrl,
            String sceneId,
            String outerOrderNo) throws Exception {
        
        Client client = createClient(accessKeyId, accessKeySecret);
        InitFaceVerifyRequest request = new InitFaceVerifyRequest()
            .setCertifyId(certifyId)
            .setCertifyUrl(certifyUrl)
            .setSceneId(sceneId)
            .setOuterOrderNo(outerOrderNo)
            .setProductCode("ID_PRO")
            .setModel("FACE");
        
        return client.initFaceVerify(request);
    }
}

查询认证结果接口调用示例：

import com.aliyun.cloudauth20221125.models.DescribeFaceVerifyRequest;
import com.aliyun.cloudauth20221125.models.DescribeFaceVerifyResponse;

public class RealNameAuthResultService {
    
    public static DescribeFaceVerifyResponse describeFaceVerify(
            String accessKeyId,
            String accessKeySecret,
            String certifyId) throws Exception {
        
        Client client = createClient(accessKeyId, accessKeySecret);
        DescribeFaceVerifyRequest request = new DescribeFaceVerifyRequest()
            .setCertifyId(certifyId)
            .setSceneId(sceneId);
        
        return client.describeFaceVerify(request);
    }
}

4.1.3 服务端代码示例（Python）

Python开发者可以使用阿里云官方提供的Python SDK：

from alibabacloud_cloudauth20221125.client import Client
from alibabacloud_cloudauth20221125.models import InitFaceVerifyRequest, DescribeFaceVerifyRequest
from alibabacloud_teaopenapi.models import Config

def create_client(access_key_id, access_key_secret):
    config = Config(
        access_key_id=access_key_id,
        access_key_secret=access_key_secret,
        endpoint='cloudauth.aliyuncs.com'
    )
    return Client(config)

def init_face_verify(access_key_id, access_key_secret, scene_id, outer_order_no, certify_url):
    client = create_client(access_key_id, access_key_secret)
    request = InitFaceVerifyRequest(
        scene_id=scene_id,
        outer_order_no=outer_order_no,
        certify_url=certify_url,
        product_code='ID_PRO',
        model='FACE'
    )
    return client.init_face_verify(request)

def describe_face_verify(access_key_id, access_key_secret, certify_id):
    client = create_client(access_key_id, access_key_secret)
    request = DescribeFaceVerifyRequest(certify_id=certify_id)
    return client.describe_face_verify(request)

4.1.4 Android客户端集成示例

Android客户端需要集成阿里云提供的认证SDK。以下是一个简化的集成示例：

// 在build.gradle中添加依赖
implementation 'com.aliyun.aliyunface:aliyun-face-sdk:3.0.0'

// 在Activity中调用认证
public class CertifyActivity extends AppCompatActivity {
    
    private void startCertify(String certifyId) {
        // 创建认证参数
        FaceCertifyParam param = new FaceCertifyParam.Builder()
            .setCertifyId(certifyId)
            .setProtocol("https")
            .setHost("cloudauth.aliyuncs.com")
            .build();
        
        // 启动认证
        FaceCertifyManager.getInstance().startCertify(
            this,
            param,
            new FaceCertifyCallback() {
                @Override
                public void onSuccess(String certifyId, String status) {
                    // 认证成功，通知服务端查询最终结果
                }
                
                @Override
                public void onFailure(int code, String message) {
                    // 认证失败，处理错误
                }
            }
        );
    }
}

4.2 H5网页接入

H5网页接入适用于在浏览器或内嵌WebView中实现实人认证功能的场景。这种接入方式无需安装App，用户通过浏览器访问H5页面即可完成认证，适合PC端业务或没有App的轻量级场景。

4.2.1 接入流程

H5网页接入的流程与App SDK接入类似，区别在于客户端侧使用Web SDK而非原生SDK：

在H5页面中引入阿里云提供的Web SDK的JS文件。
调用getMetaInfo函数获取MetaInfo环境参数。
将MetaInfo传递给服务端，服务端调用Initialize接口获取TransactionId。
服务端将TransactionId返回给H5页面。
H5页面使用TransactionId启动刷脸认证流程。
认证完成后，服务端调用CheckResult接口获取最终认证结果。

4.2.2 H5前端代码示例

<!-- 引入Web SDK -->
<script src="https://g.alicdn.com/cloudauth/face-web-sdk/1.0.0/face-web-sdk.js"></script>

<script>
// 获取MetaInfo
function getMetaInfo() {
    return new Promise((resolve, reject) => {
        AliyunFaceWeb.getMetaInfo({
            success: function(metaInfo) {
                resolve(metaInfo);
            },
            fail: function(error) {
                reject(error);
            }
        });
    });
}

// 发起认证
async function startCertify() {
    try {
        // 1. 获取MetaInfo
        const metaInfo = await getMetaInfo();
        
        // 2. 调用服务端接口获取TransactionId
        const response = await fetch('/api/init-certify', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ metaInfo: metaInfo })
        });
        const data = await response.json();
        const transactionId = data.transactionId;
        
        // 3. 启动刷脸认证
        AliyunFaceWeb.startCertify({
            transactionId: transactionId,
            success: function(result) {
                // 认证成功
                console.log('认证通过', result);
            },
            fail: function(error) {
                // 认证失败
                console.error('认证失败', error);
            }
        });
    } catch (error) {
        console.error('认证流程异常', error);
    }
}
</script>

4.3 纯服务端API接入

纯服务端API接入适用于不需要客户端SDK交互的场景，例如后端系统对用户身份信息进行批量核验。这种接入方式不涉及活体检测，仅通过API调用核验姓名、身份证号等信息的真实性。阿里云为开发者提供了多种编程语言（Java、C#、Go、Python、Node.js/TypeScript、PHP、C++等）的SDK，开发者只需要集成SDK，通过SDK暴露的方法直接调用服务接口。SDK统一封装了签名逻辑、超时机制、重试机制，并根据文档返回结构化Response对象，易于开发。

五、生产环境安全加固策略

5.1 RAM最小权限授权

在生产环境中，应当遵循最小权限原则，为不同服务分配不同权限的RAM子账号。例如，负责发起认证的服务只需要cloudauth:InitFaceVerify权限，负责查询结果的服务只需要cloudauth:DescribeFaceVerify权限，而不需要授予全量权限。这样即使某个服务的AccessKey泄露，攻击者也无法执行超出权限范围的操作。

5.2 参数传输加密

所有与阿里云实人认证服务端的通信必须使用HTTPS协议，确保传输过程中的数据加密。同时，建议对服务端与客户端之间传递的敏感信息（如用户姓名、身份证号）进行额外的加密处理，防止中间人攻击。

5.3 敏感信息脱敏处理

在日志记录和调试过程中，应当对用户敏感信息进行脱敏处理。例如，身份证号只记录前六位和后四位，手机号只记录前三位和后四位，姓名只记录姓氏。这既能满足问题排查的需要，又能有效保护用户隐私。

5.4 回调地址白名单

在控制台配置认证场景时，可以设置回调地址白名单，只允许指定的域名接收认证结果回调，防止认证结果被恶意劫持。

六、计费逻辑与成本优化

6.1 计费方式

阿里云实人认证采用按天计费（后付费）的付费方式。费用由产品方案调用费与功能使用费两部分构成。各项服务的标准价如下：

实人认证（eKYC_PRO）：1美元/次，按成功调用次数计费。
活体检测（FACE_LIVENESS_PRO）：0.3美元/次，按成功调用次数计费。
人脸比对（FACE_COMPARE）：0.001美元/次，按成功调用次数计费。
证件OCR识别（ID_OCR_MAX）：0.5美元/次，按成功调用次数计费。
NFC识别（ID_NFC）：0.1美元/次，按成功调用次数计费。

需要注意的是，若用户未完成认证方案中要求的所有认证步骤而中途退出，则不计入调用次数。实人认证实行按天结算的模式，即按天出账，按天结算。账单出账时间通常在每一个自然日结束后10到12个小时内。

6.2 成本优化建议

对于调用量较大的业务，建议购买流量包以享受更优惠的价格。同时，合理设计认证流程，避免不必要的重复认证，也能有效控制成本。在调用Initialize接口发起请求后，建议在本地保存返回的TransactionId，方便后续核对账单。

七、常见报错排查

7.1 错误码1001：CertifyId无效

错误码1001通常是因为认证的CertifyId无效导致的。需要通过配套的服务端初始化接口获取认证的CertifyId，且保持该ID未被使用过。

7.2 错误码3206：非本人操作

认证时接口返回3206表示异常码，非本人操作。如出现此类问题，请确认是否是本人认证。如果是本人认证，可能是由于用户或者该设备存在多次提交认证，容易触发3206的风控策略，建议更换设备或者等待24小时后提交。

7.3 错误码2002：人脸识别未通过

错误码2002通常表示人脸识别未通过。请检查是否在光线充足且背景简单的环境中操作，或尝试重新进行身份验证。

7.4 错误码412：欠费

错误码412表示金融级实人认证或OSS存在欠费。请充值后操作。

7.5 错误码414：设备类型不支持

错误码414表示当前移动设备不支持刷脸认证。请更换设备后操作。

7.6 错误码427：触发内部风控策略

错误码427表示该身份因触发内部风控策略未完成认证。可能的原因包括设备环境风险、IP异常、多次失败尝试等。

八、最佳实践建议

8.1 选择合适的认证方案

根据业务场景选择合适的认证方案，避免过度认证或认证不足。首次实名认证场景使用金融级实人认证方案，二次验证场景使用金融级活体人脸验证方案，高风险操作场景使用金融级多因子意愿认证方案。

8.2 做好异常处理与重试机制

网络波动、用户操作不当等因素都可能导致认证失败。建议在客户端和服务端都做好异常处理和重试机制，提升用户体验和认证成功率。

8.3 设置监控与告警

接入金融级实人认证服务后，可以通过设置监控规则监测API的稳定性或对系统异常请求进行拦截。当出现不稳定性事件或异常请求时，可通过设置电话、短信、钉钉等方式进行告警通知。

8.4 定期轮换AccessKey

建议定期轮换AccessKey，降低密钥泄露的长期风险。同时，不要将AccessKey硬编码在代码中，应使用环境变量或配置中心进行管理。

九、常见问题问答

问1：实人认证是否支持海外用户？

答：阿里云实人认证支持中国香港、新加坡、印度尼西亚、马来西亚四大接入点，可覆盖海外用户的身份核验需求。具体支持的证件类型和地区以产品文档为准。

问2：调用接口时提示NoPermission，应该如何处理？

答：NoPermission错误表示当前使用的AccessKey没有调用该接口的权限。请检查RAM子账号是否已被授予AliyunYundunCloudAuthFullAccess权限策略，或根据具体接口授权相应的细粒度权限。

问3：认证结果中的人脸图片如何获取和保存？

答：金融级实人认证服务的部分接入方式支持将用户的认证照片上传并存储到您的OSS空间。需要在控制台完成授权金融级实人认证访问OSS存储空间的操作，并在认证场景中开启保存图片选项。

问4：CertifyId的有效期是多久？

答：初始化接口返回的认证CertifyUrl在30分钟内有效，且仅能认证提交一次。CertifyId本身也有时效限制，建议在获取后尽快使用。

问5：实人认证支持哪些客户端平台？

答：金融级实人认证支持Android、iOS、H5网页、支付宝小程序、Flutter等多种平台。Android要求系统版本4.4及以上，iOS要求9.0及以上。

问6：认证失败是否会计费？

答：若用户未完成认证方案中要求的所有认证步骤而中途退出，则不计入调用次数。但若完成了完整认证流程但最终结果不通过（如人脸比对失败），仍会计费，因为服务端已完成了完整的核验计算。