1# User Authentication Development 2 3>  **NOTE**<br/> 4> This development guide applies to the SDK of API Version 8 or later. 5 6## When to Use 7 82D and 3D facial recognition used in identity authentication scenarios such as device unlocking, application login, and payment 9 10## Available APIs 11 12The userIAM_userAuth module provides methods for checking the support for user authentication, and performing and canceling authentication. You can perform authentication based on biometric features such as facial characteristics. For more details, see [API Reference](../reference/apis/js-apis-useriam-userauth.md). 13 14Before performing authentication, check whether the device supports user authentication, including the authentication type and level. If user authentication is not supported, consider using another authentication type. The following table lists the APIs available for user authentication. 15 16**Table 1** APIs of user authentication 17 18| API | Description | 19| ------------------------------------------------------------ | ------------------------------------------------------------ | 20| getVersion() : number | Obtains the version information of an authentication object. | 21| getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number | Checks whether the device supports the specified authentication type and level.| 22| auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array | Performs user authentication. This method uses asynchronous callback to return the result. | 23| cancelAuth(contextID : Uint8Array) : number | Cancels an authentication. | 24 25## How to Develop 26 27Before starting the development, make the following preparations: 28 291. Add the ohos.permission.ACCESS_BIOMETRIC permission declaration to the application permission file. 302. Add **import userIAM_userAuth from '@ohos.userIAM.userAuth'** to the code file. 31 32The development procedure is as follows: 33 341. Obtain an **Authenticator** singleton object. The sample code is as follows: 35 36 ```js 37 let auth = new userIAM_userAuth.UserAuth(); 38 ``` 39 402. (Optional) Obtain the version information of the authenticated object. 41 42 ```js 43 let auth = new userIAM_userAuth.UserAuth(); 44 let version = auth.getVersion(); 45 console.info("auth version = " + version); 46 ``` 47 483. Check whether the device supports the authentication capabilities based on the specified authentication type and level. 49 50 ```js 51 let auth = new userIAM_userAuth.UserAuth(); 52 let checkCode = auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); 53 if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) { 54 console.info("check auth support success"); 55 // Add the logic to be executed if the specified authentication type is supported. 56 } else { 57 console.error("check auth support fail, code = " + checkCode); 58 // Add the logic to be executed if the specified authentication type is not supported. 59 } 60 ``` 61 624. Perform an authentication. 63 64 ```js 65 let auth = new userIAM_userAuth.UserAuth(); 66 auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 67 onResult: (result, extraInfo) => { 68 try { 69 console.info("auth onResult result = " + result); 70 console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo)); 71 if (result == 'SUCCESS') { 72 // Add the logic to be executed when the authentication is successful. 73 } else { 74 // Add the logic to be executed when the authentication fails. 75 } 76 } catch (e) { 77 console.info("auth onResult error = " + e); 78 } 79 }, 80 81 onAcquireInfo: (module, acquire, extraInfo) => { 82 try { 83 console.info("auth onAcquireInfo module = " + module); 84 console.info("auth onAcquireInfo acquire = " + acquire); 85 console.info("auth onAcquireInfo extraInfo = " + JSON.stringify(extraInfo)); 86 } catch (e) { 87 console.info("auth onAcquireInfo error = " + e); 88 } 89 } 90 }); 91 ``` 92 935. Cancel the authentication. 94 95 ```js 96 let auth = new userIAM_userAuth.UserAuth(); 97 // Obtain contextId using auth(). 98 let contextId = auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, { 99 onResult: (result, extraInfo) => { 100 console.info("auth onResult result = " + result); 101 }, 102 103 onAcquireInfo: (module, acquire, extraInfo) => { 104 console.info("auth onAcquireInfo module = " + module); 105 } 106 }); 107 let cancelCode = auth.cancel(contextId); 108 if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) { 109 console.info("cancel auth success"); 110 } else { 111 console.error("cancel auth fail"); 112 } 113 ``` 114
