首页 >安全认证 >开发指南 >服务端接入 >生物识别(IFAA)接入

生物识别(IFAA)接入

前提条件

  1. 请先完成阿里云账号注册、实名认证、开通安全认证创建应用

  2. 请完成获取阿里云访问密钥;

  3. 请确保使用的应用,已经勾选了“生物识别(IFAA)”的认证方式,请查看修改应用认证方式。

IFAA认证器注册-初始化

IFAA认证器注册-初始化请求,返回符合IFAA创建身份证明的参数对象。

请求参数

名称

类型

必填

示例值

描述

ApplicationExternalId

String

A0000001

应用外部ID,该字段在创建应用时指定,在应用详情页中查看

AuthenticatorType

String

IFAA

认证方式标识,调用IFAA认证接口时,固定值为:IFAA

UserId

String

user-test-1

用户的唯一标识, 例如:userId、手机号、邮箱等

Username

String

张三

用户名

UserDisplayName

String

小张

用户昵称

RegistrationContext

String

{"action":"request/register","ifaa":{"appid":"CZHqxFpzF4Ahp0u45Kl4kuvY/4Y","auth-type":1,"device-id":"ad24csqTlz7IfiXJoyw7_zK8HbF0lz_3zfnnRzGhWwEK8IxEnHaDaA==","message":"eyJhaSI6IjIjMSMwI......JIVUFXRUktWjExNCJ9","userid":"user1","version":"2.0"},"transaction":{"id":"transId","payload":"transPayload","type":"Login"},"version":"1.0.0"}

