生物认证

更新时间: 2025-05-14 08:32:28
编辑

目前 Android 仅支持指纹识别登录，首先确保已经完成了 开发准备工作。

此功能在 android guard sdk 1.5.0 版本新增。


第一步：控制台配置

需要先在 Authing 控制台配置，在自建应用-客户端应用-登录控制-生物认证登录中勾选指纹识别。

drawing

第二步：添加依赖

implementation 'cn.authing:authing-android-webauthn:1.0.0'

第三步：分场景使用

使用托管页

在需要登录认证的地方启动托管页：

// this is the activity context
AuthFlow.start(this);

​ 通过以上步骤即可简单快速地通过配置 Authing 管理控制台后自动拥有生物认证登录功能，登录入口会在 Guard 内置登录界面的社会化登录按钮列表中体现。

使用指纹登录按钮

如果使用我们提供的指纹登录按钮。

​ 1. 布局文件里面加上（或者代码初始化添加）如下代码：

 <cn.authing.guard.social.FingerLoginButton
    android:id="@+id/btn_finger_login"
    android:background="@drawable/authing_button_background"
    android:textColor="@color/white"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

​ 2. 然后在代码里面处理事件：

FingerLoginButton button = findViewById(R.id.btn_finger_login);
button.setOnLoginListener(new AuthCallback<UserInfo>() {
    @Override
    public void call(int code, String message, UserInfo data) {
      	if (code == 200) {
        	// 登录成功，data 是用户信息
       	} else {
        	// 登录失败
      	}
    }
});

使用指纹登录授权类

如果不想使用我们内置的按钮，想完全自己实现 UI，则可以在按钮的点击事件里面调用 Finger 类的授权函数，此类集成了拉起指纹授权登录的业务逻辑：

Finger finger = new Finger();
finger.login(appContext, new AuthCallback<UserInfo>() {
    @Override
    public void call(int code, String message, UserInfo data) {
        if (code == 200) {
          // 登录成功，data 是用户信息
        } else {
          // 登录失败
        }
    }
});

使用指纹登录 API

指纹绑定 - 初始化绑定请求参数

public static void bindBiometricRequest(@NotNull AuthCallback<JSONObject> callback)

示例

AuthClient.bindBiometricRequest(new AuthCallback<JSONObject>() {
    @Override
    public void call(int code, String message, JSONObject data) {
      	if (code == 200) {
      	  // 成功
       	} 
    }
});

请求响应

名称类型描述
statusCodeint业务状态码，可以通过此状态码判断操作是否成功，200 表示成功
messageString描述信息
data.registrationOptions.challengestring挑战码, base64Url 编码
data.registrationOptions.rp.idString信赖方 domain
data.registrationOptions.rp.nameString信赖方名称
data.registrationOptions.user.idString用户 Id
data.registrationOptions.user.nameString用户名
data.registrationOptions.user.displayNameString用户显示名
data.registrationOptions.pubKeyCredParams[x].algnumber-7： ES256、-257：RS256
data.registrationOptions.pubKeyCredParams[x].typeString固定值, public-key
data.registrationOptions.timeoutnumber超时时间，毫秒
data.registrationOptions.attestationString依赖方是否需要证明
data.registrationOptions.excludeCredentials[x].idString凭证 ID, base64Url 编码
data.registrationOptions.excludeCredentials[x].typeString固定值
data.registrationOptions.excludeCredentials[x].transportsstring[]
data.registrationOptions.authenticatorSelection.userVerificationString指定认证器是否需要验证“用户为本人 (User Verified, UV)”，否则只须“用户在场 (User Present, UP)”
data.registrationOptions.authenticatorSelection.residentKeyString
data.registrationOptions.authenticatorSelection.requireResidentKeyboolean是否要求将私钥钥永久存储于认证器中
data.ticketStringticket 参数，验证时回传

指纹绑定 - 验证绑定

public static void bindBiometric(RegistrationParams registrationParams, @NotNull AuthCallback<JSONObject> callback)

参数

