# User Authentication >**NOTE:** >The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import ``` import userIAM_userAuth from '@ohos.userIAM.userAuth'; ``` ## Required Permissions ohos.permission.ACCESS\_BIOMETRIC ## Sample Code ``` import userIAM_userAuth from '@ohos.userIAM.userAuth'; export default { startAuth() { console.info("start auth"); let tipCallback = (tip)=>{ console.info("receive tip: errorCode(" + tip.errorCode + ") code(" + tip.tipCode + ") event(" + tip.tipEvent + ") info(" + tip.tipInfo + ")"); // Add the logic for displaying the prompt message. }; let auth = userIAM_userAuth.getAuthenticator(); auth.on("tip", tipCallback); auth.execute("FACE_ONLY", "S2").then((code)=>{ auth.off("tip", tipCallback); console.info("auth success"); // Add the logic for authentication success. }).catch((code)=>{ auth.off("tip", tipCallback); console.error("auth fail, code = " + code); // Add the logic for authentication failure. }); }, checkAuthSupport() { console.info("start check auth support"); let auth = userIAM_userAuth.getAuthenticator(); let checkCode = auth.checkAvailability("FACE_ONLY", "S2"); if (checkCode == userIAM_userAuth.CheckAvailabilityResult.SUPPORTED) { console.info("check auth support success"); // Add the logic for the specified authentication type supported. } else { console.error("check auth support fail, code = " + checkCode); // Add the logic for the authentication type that is not supported. } }, cancelAuth() { console.info("start cancel auth"); let auth = userIAM_userAuth.getAuthenticator(); let cancelCode = auth.cancel(); if (cancelCode == userIAM_userAuth.Result.SUCCESS) { console.info("cancel auth success"); } else { console.error("cancel auth fail"); } } } ``` ## userIAM\_userAuth.getAuthenticator getAuthenticator\(\): Authenticator Obtains an **Authenticator** object for user authentication. ⁶⁺ Obtains an **Authenticator** object to check the device's capability of user authentication, perform or cancel user authentication, and obtain the tips generated in the authentication process. ⁷⁺ - Return values

Type	Description
Authenticator	Authenticator object obtained.

- Example ``` let authenticator = userIAM_userAuth.getAuthenticator(); ``` ## Authenticator Provides an **Authenticator** object. ### execute execute\(type: string, level: string, callback: AsyncCallback\): void Performs user authentication and returns the authentication result using an asynchronous callback. - Parameters

Name	Type	Mandatory	Description
type	string	Yes	Authentication type. Only FACE_ONLY is supported. ALL is reserved and not supported by the current version.
level	string	Yes	Security level of the authentication. It can be S1 (lowest), S2, S3, or S4 (highest). Devices capable of 3D facial recognition support S3 and lower-level authentication. Devices capable of 2D facial recognition support S2 and lower-level authentication.
callback	AsyncCallback<number>	No	Callback invoked to return the authentication result

Name

Type

Mandatory

Description

type

string

Yes

Authentication type. Only FACE_ONLY is supported.

ALL is reserved and not supported by the current version.

level

string

Yes

Security level of the authentication. It can be S1 (lowest), S2, S3, or S4 (highest).

Devices capable of 3D facial recognition support S3 and lower-level authentication.

Devices capable of 2D facial recognition support S2 and lower-level authentication.

callback

AsyncCallback<number>

Callback invoked to return the authentication result

Callback return values

Type	Description
number	Authentication result. See AuthenticationResult.

- Example ``` authenticator.execute("FACE_ONLY", "S2", (code)=>{ if (code == userIAM_userAuth.AuthenticationResult.SUCCESS) { console.info("auth success"); return; } console.error("auth fail, code = " + code); }) ``` ### execute execute\(type:string, level:string\): Promise Performs user authentication and returns the authentication result using a promise. - Parameters

Name	Type	Mandatory	Description
type	string	Yes	Authentication type. Only FACE_ONLY is supported. ALL is reserved and not supported by the current version.
level	string	Yes	Security level of the authentication. It can be S1 (lowest), S2, S3, or S4 (highest). Devices capable of 3D facial recognition support S3 and lower-level authentication. Devices capable of 2D facial recognition support S2 and lower-level authentication.

