1# User Authentication Development 2 3>  **NOTE**<br> 4> This guide applies to the SDK for API version 9. 5 6## When to Use 7 8User authentication supports facial recognition and fingerprint recognition and can be used in identity authentication scenarios such as device unlocking, application login, and payment. 9 10## Available APIs 11 12The **userIAM_userAuth** module provides APIs for user authentication, including querying authentication capabilities, and initiating or canceling authentication. Users can use biometric feature information, such as facial and fingerprints, to perform authentications. For more details about the APIs, see [User Authentication](../reference/apis/js-apis-useriam-userauth.md). 13 14Before authentication, you must specify the [authentication type](../reference/apis/js-apis-useriam-userauth.md#userauthtype8) and [authentication trust level](../reference/apis/js-apis-useriam-userauth.md#authtrustlevel8) to check whether the device supports the authentication capabilities. 15 16**Table 1** APIs of user authentication 17 18| API | Description | 19| ---------- | ----------------------- | 20| getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void | Checks whether the device supports the specified authentication type and level.| 21| getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance | Obtains an **AuthInstance** instance for user authentication.| 22| on(name : AuthEventKey, callback : AuthEvent) : void | Subscribes to the user authentication events of the specified type.| 23| off(name : AuthEventKey) : void | Unsubscribes from the user authentication events of the specific type.| 24| start: void | Starts user authentication. | 25| cancel: void | Cancel this user authentication. | 26 27## Checking Authentication Capabilities Supported by a Device 28 29### How to Develop 30 311. Apply for the permission.<br> Configure the **ohos.permission.ACCESS_BIOMETRIC** permission in **requestPermissions** in the **module.json5** file. For more information, see [module.json5](../quick-start/module-configuration-file.md). 32 332. Specify the [authentication type](../reference/apis/js-apis-useriam-userauth.md#userauthtype8) and [authentication trust level](../reference/apis/js-apis-useriam-userauth.md#authtrustlevel8), and call [getAvailableStatus](../reference/apis/js-apis-useriam-userauth.md#useriam_userauthgetavailablestatus9) to check whether the current device supports the authentication capabilities. 34 35 ```js 36 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 37 38 // Check whether the authentication capabilities are supported. 39 try { 40 userIAM_userAuth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); 41 console.info("current auth trust level is supported"); 42 } catch (error) { 43 console.info("current auth trust level is not supported, error = " + error); 44 } 45 ``` 46 47## Performing Authentication and Subscribing to the Authentication Result 48 49### How to Develop 50 511. Apply for the permission.<br> Configure the **ohos.permission.ACCESS_BIOMETRIC** permission in **requestPermissions** in the **module.json5** file. For more information, see [module.json5](../quick-start/module-configuration-file.md). 52 532. Specify the challenge, [authentication type](../reference/apis/js-apis-useriam-userauth.md#userauthtype8), and [authentication trust level](../reference/apis/js-apis-useriam-userauth.md#authtrustlevel8) to obtain an authentication object. 54 553. Use [on](../reference/apis/js-apis-useriam-userauth.md#on9) to subscribe to the authentication result. 56 574. Use [start](../reference/apis/js-apis-useriam-userauth.md#start9) to initiate an authentication and return the authentication result through [callback](../reference/apis/js-apis-useriam-userauth.md#callback9). 58 595. Use [off](../reference/apis/js-apis-useriam-userauth.md#off9) to unsubscribe from the authentication result. 60 61 ```js 62 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 63 64 let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 65 let authType = userIAM_userAuth.UserAuthType.FACE; 66 let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 67 68 // Obtain an authentication object. 69 let auth; 70 try { 71 auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 72 console.log("get auth instance success"); 73 } catch (error) { 74 console.log("get auth instance failed" + error); 75 } 76 77 // Subscribe to the authentication result. 78 try { 79 auth.on("result", { 80 callback: (result: userIAM_userAuth.AuthResultInfo) => { 81 console.log("authV9 result " + result.result); 82 console.log("authV9 token " + result.token); 83 console.log("authV9 remainAttempts " + result.remainAttempts); 84 console.log("authV9 lockoutDuration " + result.lockoutDuration); 85 } 86 }); 87 console.log("subscribe authentication event success"); 88 } catch (error) { 89 console.log("subscribe authentication event failed " + error); 90 } 91 92 // Start user authentication. 93 try { 94 auth.start(); 95 console.info("authV9 start auth success"); 96 } catch (error) { 97 console.info("authV9 start auth failed, error = " + error); 98 } 99 100 // Unsubscribe from the authentication result. 101 try { 102 auth.off("result"); 103 console.info("cancel subscribe authentication event success"); 104 } catch (error) { 105 console.info("cancel subscribe authentication event failed, error = " + error); 106 } 107 ``` 108 109## Performing Authentication and Subscribing to Authentication Tip Information 110 111### How to Develop 112 1131. Apply for the permission.<br> Configure the **ohos.permission.ACCESS_BIOMETRIC** permission in **requestPermissions** in the **module.json5** file. For more information, see [module.json5](../quick-start/module-configuration-file.md). 114 1152. Specify the challenge, [authentication type](../reference/apis/js-apis-useriam-userauth.md#userauthtype8), and [authentication trust level](../reference/apis/js-apis-useriam-userauth.md#authtrustlevel8) to obtain an authentication object. 116 1173. Use [on](../reference/apis/js-apis-useriam-userauth.md#on9) to subscribe to the authentication tip information. 118 1194. Use [start](../reference/apis/js-apis-useriam-userauth.md#start9) to initiate an authentication and return the tip information through [callback](../reference/apis/js-apis-useriam-userauth.md#callback9). 120 1215. Use [off](../reference/apis/js-apis-useriam-userauth.md#off9) to unsubscribe from the authentication tip information. 122 123 ```js 124 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 125 126 let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 127 let authType = userIAM_userAuth.UserAuthType.FACE; 128 let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 129 130 // Obtain an authentication object. 131 let auth; 132 try { 133 auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 134 console.log("get auth instance success"); 135 } catch (error) { 136 console.log("get auth instance failed" + error); 137 } 138 139 // Subscribe to authentication tip information. 140 try { 141 auth.on("tip", { 142 callback : (result : userIAM_userAuth.TipInfo) => { 143 switch (result.tip) { 144 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT: 145 // Do something. 146 case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK: 147 // Do something. 148 default: 149 // Do others. 150 } 151 } 152 }); 153 console.log("subscribe authentication event success"); 154 } catch (error) { 155 console.log("subscribe authentication event failed " + error); 156 } 157 158 // Start user authentication. 159 try { 160 auth.start(); 161 console.info("authV9 start auth success"); 162 } catch (error) { 163 console.info("authV9 start auth failed, error = " + error); 164 } 165 166 // Unsubscribe from authentication tip information. 167 try { 168 auth.off("tip"); 169 console.info("cancel subscribe tip information success"); 170 } catch (error) { 171 console.info("cancel subscribe tip information failed, error = " + error); 172 } 173 ``` 174 175## Canceling User Authentication 176 177### How to Develop 178 1791. Apply for the permission.<br> Configure the **ohos.permission.ACCESS_BIOMETRIC** permission in **requestPermissions** in the **module.json5** file. For more information, see [module.json5](../quick-start/module-configuration-file.md). 180 1812. Specify the challenge, [authentication type](../reference/apis/js-apis-useriam-userauth.md#userauthtype8), and [authentication trust level](../reference/apis/js-apis-useriam-userauth.md#authtrustlevel8) to obtain an authentication object. 182 1833. Use [start](../reference/apis/js-apis-useriam-userauth.md#start9) to initiate an authentication. 184 1854. Use [cancel](../reference/apis/js-apis-useriam-userauth.md#cancel9) to cancel this authentication. 186 187 ```js 188 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 189 190 let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); 191 let authType = userIAM_userAuth.UserAuthType.FACE; 192 let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; 193 194 // Obtain an authentication object. 195 let auth; 196 try { 197 auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel); 198 console.log("get auth instance success"); 199 } catch (error) { 200 console.log("get auth instance failed" + error); 201 } 202 203 // Start user authentication. 204 try { 205 auth.start(); 206 console.info("authV9 start auth success"); 207 } catch (error) { 208 console.info("authV9 start auth failed, error = " + error); 209 } 210 211 // Cancel the authentication. 212 try { 213 auth.cancel(); 214 console.info("cancel auth success"); 215 } catch (error) { 216 console.info("cancel auth failed, error = " + error); 217 } 218 ``` 219