名称类型是否必填默认值描述
ticketString是-ticket, options 响应中的需回传的参数
registrationCredential.idString是-凭证 ID, Base64URL 编码的凭证 ID
registrationCredential.rawIdString是-凭证 ID
registrationCredential.response.attestationObjectString是-CBOR 编码的认证器数据，包含凭证公钥、凭证 ID、签名（如果有）、签名计数等信息
registrationCredential.response.clientDataJSONString是-客户端数据，包含 origin（即凭证请求来源）、挑战等信息
registrationCredential.typeString是-固定值
registrationCredential.transportsString[]是-字符串数组
authenticatorCodeString是-凭证类型编码：fingerprint 指纹、face 人脸

示例

RegistrationParams registrationParams = new RegistrationParams();
registrationParams.setTicket(ticket);
RegistrationCredential registrationCredential = new RegistrationCredential();
registrationCredential.setId(rep.getId());
registrationCredential.setRawId(Util.encodeBase64URL(rep.getRawId()));
RegistrationCredential.Response response = new RegistrationCredential.Response();
response.setAttestationObject(Util.encodeBase64URL(rep.getResponse().getAttestationObject()));
response.setClientDataJSON(Util.encodeBase64URL(rep.getResponse().getClientDataJSON().getBytes()));
registrationCredential.setResponse(response);
registrationCredential.setType("public-key");
registrationParams.setRegistrationCredential(registrationCredential);
registrationParams.setAuthenticatorCode("fingerprint");
AuthClient.bindBiometric(registrationParams, new AuthCallback<JSONObject>() {
    @Override
    public void call(int code, String message, JSONObject data) {
      	if (code == 200) {
      	  // 成功
       	} 
    }
});

请求响应

名称类型描述
statusCodeint业务状态码，可以通过此状态码判断操作是否成功，200 表示成功
messageString描述信息
data.verifiedStringtrue 成功，false 失败

指纹登录 - 初始化认证请求参数

public static void biometricAuthenticationRequest(@NotNull AuthCallback<JSONObject> callback)

示例

AuthClient.biometricAuthenticationRequest(new AuthCallback<JSONObject>() {
    @Override
    public void call(int code, String message, JSONObject data) {
      	if (code == 200) {
      	  // 成功
       	} 
    }
});

请求响应

名称类型描述
statusCodeint业务状态码，可以通过此状态码判断操作是否成功，200 表示成功
messageString描述信息
data.authenticationOptions.challengestring挑战码, base64Url 编码
data.authenticationOptions.allowCredentials[x].idString允许的凭证 ID
data.authenticationOptions.allowCredentials[x].typeString固定值
data.authenticationOptions.allowCredentials[x].transportsString[]字符串数组
data.authenticationOptions.timeoutnumber超时时间，毫秒值
data.authenticationOptions.userVerificationString
data.authenticationOptions.rpIdString依赖方 domain
data.ticketStringticket 参数，验证时回传

指纹登录 - 验证认证

public static void biometricAuthentication(AuthenticationParams authenticationParams, @NotNull AuthCallback<JSONObject> callback)

参数

名称类型是否必填默认值描述
ticketString是-ticket, options 响应中的需回传的参数
authenticationCredential.idString是-凭证 ID, Base64URL 编码的凭证 ID
authenticationCredential.rawIdString是-凭证 ID
authenticationCredential.response.authenticatorDataString是-认证器信息，包含认证状态、签名计数等
authenticationCredential.response.userHandleString是-创建凭证时的用户 ID, user.id
authenticationCredential.response.clientDataJSONString是-客户端数据，包含 origin（即凭证请求来源）、挑战等信息
authenticationCredential.response.signatureString是-被认证器签名的 authenticatorData + clientDataHash（clientDataJSON 的 SHA-256 hash）
authenticationCredential.typeString是-固定值
authenticationCredential.authenticatorAttachmentString是-指定要求的认证器类型

示例