Name

Type

Mandatory

Description

type

string

Yes

Authentication type. Only FACE_ONLY is supported.

ALL is reserved and not supported by the current version.

level

string

Yes

Security level of the authentication. It can be S1 (lowest), S2, S3, or S4 (highest).

Devices capable of 3D facial recognition support S3 and lower-level authentication.

Devices capable of 2D facial recognition support S2 and lower-level authentication.

- Return values

Type	Description
Promise<number>	Promise used to return the authentication result. The number in the promise indicates the authentication result. See AuthenticationResult.

- Example ``` let authenticator = userIAM_userAuth.getAuthenticator(); authenticator.execute("FACE_ONLY", "S2").then((code)=>{ authenticator.off("tip", tipCallback); console.info("auth success"); }).catch((code)=>{ authenticator.off("tip", tipCallback); console.error("auth fail, code = " + code); }); ``` ### cancel⁷⁺ cancel\(\): number Cancels the current authentication. - Return values

Type	Description
number	Whether the authentication is canceled. For details, see Result.

- Example ``` let authenticator = userIAM_userAuth.getAuthenticator(); let cancelCode = authenticator.cancel(); if (cancelCode == userIAM_userAuth.Result.SUCCESS) { console.info("cancel auth success"); } else { console.error("cancel auth fail"); } ``` ### checkAvailability⁷⁺ checkAvailability\(type: AuthType, level: SecureLevel\): number Checks whether the device supports the specified authentication type and security level. - Parameters

Name	Type	Mandatory	Description
type	string	Yes	Authentication type. Only FACE_ONLY is supported. ALL is reserved and not supported by the current version.
level	string	Yes	Security level of the authentication. It can be S1 (lowest), S2, S3, or S4 (highest). Devices capable of 3D facial recognition support S3 and lower-level authentication. Devices capable of 2D facial recognition support S2 and lower-level authentication.

Name

Type

Mandatory

Description

type

string

Yes

Authentication type. Only FACE_ONLY is supported.

ALL is reserved and not supported by the current version.

level

string

Yes

Security level of the authentication. It can be S1 (lowest), S2, S3, or S4 (highest).

Devices capable of 3D facial recognition support S3 and lower-level authentication.

Devices capable of 2D facial recognition support S2 and lower-level authentication.

- Return values

Type	Description
number	Check result. For details, see CheckAvailabilityResult.

- Example ``` let authenticator = userIAM_userAuth.getAuthenticator(); let checkCode = authenticator.checkAvailability("FACE_ONLY", "S2"); if (checkCode == userIAM_userAuth.CheckAvailabilityResult.SUPPORTED) { console.info("check auth support success"); } else { console.error("check auth support fail, code = " + checkCode); } ``` ### on⁷⁺ on\(type: "tip", callback: Callback\) : void; Subscribes to the events of the specified type. - Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. Currently, only tip is supported. An event is triggered when the authentication service sends a message to the caller.
callback	Callback<Tip>	Yes	Callback used to report the event of the specified type. Currently, only the tip event is supported.

- Example ``` let authenticator = userIAM_userAuth.getAuthenticator(); let tipCallback = (tip)=>{ console.info("receive tip: errorCode(" + tip.errorCode + ") code(" + tip.tipCode +") event(" + tip.tipEvent + ") info(" + tip.tipInfo + ")"); }; authenticator.on("tip", tipCallback); ``` ### off⁷⁺ off\(type: "tip", callback?: Callback\) : void; Unsubscribes from the events of the specified type. - Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. Currently, only tip is supported.
callback	Callback<Tip>	No	Callback used to report the event of the specified type. Currently, only the tip event is supported. If this parameter is not specified, all callbacks corresponding to type will be canceled.