IFAA注册上下文, JSON字符串,由IFAA SDK 中的方法[EtasRegister regInit生成

返回数据

名称

类型

示例值

描述

Success

boolean

true

操作结果,true 代表成功,false 代表失败

Code

String

Opreation.Success

状态码。当 Success=true 时,Code=Operation.Success当 Success=false 时,Code的值,请参见下方错误码

Message

String

Opreation.Success

具体的描述信息,当 Success=false 时,会给出Code的对应的具体描述信息

RequestId

String

1C0EE50A-B3BB-42FD-AB59-E3FE88976982

请求ID

Data

String

操作成功时,Data中的JSON字符串包含两个字段:

  • ChallengeBase64: 字符串:防重放挑战码

  • Options:创建认证器的Options,包含IFAA注册初始化响应报etasSDKString

操作失败时,Data字段为空

请求示例

请求方式:POST

https://idaas-doraemon.aliyuncs.com/?Action=CreateAuthenticatorRegistration
&Version=2021-05-20
&ApplicationExternalId=A0000001
&AuthenticatorType=IFAA
&UserId=user-test-1
&UserName=user-test-1
&UserDisplayName=user-test-1
&RegistrationContext={\"action\": \"request/register\",\"version\": \"1.0.0\",\"transaction\": {\"id\": \"100001\",\"payload\": \"payload\",\"type\": \"Login\"},\"ifaa\": {\"version\": \"2.0\",\"message\": \"eyJhcCI6IiIsImFpIjoiMiMxIzAjMjAjMiMwIzY7IiwidGsiOiJBQkMtZjYzNGUzY2MtNWE1Mi00NDEzLThkZDctNmQ0ZTU0MzBkZTc1IiwicG0iOiJJRkFBLUFwcGxlIiwiZGkiOiJSa1pHUmtaR1JrWXdSREkwUVRRMFF6UXlPVGcwUTBaRU9EazRSREF4UWpjeFF6ZENNRVkzTnc9PSJ9\",\"device-id\":\"RkZGRkZGRkYwRDI0QTQ0QzQyOTg0Q0ZEODk4RDAxQjcxQzdCMEY3Nw==\",\"auth-type\":1,\"userid\":\"wei3333\",\"appid\":\"com.esandinfo.demo\"}}
&<公共请求参数>

正常返回示例 -IFAA注册认证器-初始化通过

{
  "Success": true,
  "Code": "Operation.Success",
  "Message": "Operation.Success",
  "RequestId": "337848D2-FF8A-4EDD-BD4D-1B9BC80E58B6",
  "Data": {
    "challengeBase64":"ODJkMzg5ZWZiMDU2ZGJiMGJiN2FlZjkyMDk1YzQwOThMWngzSlhaVWxhcw==",
    "requestId":"10280909-EB9F-17BC-8A0C-24813AC96BF6",
    "options":"{\"etasSDKString\":\"{\\\"ifaa\\\":{\\\"code\\\":0,\\\"message\\\":\\\"eyJoZV....UFBQUFBIn19\\\"},\\\"version\\\":\\\"1.0.0\\\",\\\"transaction\\\":{\\\"id\\\":\\\"100001\\\",\\\"type\\\":\\\"Login\\\",\\\"payload\\\":\\\"payload\\\"}}\",\"user\":{\"displayName\":\"wei3333\",\"id\":\"wei3333\",\"name\":\"wei3333\"}}"
}
}

错误返回示例 - 请求参数中缺少认证方式标识

{
  "Success": false,
  "Code": "Params.Blank",
  "Message": "Params.Blank.APIInvokeParams.AuthenticatorType",
  "RequestId": "1C0EE50A-B3BB-42FD-AB59-E3FE88976982",
  "Data":null
}

IFAA认证器注册-验证

IFAA认证器注册-初始化请求,返回符合IFAA创建身份证明的参数对象。

请求参数

名称

类型

必填

示例值

描述

ApplicationExternalId

String

A0000001

应用外部ID,该字段在创建应用时指定,在应用详情页中查看

AuthenticatorType

String

IFAA

认证方式标识,调用IFAA认证接口时,固定值为:IFAA

UserId

String

user-test-1

用户的唯一标识, 例如:userId、手机号、邮箱等

Username

String

张三

用户名

UserDisplayName

String

小张

用户昵称

RequireChallengeBase64

String

NGYzZTEyZDRmMWVmNzM4NmEwYjk1MTM4NDQyNGRhMjM4NjJ3QzJ6SVdBYg

挑战码,通过注册初始化请求返回的参数,挑战码须通过该字段或者下边registrationContext中的base64Challenge字段回传

RegistrationContext

String

{"base64Challenge": "NGYzZTEyZDRmMWVmNzM4NmEwYjk1MTM4NDQyNGRhMjM4NjJ3QzJ6SVdBYg==",

"etasSDKString": ""}

IFAA认证器注册初始化上下文,JSON字符串,包含的字段请参考下文:registrationContext参数说明

RegistrationContext 参数说明:

参数名称

类型

示例

说明

base64Challenge

string

NGYzZTEyZDRmMWVmNzM4NmEwYjk1MTM4NDQyNGRhMjM4NjJ3QzJ6SVdBYg==

挑战码,通过注册初始化请求返回的参数,挑战码须通过该字段或者上文中requireChallengeBase64 字段回传

etasSDKString

string

调用IFAA注册初始化返回的参数etasSDKString,返回JSON字符串

返回数据

名称

类型

示例值

描述

Success

boolean

true

操作结果,true 代表成功,false 代表失败

Code

String

Opreation.Success

状态码。当 Success=true 时,Code=Operation.Success当 Success=false 时,Code的值,请参见下方错误码

Message

String

Opreation.Success

具体的描述信息,当 Success=false 时,会给出Code的对应的具体描述信息

RequestId

String

1C0EE50A-B3BB-42FD-AB59-E3FE88976982

请求ID

Data

String

{ "authenticatorUuid":"333d1541412204930221ee1268564041XwhgRc0Yl0j",

"etasSDKString":"" }

错误码,当 success=false 时,为 null;当 success=true 时,是一个对象:对象中包含一个字段:authenticatorUuid,代表认证器唯一标识,

etasSDKString参数需要传入移动端SDK进行确认

请求示例

请求方式:POST

https://idaas-doraemon.aliyuncs.com/?Action=VerifyUserAuthentication
&Version=2021-05-20
&ApplicationExternalId=A0000001
&AuthenticatorType=IFAA
&UserId=user-test-1
&AuthenticatorName=认证器
&RegistrationContext={"base64Challenge": "NGYzZTEyZDRmMWVmNzM4NmEwYjk1MTM4NDQyNGRhMjM4NjJ3QzJ6SVdBYg==","etasSDKString": ""}
&<公共请求参数>

正常返回示例 -IFAA注册认证器-验证通过

{
  "Success": true,
  "Code": "Operation.Success",
  "Message": "Operation.Success",
  "RequestId": "337848D2-FF8A-4EDD-BD4D-1B9BC80E58B6",
  "Data": {
"authenticatorUuid":"333d1541412204930221ee1268564041XwhgRc0Yl0j",
"etasSDKString":"xxxxx"
}
}

错误返回示例 - 请求参数中缺少认证方式标识

{
  "Success": false,
  "Code": "Params.Blank",
  "Message": "Params.Blank.APIInvokeParams.AuthenticatorType",
  "RequestId": "1C0EE50A-B3BB-42FD-AB59-E3FE88976982",
  "Data":null
}

IFAA认证器认证-初始化

IFAA认证器认证-初始化请求。

请求参数

名称

类型

必填

示例值

描述

ApplicationExternalId

String

A0000001

应用外部ID,该字段在创建应用时指定,在应用详情页中查看

AuthenticatorType

String

IFAA

认证方式标识,调用IFAA认证接口时,固定值为:IFAA

UserId

String

user-test-1

用户的唯一标识, 例如:userId、手机号、邮箱等

ClientExtendParamsJson

String

eyJhcHBJZCI6I.......XbEpjMGx0Um5CSMCJ9

调用安全认证IFAA-SDK生成的参数, 该参数不可以为空

ClientExtendParamsJsonSign

String

6bba843a95fc47919297ee8a05cd344ea2a691dc870b20831f8b852f8d14c250

调用安全认证IFAA-SDK生成的参数, 该参数不可以为空

返回数据

名称

类型

示例值

描述

Success

boolean

true

操作结果,true 代表成功,false 代表失败

Code

String

Opreation.Success

状态码。当 Success=true 时,Code=Operation.Success当 Success=false 时,Code的值,请参见下方错误码

Message

String

Opreation.Success

具体的描述信息,当 Success=false 时,会给出Code的对应的具体描述信息

RequestId

String

1C0EE50A-B3BB-42FD-AB59-E3FE88976982

请求ID

Data

String

操作成功时,Data中的JSON字符串包含1个字段:

  • ChallengeBase64: String :Base64的挑战码

  • Options String:JSON字符串 认证器认证请求参数,包含移动端SDK需要的参数etasSDKString

操作失败时,Data字段为空

请求示例

请求方式:POST

https://idaas-doraemon.aliyuncs.com/?Action=VerifyUserAuthentication
&Version=2021-05-20
&ApplicationExternalId=A0000001
&AuthenticatorType=IFAA
&UserId=user-test-1
&ClientExtendParamsJson=xxxxx
&ClientExtendParamsJsonSign=xxxxx
&<公共请求参数>

正常返回示例 -IFAA认证器认证-初始化通过

{
  "Success": true,
  "Code": "Operation.Success",
  "Message": "Operation.Success",
  "RequestId": "337848D2-FF8A-4EDD-BD4D-1B9BC80E58B6",
  "Data": {
    "challengeBase64":"AQAAAX1MtRZJdDhHTnFMVWR1bDdBSlBFYnlaRnlYd2s5",
    "requestId":"8FFB6C53-84CC-0D8F-BD78-BA6ABB697980",
    "options":"{\"allowCredentials\":[\"FFFFFFFF0D24A44C42984CFD898D01B71C7B0F77\"],\"challengeBase64\":\"AQAAAX1MtRZJdDhHTnFMVWR1bDdBSlBFYnlaRnlYd2s5\",\"etasSDKString\":\"{\\\"ifaa\\\":{\\\"code\\\":0,\\\"message\\\":\\\"eyJo......FBQUFBIn19\\\"},\\\"version\\\":\\\"1.0.0\\\",\\\"transaction\\\":{\\\"id\\\":\\\"100001\\\",\\\"type\\\":\\\"Login\\\",\\\"payload\\\":\\\"payload\\\"}}\"}"
   }
}

错误返回示例 - 请求参数中缺少认证方式标识

{

  "Success": false,
  "Code": "Params.Blank",
  "Message": "Params.Blank.APIInvokeParams.AuthenticatorType",
  "RequestId": "1C0EE50A-B3BB-42FD-AB59-E3FE88976982",
  "Data":null
}

IFAA认证器认证

IFAA认证器认证。

名称

类型

必填

示例值

描述

ApplicationExternalId

String

A0000001

应用外部ID,该字段在创建应用时指定,在应用详情页中查看

AuthenticatorType

String

IFAA

认证器类型,固定值为:

IFAA

AuthenticationContext

String

A0000001

IFAA场景可以传随机字符串,不做校验

UserId

String

user-test-1

用户ID

ClientExtendParamsJson

String

eyJhcHBJZCI6I.......XbEpjMGx0Um5CSMCJ9

调用安全认证IFAA-SDK生成的参数, 该参数不可以为空

ClientExtendParamsJsonSign

String

6bba843a95fc47919297ee8a05cd344ea2a691dc870b20831f8b852f8d14c250

调用安全认证IFAA-SDK生成的参数, 该参数不可以为空

返回数据

名称

类型

示例值

描述

Success

boolean

true

操作结果,true 代表成功,false 代表失败

Code

String

Opreation.Success

状态码。

  • 当 Success=true 时,Code=Operation.Success

  • 当 Success=false 时,Code的值,请参见下方错误码

Message

String

Opreation.Success

具体的描述信息,当 Success=false 时,会给出Code的对应的具体描述信息

RequestId

String

1C0EE50A-B3BB-42FD-AB59-E3FE88976982

请求ID

Data

String

{ "verifyResult": true,

"etasSDKString": "xxxx", "authenticateResultInfo": { "credentialId": "Z0MkHYJnRDbGfa0LvWvvO6UqcNjFwCIR6mpNTl8jfTA", "userId": "abcdefg" }

操作成功时,Data中的JSON字符串包含1个字段:

  • VerifyResult: Bool :认证器结果

  • etasSDKString:认证结果响应报文, 需要传给移动端SDK校验

  • AuthenticateResultInfo Object:认证结果对象

- UserId:认证通过的用户Id

- CredentialId:认证使用的凭据Id

请求方式:POST

https://idaas-doraemon.aliyuncs.com/?Action=VerifyUserAuthentication
&Version=2021-05-20
&ApplicationExternalId=A0000001
&AuthenticatorType=IFAA
&UserId=user-test-1
&AuthenticationContext=xxxxx
&ClientExtendParamsJson=eyJwaG9uZU51bWJlciI6IjAwMDAwMDAwMDAwIn0=
&ClientExtendParamsJsonSign=6bba843a95fc47919297ee8a05cd344ea2
&UserSourceIp=1.1.1.1
&<公共请求参数>

正常返回示例 -创建IFAA认证器认证请求通过

{
  "Success": true,
  "Code": "Operation.Success",
  "Message": "Operation.Success",
  "RequestId": "337848D2-FF8A-4EDD-BD4D-1B9BC80E58B6",
  "Data":  {
    "verifyResult": true,
    "etasSDKString":xxxxx,
    "authenticateResultInfo": {
      "credentialId": "Z0MkHYJnRDbGfa0LvWvvO6UqcNjFwCIR6mpNTl8jfTA",
      "userId": "abcdefg"
    }
  }
}

错误返回示例 - 请求参数中缺少认证类型标识

{
  "Success": false,
  "Code": "Params.Blank",
  "Message": "Params.Blank.APIInvokeParams.AuthenticatorType",
  "RequestId": "1C0EE50A-B3BB-42FD-AB59-E3FE88976982",
  "Data":null
}

代码示例(Java)

需要在一个JAVA的MAVEN 项目中引入服务端SDK包, 坐标如下。

  <dependency>
   <groupId>com.aliyun</groupId>
   <artifactId>aliyun-java-sdk-idaas-doraemon</artifactId>
   <version>1.2.4</version>
  </dependency>

IFAA认证的示例代码:

import com.alibaba.fastjson.JSONObject;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.idaas_doraemon.model.v20210520.*;
import com.aliyuncs.profile.DefaultProfile;

import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class IDaaSAuthSample {
    /**
     * 使用AK&SK初始化账号Client
     *
     * @param accessKeyId
     * @param accessKeySecret
     * @return Client
     * @throws Exception
     */
    public static IAcsClient createClient(String accessKeyId, String accessKeySecret) throws Exception {
        DefaultProfile profile = DefaultProfile.getProfile(
                "cn-hangzhou",
                accessKeyId,
                accessKeySecret);
        // addEndpoint
        DefaultProfile.addEndpoint("cn-hangzhou",
                "idaas-doraemon",
                "idaas-doraemon.aliyuncs.com");
        // 访问的域名
        return new DefaultAcsClient(profile);
    }

    public static void main(String[] args_) throws Exception {
        // IFAA认证器注册初始化
        registerIFAAInit();
        // IFAA认证器注册
        registerIFAAVerify();
        // IFAA认证初始化
        IFAAVerifyInit();
        // IFAAVerify认证
    }

    public void registerIFAAInit() throws Exception {
        IAcsClient client = IDaaSAuthSample.createClient("Your AccessKey", "Your AccessSecret");
        //IFAA认证器注册初始化
        CreateAuthenticatorRegistrationRequest request = new CreateAuthenticatorRegistrationRequest();
                request.setApplicationExternalId("testApplication");
                request.setAuthenticatorType("IFAA");
                request.setUserId("1232312312");
                request.setUserName("1232312312");
                request.setUserDisplayName("1232312312");
                request.setRegistrationContext("{\"action\": \"request/register\",\"version\": \"1.0.0\",\"transaction\": {\"id\": \"100001\",\"payload\": \"payload\",\"type\": \"Login\"},\"ifaa\": {\"version\": \"2.0\",\"message\": \"eyJhcCI6IiIsImFpIjoiMiMxIzAjMjAjMiMwIzY7IiwidGsiOiJBQkMtZjYzNGUzY2MtNWE1Mi00NDEzLThkZDctNmQ0ZTU0MzBkZTc1IiwicG0iOiJJRkFBLUFwcGxlIiwiZGkiOiJSa1pHUmtaR1JrWXdSREkwUVRRMFF6UXlPVGcwUTBaRU9EazRSREF4UWpjeFF6ZENNRVkzTnc9PSJ9\",\"device-id\":\"RkZGRkZGRkYwRDI0QTQ0QzQyOTg0Q0ZEODk4RDAxQjcxQzdCMEY3Nw==\",\"auth-type\":1,\"userid\":\"wei3333\",\"appid\":\"com.esandinfo.demo\"}}");
        // 复制代码运行请自行打印 API 的返回值
        try {
            CreateAuthenticatorRegistrationResponse response = client.getAcsResponse(request);
            System.out.println(response.getChallengeBase64());
        } catch (Exception e) {
            //根据e,getCode()判断异常原因
            System.out.println(e);
        }
    }

    public void registerIFAAVerify() throws Exception {
        IAcsClient client = IDaaSAuthSample.createClient("Your AccessKey", "Your AccessSecret");
        //IFAA认证器注册-验证
        RegisterAuthenticatorRequest request = new RegisterAuthenticatorRequest();
                request.setApplicationExternalId("testApplication");
                request.setAuthenticatorType("IFAA");
                request.setUserId("1232312312");
                request.setAuthenticatorName("认证器");
                request.setRequireChallengeBase64("AAAAAXy71/wtMTIzMjMxMjMxMg==");
                request.setRegistrationContext("{\"base64Challenge\":"", \"etasSDKString\":{\"action\":\"response/register\",\"version\":\"1.0.0\",\"transaction\": {\"id\":\"100001\",\"payload\":\"payload\",\"type\": \"Login\"},\"ifaa\":{\"auth-type\":1,\"message\":\"=\", \"device-id\":\"==\",\"userid\":\"wei3333\",\"appid\":\"com.esandinfo.demo\"}}}");
                request.setUserSourceIp("1.0.0.1");
        // 复制代码运行请自行打印 API 的返回值
        try {
            RegisterAuthenticatorResponse response = client.getAcsResponse(request);
            System.out.println(response.getAuthenticatorUuid());
        } catch (Exception e) {
            //根据e,getCode()判断异常原因
            System.out.println(e);
        }
    }

    public void IFAAVerifyInit() throws Exception {
        IAcsClient client = IDaaSAuthSample.createClient("Your AccessKey", "Your AccessSecret");
        //IFAA认证器注册-验证
        CreateUserAuthenticateOptionsRequest request = new CreateUserAuthenticateOptionsRequest();
                request.setApplicationExternalId("testApplication");
                request.setAuthenticatorType("IFAA");
                request.setUserId("1232312312");
                request.setClientExtendParamsJson("");
                request.setClientExtendParamsJsonSign("");
        // 复制代码运行请自行打印 API 的返回值
        try {
            CreateUserAuthenticateOptionsResponse response = client.getAcsResponse(request);
            System.out.println(response.getOptions());
        } catch (Exception e) {
            //根据e,getCode()判断异常原因
            System.out.println(e);
        }
    }

    public void IFAAVerify() throws Exception {
        IAcsClient client = IDaaSAuthSample.createClient("Your AccessKey", "Your AccessSecret");
        //IFAA认证器注册-验证
        VerifyUserAuthenticationRequest request = new VerifyUserAuthenticationRequest();
                request.setApplicationExternalId("testApplication");
                request.setAuthenticatorType("IFAA");
                request.setUserId("1232312312");
                request.setAuthenticationContext("IFAA");
                request.setClientExtendParamsJson("");
                request.setClientExtendParamsJsonSign("");
        // 复制代码运行请自行打印 API 的返回值
        try {
            VerifyUserAuthenticationResponse response = client.getAcsResponse(request);
            System.out.println(response.getAuthenticateResultInfo());
        } catch (Exception e) {
            //根据e,getCode()判断异常原因
            System.out.println(e);
        }
    }
}

示例代码的maven依赖

  <dependency>
   <groupId>com.aliyun</groupId>
   <artifactId>aliyun-java-sdk-idaas-doraemon</artifactId>
   <version>1.2.4</version>
  </dependency>
  <dependency>
   <groupId>com.aliyun</groupId>
   <artifactId>aliyun-java-sdk-core</artifactId>
   <optional>true</optional>
   <version>[4.4.9,5.0.0)</version>
  </dependency>

阿里云首页 安全认证 相关技术圈