AuthenticationParams authenticationParams = new AuthenticationParams();
authenticationParams.setTicket(ticket);
AuthenticationCredential authenticationCredential = new AuthenticationCredential();
authenticationCredential.setId(rep.getId());
authenticationCredential.setRawId(Util.encodeBase64URL(rep.getRawId()));
AuthenticationCredential.Response response = new AuthenticationCredential.Response();
response.setAuthenticatorData(Util.encodeBase64URL(rep.getResponse().getAuthenticatorData()));
response.setClientDataJSON(Util.encodeBase64URL(rep.getResponse().getClientDataJSON().getBytes()));
response.setSignature(Util.encodeBase64URL(rep.getResponse().getSignature()));
response.setUserHandle(Util.encodeBase64URL(Util.encodeBase64URL(rep.getResponse().getUserHandle()).getBytes()));
authenticationCredential.setResponse(response);
authenticationCredential.setType("public-key");
authenticationParams.setAuthenticationCredential(authenticationCredential);
authenticationParams.setAuthenticatorAttachment("platform");
AuthClient.biometricAuthentication(registrationParams, new AuthCallback<JSONObject>() {
    @Override
    public void call(int code, String message, JSONObject data) {
      	if (code == 200) {
      	  // 成功
       	} 
    }
});

请求响应

名称类型描述
statusCodeint业务状态码，可以通过此状态码判断操作是否成功，200 表示成功
messageString描述信息
data.verifiedStringtrue 成功，false 失败
data.tokenSet.expire_innumber过期时间 单位是秒
data.tokenSet.access_tokenStringAccess token
data.tokenSet.id_tokenStringId token
data.tokenSet.token_typeStringToken type
data.tokenSet.refresh_tokenStringRefresh token

指纹解绑

public static void unBindBiometric(String credentialID, @NotNull AuthCallback<JSONObject> callback)

参数

名称类型是否必填默认值描述
credentialIDString是-路径参数, 凭证 ID

示例

AuthClient.unBindBiometric("credentialID", new AuthCallback<JSONObject>() {
    @Override
    public void call(int code, String message, JSONObject data) {
      	if (code == 200) {
      	  // 成功
       	} 
    }
});

请求响应

名称类型描述
statusCodeint业务状态码，可以通过此状态码判断操作是否成功，200 表示成功
messageString描述信息
data.successStringtrue 成功，false 失败

指纹绑定数据查询

public static void getBiometricList(String authenticatorCode, @NotNull AuthCallback<JSONObject> callback)

参数

名称类型是否必填默认值描述
authenticatorCodeString是-fingerprint 指纹、face 人脸

示例

AuthClient.getBiometricList("authenticatorCode", new AuthCallback<JSONObject>() {
    @Override
    public void call(int code, String message, JSONObject data) {
      	if (code == 200) {
      	  // 成功
       	} 
    }
});

请求响应

名称类型描述
statusCodeint业务状态码，可以通过此状态码判断操作是否成功，200 表示成功
messageString描述信息
data.list[x].idString认证器凭证信息 Id
data.list[x].userPoolIdString用户池 ID
data.list[x].userIdString用户 ID
data.list[x].credentialIDString凭证 ID
data.list[x].authenticatorCodeString凭证类型编码，fingerprint: 指纹、face: 人脸、other: 未知
data.list[x].nameString凭证名称或设备名
data.list[x].initiatorPlatformString凭证注册平台信息
data.totalCountnumber总数

指纹绑定数据查询 - 通过凭证 id

public static void checkBiometricBind(String authenticatorCode, String[] credentialIds，@NotNull AuthCallback<JSONObject> callback)

参数

名称类型是否必填默认值描述
authenticatorCodeString是-fingerprint 指纹、face 人脸
credentialIdsString[]是-待检查的凭证 id 列表。要求至少有 1 个凭证 ID，最大 100 个。

示例

AuthClient.checkBiometricBind("authenticatorCode", ["1"],  new AuthCallback<JSONObject>() {
    @Override
    public void call(int code, String message, JSONObject data) {
      	if (code == 200) {
      	  // 成功
       	} 
    }
});

请求响应

名称类型描述
statusCodeint业务状态码，可以通过此状态码判断操作是否成功，200 表示成功
messageString描述信息
data.list[x].idString认证器凭证信息 Id
data.list[x].userPoolIdString用户池 ID
data.list[x].userIdString用户 ID
data.list[x].credentialIDString凭证 ID
data.list[x].authenticatorCodeString凭证类型编码，fingerprint: 指纹、face: 人脸、other: 未知
data.list[x].nameString凭证名称或设备名
data.list[x].initiatorPlatformString凭证注册平台信息
data.totalCountnumber总数