1# 发起认证 2 3<!--Kit: User Authentication Kit--> 4<!--Subsystem: UserIAM--> 5<!--Owner: @WALL_EYE--> 6<!--Designer: @lichangting518--> 7<!--Tester: @jane_lz--> 8<!--Adviser: @zengyawen--> 9 10应用发起身份认证请求，获取身份认证结果，以访问受保护的系统、服务或应用的功能和数据，包括用户个人数据。 11 12## 接口说明 13 14具体参数、返回值、错误码等描述，请参考对应的[API文档](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthgetuserauthinstance10)。 15 16| 接口名称 | 功能描述 | 17| -------- | -------- | 18| getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance | 获取UserAuthInstance对象，用于执行用户身份认证，并支持使用统一[用户身份认证控件](#用户身份认证控件介绍)。 | 19| on(type: 'result', callback: IAuthCallback): void | 订阅用户身份认证结果。 | 20| off(type: 'result', callback?: IAuthCallback): void | 取消订阅用户身份认证结果。 | 21| start(): void | 执行用户认证。 | 22 23## 用户身份认证控件介绍 24 25系统提供了统一的用户认证控件供应用调用，使用用户认证控件的优势： 26 27- 统一用户认证服务将通过该控件完成信息的识别和认证，再将认证结果返回给应用，整体过程安全可控，可以更好地保护用户的生物特征信息。 28 29- 统一固定的UI组件样式，便于用户识别。 30 31认证控件的样式如图所示，通过[WidgetParam](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#widgetparam10)配置对应参数。 32 33<!--RP1--> 34 35<!--RP1End--> 36 37- 标注1：用户认证界面的标题（WidgetParam.title），不支持传空字串，最大长度为500字符。应用可在此配置符合场景的字符串，建议传入认证目的，例如用于支付、登录应用等。 38<!--RP2--> 39- 标注2：导航按键上显示的文本（WidgetParam.navigationButtonText），最大长度为60字符。API 10-17仅在单指纹、单人脸场景下支持配置。从API 18开始，增加支持人脸+指纹场景。 40 41 当生物认证失败后，将显示一个按钮。点击该按钮，可以从生物认证切换到应用自定义认证。<!--RP2End--> 42 43<!--Del--> 44- 如图所示，认证控件的显示形式（WidgetParam.windowMode）为弹窗。 45 46 认证控件分为弹窗、全屏两种显示形式，如下图所示，左侧为默认的弹窗样式，右侧为全屏样式。 47 48 当前仅系统应用可以选择和使用全屏类型的认证界面。 49 50  51<!--DelEnd--> 52 53当前支持使用认证控件的认证类型包括： 54 55- 锁屏口令认证 56 57- 人脸认证 58 59- 指纹认证 60 61- 人脸+锁屏口令认证 62 63- 指纹+锁屏口令认证 64 65- 人脸+指纹+锁屏口令认证 66 67- 人脸+自定义导航按键 68 69- 指纹+自定义导航按键 70 71- 人脸+指纹+自定义导航按键<sup>18+</sup> 72 73## 开发步骤 74 751. [申请权限](prerequisites.md#申请权限)：ohos.permission.ACCESS_BIOMETRIC。 76 772. 指定用户认证相关参数[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)获取认证对象。 78 793. 调用[UserAuthInstance.on](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#on10)接口订阅认证结果。 80 814. 调用[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)。当认证成功时返回认证通过类型（[UserAuthType](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#userauthtype8)）和令牌信息（AuthToken）。 82 83**示例1：** 84 85 发起用户认证，采用认证可信等级≥ATL3的人脸+锁屏口令认证，获取认证结果。 86 87```ts 88// API version 10 89import { BusinessError } from '@kit.BasicServicesKit'; 90import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 91import { userAuth } from '@kit.UserAuthenticationKit'; 92 93try { 94 const rand = cryptoFramework.createRandom(); 95 const len: number = 16; // Generate a 16-byte random number. 96 let randData: Uint8Array | null = null; 97 let retryCount = 0; 98 while(retryCount < 3){ 99 randData = rand?.generateRandomSync(len)?.data; 100 if(randData){ 101 break; 102 } 103 retryCount++; 104 } 105 if(!randData){ 106 return; 107 } 108 // 设置认证参数。 109 const authParam: userAuth.AuthParam = { 110 challenge: randData, 111 authType: [userAuth.UserAuthType.PIN, userAuth.UserAuthType.FACE], 112 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 113 }; 114 // 配置认证界面。 115 const widgetParam: userAuth.WidgetParam = { 116 title: '请进行身份认证', 117 }; 118 // 获取认证对象。 119 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 120 console.info('get userAuth instance success'); 121 // 订阅认证结果。 122 userAuthInstance.on('result', { 123 onResult(result) { 124 console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`); 125 // 可在认证结束或其他业务需要场景，取消订阅认证结果。 126 userAuthInstance.off('result'); 127 } 128 }); 129 console.info('auth on success'); 130 userAuthInstance.start(); 131 console.info('auth start success'); 132} catch (error) { 133 const err: BusinessError = error as BusinessError; 134 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 135} 136``` 137**示例2：** 138 139发起用户认证，采用认证可信等级≥ATL3的人脸+认证类型相关+复用设备解锁最大有效时长认证，获取认证结果。 140 141```ts 142// API version 10 143import { BusinessError } from '@kit.BasicServicesKit'; 144import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 145import { userAuth } from '@kit.UserAuthenticationKit'; 146 147// 设置认证参数。 148let reuseUnlockResult: userAuth.ReuseUnlockResult = { 149 reuseMode: userAuth.ReuseMode.AUTH_TYPE_RELEVANT, 150 reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION, 151} 152try { 153 const rand = cryptoFramework.createRandom(); 154 const len: number = 16; 155 let randData: Uint8Array | null = null; 156 let retryCount = 0; 157 while(retryCount < 3){ 158 randData = rand?.generateRandomSync(len)?.data; 159 if(randData){ 160 break; 161 } 162 retryCount++; 163 } 164 if(!randData){ 165 return; 166 } 167 const authParam: userAuth.AuthParam = { 168 challenge: randData, 169 authType: [userAuth.UserAuthType.FACE], 170 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 171 reuseUnlockResult: reuseUnlockResult, 172 }; 173 // 配置认证界面。 174 const widgetParam: userAuth.WidgetParam = { 175 title: '请进行身份认证', 176 }; 177 // 获取认证对象。 178 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 179 console.info('get userAuth instance success'); 180 // 订阅认证结果。 181 userAuthInstance.on('result', { 182 onResult(result) { 183 console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`); 184 // 可在认证结束或其他业务需要场景，取消订阅认证结果。 185 userAuthInstance.off('result'); 186 } 187 }); 188 console.info('auth on success'); 189 userAuthInstance.start(); 190 console.info('auth start success'); 191} catch (error) { 192 const err: BusinessError = error as BusinessError; 193 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 194} 195``` 196**示例3：** 197 198发起用户认证，采用认证可信等级≥ATL3的人脸+任意应用认证类型相关+复用任意应用最大有效时长认证，获取认证结果。 199 200```ts 201// API version 14 202import { BusinessError } from '@kit.BasicServicesKit'; 203import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 204import { userAuth } from '@kit.UserAuthenticationKit'; 205 206// 设置认证参数。 207let reuseUnlockResult: userAuth.ReuseUnlockResult = { 208 reuseMode: userAuth.ReuseMode.CALLER_IRRELEVANT_AUTH_TYPE_RELEVANT, 209 reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION, 210} 211try { 212 const rand = cryptoFramework.createRandom(); 213 const len: number = 16; 214 let randData: Uint8Array | null = null; 215 let retryCount = 0; 216 while(retryCount < 3){ 217 randData = rand?.generateRandomSync(len)?.data; 218 if(randData){ 219 break; 220 } 221 retryCount++; 222 } 223 if(!randData){ 224 return; 225 } 226 const authParam: userAuth.AuthParam = { 227 challenge: randData, 228 authType: [userAuth.UserAuthType.FACE], 229 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 230 reuseUnlockResult: reuseUnlockResult, 231 }; 232 // 配置认证界面。 233 const widgetParam: userAuth.WidgetParam = { 234 title: '请进行身份认证', 235 }; 236 // 获取认证对象。 237 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 238 console.info('get userAuth instance success'); 239 // 订阅认证结果。 240 userAuthInstance.on('result', { 241 onResult(result) { 242 console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`); 243 // 可在认证结束或其他业务需要场景，取消订阅认证结果。 244 userAuthInstance.off('result'); 245 } 246 }); 247 console.info('auth on success'); 248 userAuthInstance.start(); 249 console.info('auth start success'); 250} catch (error) { 251 const err: BusinessError = error as BusinessError; 252 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 253} 254``` 255 256**示例4：** 257 258以模应用方式拉起身份认证控件对用户进行身份认证： 259 260```ts 261// API version 18 262import { BusinessError } from '@kit.BasicServicesKit'; 263import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 264import { userAuth } from '@kit.UserAuthenticationKit'; 265 266try { 267 const rand = cryptoFramework.createRandom(); 268 const len: number = 16; 269 let randData: Uint8Array | null = null; 270 let retryCount = 0; 271 while(retryCount < 3){ 272 randData = rand?.generateRandomSync(len)?.data; 273 if(randData){ 274 break; 275 } 276 retryCount++; 277 } 278 if(!randData){ 279 return; 280 } 281 const authParam: userAuth.AuthParam = { 282 challenge: randData, 283 authType: [userAuth.UserAuthType.PIN], 284 authTrustLevel: userAuth.AuthTrustLevel.ATL3, 285 }; 286 const widgetParam: userAuth.WidgetParam = { 287 title: '请输入密码', 288 uiContext: this.getUIContext().getHostContext(), 289 }; 290 const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 291 console.info('get userAuth instance success'); 292 // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。 293 userAuthInstance.on('result', { 294 onResult (result) { 295 console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); 296 } 297 }); 298 console.info('auth on success'); 299 userAuthInstance.start(); 300 console.info('auth start success'); 301} catch (error) { 302 const err: BusinessError = error as BusinessError; 303 console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); 304} 305```
