• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 用户认证开发指导
2
3> **说明：**
4> 该开发指导需配合API version 10版本的SDK使用。
5
6## 场景介绍
7
8当前用户认证支持Pin码认证、人脸识别和指纹识别，可应用于设备解锁、应用登录、支付等身份认证场景。
9
10## 接口说明
11
12userIAM_userAuth模块提供了用户认证的相关方法，包括查询认证能力、发起认证和取消认证等，用户可以使用人脸、指纹等生物特征信息进行认证操作。具体接口说明可以查阅[API参考文档](../reference/apis/js-apis-useriam-userauth.md)。
13
14在执行认证前，需要指定[认证类型](../reference/apis/js-apis-useriam-userauth.md#userauthtype8)和[认证等级](../reference/apis/js-apis-useriam-userauth.md#authtrustlevel8)，查询设备是否支持该认证能力。
15
16**表1** 用户认证开放能力列表
17
18| 接口名称    | 功能描述                |
19| ---------- | ----------------------- |
20| getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void | 根据指定的认证类型、认证等级，检测当前设备是否支持相应的认证能力。 |
21| getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance | 获取UserAuthInstance对象，用于执行用户身份认证，并支持使用统一用户身份认证组件。 |
22| on(type: 'result', callback: IAuthCallback): void | 订阅用户身份认证结果。 |
23| off(type: 'result', callback?: IAuthCallback): void | 取消订阅用户身份认证结果。 |
24| start(): void | 执行用户认证。        |
25| cancel(): void | 取消本次认证操作。    |
26
27**表2** 用户身份认证可信等级划分原则
28
29| 确认用户身份的认证可信等级 | 认证能力指标                      | 说明&举例                                                    | 可支撑的典型业务场景                                 |
30| -------------------------- | --------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------- |
31| ATL4                       | FRR=10%时，FAR≤0.0003%，SAR≤3%    | 能高精度地识别用户个体，有很强的活体检测能力，如采用了安全键盘的PIN码认证和有特殊安全增强的指纹与3D人脸认证。 | 小额支付                                             |
32| ATL3                       | FRR=10%时，FAR≤0.002%，SAR≤7%     | 能精确识别用户个体，有较强的活体检测能力，如有特殊安全增强的2D人脸认证。 | 设备解锁                                             |
33| ATL2                       | FRR=10%时，FAR≤0.002%，7%<SAR≤20% | 能精确识别用户个体，有一定的活体检测能力，如基于普通测距和佩戴检测的手表作为可信持有物的认证。 | 维持设备解锁状态、应用登录                           |
34| ATL1                       | FRR=10%时，FAR≤1%，7%<SAR≤20%     | 能识别用户个体，有一定的活体检测能力，如声纹认证。           | 业务风控、一般个人数据查询、精准业务推荐、个性化服务 |
35
36
37## 查询当前设备是否支持相应的认证能力
38
39### 开发步骤
40
411. 申请权限。调用[getAvailableStatus](../reference/apis/js-apis-useriam-userauth.md#useriam_userauthgetavailablestatus9)接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息请参考[Stage模型应用程序包结构](../quick-start/module-configuration-file.md)。
42
432. 指定[认证类型](../reference/apis/js-apis-useriam-userauth.md#userauthtype8)和[认证等级](../reference/apis/js-apis-useriam-userauth.md#authtrustlevel8)，调用[getAvailableStatus](../reference/apis/js-apis-useriam-userauth.md#useriam_userauthgetavailablestatus9)接口查询当前的设备是否支持相应的认证能力。
44
45    ```ts
46    import userIAM_userAuth from '@ohos.userIAM.userAuth';
47
48    // 查询认证能力是否支持，如果该设备未录入相关特征，就会打印不支持日志信息
49    try {
50        userIAM_userAuth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1);
51        console.info('current auth trust level is supported');
52    } catch (error) {
53        console.error('current auth trust level is not supported, error = ' + error);
54    }
55    ```
56
57## 执行认证操作并订阅认证结果
58
59### 开发步骤
60
611. 申请权限。调用[start](../reference/apis/js-apis-useriam-userauth.md#start10)接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息请参考[Stage模型应用程序包结构](../quick-start/module-configuration-file.md)。
62
632. 指定challenge、[认证类型](../reference/apis/js-apis-useriam-userauth.md#userauthtype8)和[认证等级](../reference/apis/js-apis-useriam-userauth.md#authtrustlevel8)，获取认证对象。
64
653. 调用[on](../reference/apis/js-apis-useriam-userauth.md#on10)接口订阅认证结果。
66
674. 调用[start](../reference/apis/js-apis-useriam-userauth.md#start10)接口发起认证，通过[onResult](../reference/apis/js-apis-useriam-userauth.md#onresult10)回调返回认证结果。
68
69    ```ts
70    import userIAM_userAuth from '@ohos.userIAM.userAuth';
71
72    const authParam : userIAM_userAuth.AuthParam = {
73      challenge: new Uint8Array([49, 49, 49, 49, 49, 49]),
74      authType: [userIAM_userAuth.UserAuthType.PIN],
75      authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1,
76    };
77    const widgetParam : userIAM_userAuth.WidgetParam = {
78      title: '请输入密码',
79    };
80    try {
81      //获取认证对象
82      let userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
83      console.log('get userAuth instance success');
84      //订阅认证结果
85      userAuthInstance.on('result', {
86        onResult (result) {
87          console.log('userAuthInstance callback result = ' + JSON.stringify(result));
88        }
89      });
90      console.log('auth on success');
91      userAuthInstance.start();
92      console.log('auth start success');
93    } catch (error) {
94      console.error('auth catch error: ' + JSON.stringify(error));
95    }
96    ```
97
985. 如果业务需要取消订阅认证结果，可以使用已经成功订阅事件的[UserAuthInstance](../reference/apis/js-apis-useriam-userauth.md#userauthinstance10)对象调用[off](../reference/apis/js-apis-useriam-userauth.md#off10)接口进行取消订阅。
99
100   ```ts
101   import userIAM_userAuth from '@ohos.userIAM.userAuth';
102
103   const authParam : userIAM_userAuth.AuthParam = {
104     challenge: new Uint8Array([49, 49, 49, 49, 49, 49]),
105     authType: [userIAM_userAuth.UserAuthType.PIN],
106     authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1,
107   };
108   const widgetParam : userIAM_userAuth.WidgetParam = {
109     title: '请输入密码',
110   };
111   try {
112     //获取认证对象
113     let userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
114     console.log('get userAuth instance success');
115     //取消订阅认证结果
116     userAuthInstance.off('result', {
117       onResult (result) {
118         console.log('auth off result: ' + JSON.stringify(result));
119       }
120     });
121     console.log('auth off success');
122   } catch (error) {
123     console.error('auth catch error: ' + JSON.stringify(error));
124   }
125   ```
126
127## 认证过程中取消认证
128
129### 开发步骤
130
1311. 申请权限。调用[cancel](../reference/apis/js-apis-useriam-userauth.md#cancel10)接口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.ACCESS_BIOMETRIC权限。更多配置信息请参考[Stage模型应用程序包结构](../quick-start/module-configuration-file.md)。
132
1332. 指定challenge、[认证类型](../reference/apis/js-apis-useriam-userauth.md#userauthtype8)和[认证等级](../reference/apis/js-apis-useriam-userauth.md#authtrustlevel8)，获取认证对象。
134
1353. 调用[start](../reference/apis/js-apis-useriam-userauth.md#start10)接口发起认证。
136
1374. 通过使用已经成功发起认证的调用[UserAuthInstance](../reference/apis/js-apis-useriam-userauth.md#userauthinstance10)对象调用[cancel](../reference/apis/js-apis-useriam-userauth.md#cancel10)接口取消本次认证。
138
139    ```ts
140    import userIAM_userAuth from '@ohos.userIAM.userAuth';
141
142    const authParam : userIAM_userAuth.AuthParam = {
143      challenge: new Uint8Array([49, 49, 49, 49, 49, 49]),
144      authType: [userIAM_userAuth.UserAuthType.PIN],
145      authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1,
146    };
147    const widgetParam : userIAM_userAuth.WidgetParam = {
148      title: '请输入密码',
149    };
150    try {
151      //获取认证对象
152      let userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
153      console.log('get userAuth instance success');
154      //开始认证
155      userAuthInstance.start();
156      console.log('auth start success');
157      // 取消认证
158      userAuthInstance.cancel();
159      console.log('auth cancel success');
160    } catch (error) {
161      console.error('auth catch error: ' + JSON.stringify(error));
162    }
163    ```
164