- Example ``` let authenticator = userIAM_userAuth.getAuthenticator(); let tipCallback = (tip)=>{ console.info("receive tip: errorCode(" + tip.errorCode + ") code(" + tip.tipCode + ") event(" + tip.tipEvent + ") info(" + tip.tipInfo + ")"); }; // Unsubscribe from a specified callback. authenticator.off("tip", tipCallback); // Unsubscribe from all callbacks. authenticator.off("tip"); ``` ## AuthenticationResult Enumerates the authentication results.

Name	Default Value	Description
NO_SUPPORT	-1	The device does not support the current authentication mode.
SUCCESS	0	The authentication is successful.
COMPARE_FAILURE	1	The feature comparison failed.
CANCELED	2	The user cancels the authentication.
TIMEOUT	3	The authentication has timed out.
CAMERA_FAIL	4	The camera failed to start.
BUSY	5	The authentication service is not available. Try again later.
INVALID_PARAMETERS	6	The authentication parameters are invalid.
LOCKED	7	The user account is locked because the number of authentication failures has reached the threshold.
NOT_ENROLLED	8	No authentication credential is registered.
GENERAL_ERROR	100	Other errors.

## Tip⁷⁺ Defines the object of the tip generated during the authentication process.

Name	Type	Mandatory	Description
errorCode	number	Yes	Whether the tip is obtained successfully. For details, see Result.
tipEvent	number	Yes	Tip event. For details, see TipEvent. Currently, only RESULT and ACQUIRE are supported.
tipCode	number	Yes	Tip code. If tipEvent is RESULT, the tip code provides the authentication result. For details, see AuthenticationResult. If tipEvent is ACQUIRE, the tip code provides prompt information. For details, see TipCode.
tipInfo	string	Yes	Description of the tip code.

## Result⁷⁺ Enumerates the operation results.

Name	Default Value	Description
SUCCESS	0	Successful
FAILED	1	Failed

## CheckAvailabilityResult⁷⁺ Enumerates the device authentication capability check results.

Name	Default Value	Description
SUPPORTED	0	The device supports the specified authentication type and security level.
AUTH_TYPE_NOT_SUPPORT	1	The device does not support the specified authentication type.
SECURE_LEVEL_NOT_SUPPORT	2	The device does not support the specified authentication security level.
DISTRIBUTED_AUTH_NOT_SUPPORT	3	The device does not support distributed authentication.
NOT_ENROLLED	4	The device does not have the authentication credential.
PARAM_NUM_ERROR	5	The number of parameters is incorrect.

## TipEvent⁷⁺ Enumerates the tip events occurred during the authentication process.

Name	Default Value	Description
RESULT	1	Credential enrollment result or authentication result.
CANCEL	2	Credential enrollment or authentication canceled.
ACQUIRE	3	Tips generated in the credential enrollment or authentication process.
BUSY	4	Credential enrollment or authentication unavailable.
OUT_OF_MEM	5	Insufficient memory.
FACE_ID	6	Index of a face authentication credential.

## TipCode⁷⁺ Enumerates the tip codes generated during the authentication process.

Name	Default Value	Description
FACE_AUTH_TIP_TOO_BRIGHT	1	The obtained facial image is too bright due to high illumination.
FACE_AUTH_TIP_TOO_DARK	2	The obtained facial image is too dark due to low illumination.
FACE_AUTH_TIP_TOO_CLOSE	3	The face is too close to the device.
FACE_AUTH_TIP_TOO_FAR	4	The face is too far away from the device.
FACE_AUTH_TIP_TOO_HIGH	5	Only the upper part of the face is captured because the device is angled too high.
FACE_AUTH_TIP_TOO_LOW	6	Only the lower part of the face is captured because the device is angled too low.
FACE_AUTH_TIP_TOO_RIGHT	7	Only the right part of the face is captured because the device is deviated to the right.
FACE_AUTH_TIP_TOO_LEFT	8	Only the left part of the face is captured because the device is deviated to the left.
FACE_AUTH_TIP_TOO_MUCH_MOTION	9	The face moves too fast during facial information collection.
FACE_AUTH_TIP_POOR_GAZE	10	The face is not facing the camera.
FACE_AUTH_TIP_NOT_DETECTED	11	No face is detected.