1# 发起认证
2
3
4应用发起身份认证请求，获取身份认证结果，从而访问受保护的系统/服务/应用的功能和数据（包括用户个人数据）。
5
6
7## 接口说明
8
9具体参数、返回值、错误码等描述，请参考对应的[API文档](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthgetuserauthinstance10)。
10
11| 接口名称 | 功能描述 |
12| -------- | -------- |
13| getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance | 获取UserAuthInstance对象，用于执行用户身份认证，并支持使用统一[用户身份认证控件](#用户身份认证控件介绍)。 |
14| on(type: 'result', callback: IAuthCallback): void | 订阅用户身份认证结果。 |
15| off(type: 'result', callback?: IAuthCallback): void | 取消订阅用户身份认证结果。 |
16| start(): void | 执行用户认证。 |
17
18
19## 用户身份认证控件介绍
20
21系统提供了统一的用户认证控件供应用调用，使用用户认证控件的优势：
22
23- 统一用户认证服务将通过该控件完成信息的识别和认证，再将认证结果返回给应用，整体过程安全可控，可以更好地保护用户的生物特征信息。
24
25- 统一固定的UI组件样式，便于用户识别。
26
27认证控件的样式如图所示，通过[WidgetParam](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#widgetparam10)配置对应参数。
28
29<!--RP1-->
30![zh-cn_image_0000001789150921](figures/zh-cn_image_0000001789150921.png)
31<!--RP1End-->
32
33- 标注1：用户认证界面的标题（WidgetParam.title），最大长度为500字符。应用可在此配置符合场景的字符串。
34
35- 标注2：导航按键上显示的文本（WidgetParam.navigationButtonText），最大长度为60字符。仅在单指纹、单人脸场景下支持配置。
36
37  当生物认证失败后，将出现该按钮，点击后从生物认证切换到应用自定义认证。
38
39<!--Del-->
40- 如图所示，认证控件的显示形式（WidgetParam.windowMode）为弹窗。
41
42  认证控件分为弹窗、全屏两种显示形式，如下图所示，左侧为默认的弹窗样式，右侧为全屏样式。
43
44  当前仅系统应用可以选择和使用全屏类型的认证界面。
45
46  ![zh-cn_image_0000001742032002](figures/zh-cn_image_0000001742032002.png)
47<!--DelEnd-->
48
49当前支持使用认证控件的认证类型包括：
50
51- 锁屏密码认证
52
53- 人脸认证
54
55- 指纹认证
56
57- 人脸+锁屏密码认证
58
59- 指纹+锁屏密码认证
60
61- 人脸+指纹+锁屏密码认证
62
63> **说明：**
64> 当前仅在单指纹、单人脸场景下支持配置导航按键上显示的文本（WidgetParam.navigationButtonText）。
65
66
67## 开发步骤
68
691. [申请权限](prerequisites.md#申请权限)：ohos.permission.ACCESS_BIOMETRIC。
70
712. 指定用户认证相关参数[AuthParam](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#authparam10)（包括挑战值、认证类型[UserAuthType](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthtype8)列表和认证等级[AuthTrustLevel](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#authtrustlevel8)）、配置认证控件界面[WidgetParam](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#widgetparam10)，调用[getUserAuthInstance](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthgetuserauthinstance10)获取认证对象。
72
733. 调用[UserAuthInstance.on](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#on10)接口订阅认证结果。
74
754. 调用[UserAuthInstance.start](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#start10)接口发起认证，通过[IAuthCallback](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#iauthcallback10)回调返回认证结果[UserAuthResult](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthresult10)。
76   当认证成功时返回认证通过类型（[UserAuthType](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthtype8)）和令牌信息（AuthToken）。
77
78**示例1：**
79
80 发起用户认证，采用认证可信等级≥ATL3的人脸+锁屏密码认证，获取认证结果：
81
82```ts
83// API version 10
84import { BusinessError } from '@kit.BasicServicesKit';
85import { cryptoFramework } from '@kit.CryptoArchitectureKit';
86import { userAuth } from '@kit.UserAuthenticationKit';
87
88try {
89  const rand = cryptoFramework.createRandom();
90  const len: number = 16; // Generate a 16-byte random number.
91  const randData: Uint8Array = rand?.generateRandomSync(len)?.data;
92  // 设置认证参数
93  const authParam: userAuth.AuthParam = {
94    challenge: randData,
95    authType: [userAuth.UserAuthType.PIN, userAuth.UserAuthType.FACE],
96    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
97  };
98  // 配置认证界面
99  const widgetParam: userAuth.WidgetParam = {
100    title: '请进行身份认证',
101  };
102  // 获取认证对象
103  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
104  console.info('get userAuth instance success');
105  // 订阅认证结果
106  userAuthInstance.on('result', {
107    onResult(result) {
108      console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`);
109      // 可在认证结束或其他业务需要场景，取消订阅认证结果
110      userAuthInstance.off('result');
111    }
112  });
113  console.info('auth on success');
114  userAuthInstance.start();
115  console.info('auth start success');
116} catch (error) {
117  const err: BusinessError = error as BusinessError;
118  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
119}
120```
121**示例2：**
122
123发起用户认证，采用认证可信等级≥ATL3的人脸 + 认证类型相关 + 复用设备解锁最大有效时长认证，获取认证结果：
124
125```ts
126// API version 10
127import { BusinessError } from  '@kit.BasicServicesKit';
128import { cryptoFramework } from '@kit.CryptoArchitectureKit';
129import { userAuth } from '@kit.UserAuthenticationKit';
130
131// 设置认证参数
132let reuseUnlockResult: userAuth.ReuseUnlockResult = {
133  reuseMode: userAuth.ReuseMode.AUTH_TYPE_RELEVANT,
134  reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION,
135}
136try {
137  const rand = cryptoFramework.createRandom();
138  const len: number = 16;
139  const randData: Uint8Array = rand?.generateRandomSync(len)?.data;
140  const authParam: userAuth.AuthParam = {
141    challenge: randData,
142    authType: [userAuth.UserAuthType.FACE],
143    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
144    reuseUnlockResult: reuseUnlockResult,
145  };
146  // 配置认证界面
147  const widgetParam: userAuth.WidgetParam = {
148    title: '请进行身份认证',
149  };
150  // 获取认证对象
151  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
152  console.info('get userAuth instance success');
153  // 订阅认证结果
154  userAuthInstance.on('result', {
155    onResult(result) {
156      console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`);
157      // 可在认证结束或其他业务需要场景，取消订阅认证结果
158      userAuthInstance.off('result');
159    }
160  });
161  console.info('auth on success');
162  userAuthInstance.start();
163  console.info('auth start success');
164} catch (error) {
165  const err: BusinessError = error as BusinessError;
166  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
167}
168```
169**示例3：**
170
171发起用户认证，采用认证可信等级≥ATL3的人脸 + 任意应用认证类型相关 + 复用任意应用最大有效时长认证，获取认证结果：
172
173```ts
174// API version 14
175import { BusinessError } from  '@kit.BasicServicesKit';
176import { cryptoFramework } from '@kit.CryptoArchitectureKit';
177import { userAuth } from '@kit.UserAuthenticationKit';
178
179// 设置认证参数
180let reuseUnlockResult: userAuth.ReuseUnlockResult = {
181  reuseMode: userAuth.ReuseMode.CALLER_IRRELEVANT_AUTH_TYPE_RELEVANT,
182  reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION,
183}
184try {
185  const rand = cryptoFramework.createRandom();
186  const len: number = 16;
187  const randData: Uint8Array = rand?.generateRandomSync(len)?.data;
188  const authParam: userAuth.AuthParam = {
189    challenge: randData,
190    authType: [userAuth.UserAuthType.FACE],
191    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
192    reuseUnlockResult: reuseUnlockResult,
193  };
194  // 配置认证界面
195  const widgetParam: userAuth.WidgetParam = {
196    title: '请进行身份认证',
197  };
198  // 获取认证对象
199  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
200  console.info('get userAuth instance success');
201  // 订阅认证结果
202  userAuthInstance.on('result', {
203    onResult(result) {
204      console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`);
205      // 可在认证结束或其他业务需要场景，取消订阅认证结果
206      userAuthInstance.off('result');
207    }
208  });
209  console.info('auth on success');
210  userAuthInstance.start();
211  console.info('auth start success');
212} catch (error) {
213  const err: BusinessError = error as BusinessError;
214  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
215}
216```