1# User Authentication Development 2 3> **NOTE** 4> 5> This guide applies to the SDK for API version 10. 6 7## When to Use 8 9OpenHarmony supports PIN authentication, facial authentication, and fingerprint authentication, which can be used in identity authentication scenarios such as device unlocking, app login, and payment. 10 11## Available APIs 12 13The **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). 14 15Before 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. 16 17**Table 1** APIs of user authentication 18 19| API | Description | 20| ---------- | ----------------------- | 21| getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void | Checks whether the device supports the specified authentication type and level.| 22| getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance | Obtains a **UserAuthInstance** instance for user authentication. The user authentication widget is supported.| 23| on(type: 'result', callback: IAuthCallback): void | Subscribes to the user authentication result.| 24| off(type: 'result', callback?: IAuthCallback): void | Unsubscribes from the user authentication result.| 25| start(): void | Starts user authentication. | 26| cancel(): void | Cancels this user authentication. | 27 28**Table 2** Authentication trust levels 29 30| Authentication Trust Level| Metrics | Description and Example | Typical Service Scenario | 31| -------------------------- | --------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------- | 32| ATL4 | When FRR = 10%, FAR ≤ 0.003%, SAR ≤ 3% | The authentication can accurately identify individual users and provides powerful liveness detection capabilities. For example, PIN authentication with a secure keyboard and fingerprint and 3D facial authentication with special security enhancement. | Small-amount payment | 33| ATL3 | When FRR = 10%, FAR ≤ 0.002%, SAR ≤ 7% | The authentication can accurately identify individual users and provides strong liveness detection capabilities. For example, 2D facial authentication with special security enhancement. | Device unlocking | 34| ATL2 | When FRR = 10%, FAR ≤ 0.002%, 7% < SAR ≤ 20%| The authentication can accurately identify individual users and provides regular liveness detection capabilities. For example, using a watch based on common ranging as a trusted holder to unlock a device. | Logins to apps and keeping a device unlocked | 35| ATL1 | When FRR = 10%, FAR ≤ 1%, 7% < SAR ≤ 20% | The authentication can identify individual users and provides limited liveness detection capabilities. For example, voiceprint authentication. | Service risk control, query of general personal data, targeted recommendations, and personalized services| 36 37> **NOTE** 38> 39> - FRR: False Reject Rate 40> - FAR: False Acceptance Rate 41> - SAR: Spoof Acceptance Rate 42 43## Checking Authentication Capabilities Supported by a Device 44 45### How to Develop 46 471. 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). 48 492. 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. 50 51 ```ts 52 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 53 54 // Check whether the authentication capabilities are supported. 55 try { 56 userIAM_userAuth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1); 57 console.info('current auth trust level is supported'); 58 } catch (error) { 59 console.info('current auth trust level is not supported, error = ' + error); 60 } 61 ``` 62 63## Performing Authentication and Subscribing to the Authentication Result 64 65### How to Develop 66 671. 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). 68 692. 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. 70 713. Call [on](../reference/apis/js-apis-useriam-userauth.md#on10) to subscribe to the authentication result. 72 734. Call [start](../reference/apis/js-apis-useriam-userauth.md#start10) to start authentication and return the authentication result through the [callback](../reference/apis/js-apis-useriam-userauth.md#callback10). 74 75 ```ts 76 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 77 78 const authParam : userIAM_userAuth.AuthParam = { 79 challenge: new Uint8Array([49, 49, 49, 49, 49, 49]), 80 authType: [userIAM_userAuth.UserAuthType.PIN], 81 authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1, 82 }; 83 const widgetParam : userIAM_userAuth.WidgetParam = { 84 title:'Enter password', 85 }; 86 try { 87 // Obtain an authentication object. 88 let userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam); 89 console.log('get userAuth instance success'); 90 // Subscribe to the authentication result. 91 userAuthInstance.on('result', { 92 onResult (result) { 93 console.log('userAuthInstance callback result = ' + JSON.stringify(result)); 94 } 95 }); 96 console.log('auth on success'); 97 userAuthInstance.start(); 98 console.log('auth start success'); 99 } catch (error) { 100 console.log('auth catch error: ' + JSON.stringify(error)); 101 } 102 ``` 103 1045. Call [off](../reference/apis/js-apis-useriam-userauth.md#off10) for the [UserAuthInstance](../reference/apis/js-apis-useriam-userauth.md#userauthinstance10) object to unsubscribe from the authentication result. 105 106 ```ts 107 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 108 109 const authParam : userIAM_userAuth.AuthParam = { 110 challenge: new Uint8Array([49, 49, 49, 49, 49, 49]), 111 authType: [userIAM_userAuth.UserAuthType.PIN], 112 authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1, 113 }; 114 const widgetParam : userIAM_userAuth.WidgetParam = { 115 title:'Enter password', 116 }; 117 try { 118 // Obtain an authentication object. 119 let userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam); 120 console.log('get userAuth instance success'); 121 // Unsubscribe from the authentication result. 122 userAuthInstance.off('result', { 123 onResult (result) { 124 console.log('auth off result: ' + JSON.stringify(result)); 125 } 126 }); 127 console.log('auth off success'); 128 } catch (error) { 129 console.log('auth catch error: ' + JSON.stringify(error)); 130 } 131 ``` 132 133## Canceling User Authentication 134 135### How to Develop 136 1371. 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). 138 1392. 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. 140 1413. Call [start](../reference/apis/js-apis-useriam-userauth.md#start10) to start authentication. 142 1434. Call [cancel](../reference/apis/js-apis-useriam-userauth.md#cancel10) for the [UserAuthInstance](../reference/apis/js-apis-useriam-userauth.md#userauthinstance10) object to cancel this authentication. 144 145 ```ts 146 import userIAM_userAuth from '@ohos.userIAM.userAuth'; 147 148 const authParam : userIAM_userAuth.AuthParam = { 149 challenge: new Uint8Array([49, 49, 49, 49, 49, 49]), 150 authType: [userIAM_userAuth.UserAuthType.PIN], 151 authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1, 152 }; 153 const widgetParam : userIAM_userAuth.WidgetParam = { 154 title:'Enter password', 155 }; 156 try { 157 // Obtain an authentication object. 158 let userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam); 159 console.log('get userAuth instance success'); 160 // Start user authentication. 161 userAuthInstance.start(); 162 console.log('auth start success'); 163 // Cancel the authentication. 164 userAuthInstance.cancel(); 165 console.log('auth cancel success'); 166 } catch (error) { 167 console.log('auth catch error: ' + JSON.stringify(error)); 168 } 169 ``` 170