@ohos.userIAM.userAuth (User Authentication)

The userIAM.userAuth module provides user authentication capabilities in identity authentication scenarios, such as device unlocking, payment, and app login.

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';

AuthResultInfo⁹⁺

Defines the authentication result.

System capability: SystemCapability.UserIAM.UserAuth.Core

TipInfo⁹⁺

Defines the authentication tip information.

System capability: SystemCapability.UserIAM.UserAuth.Core

EventInfo⁹⁺

Enumerates the authentication event information types.

System capability: SystemCapability.UserIAM.UserAuth.Core

AuthEventKey⁹⁺

Defines the keyword of the authentication event type. It is used as a parameter of on.

AuthEvent⁹⁺

Provides an asynchronous callback to return the authentication event information.

callback⁹⁺

callback(result : EventInfo) : void

Called to return the authentication result or authentication tip information.

System capability: SystemCapability.UserIAM.UserAuth.Core

Parameters

Example

import userIAM_userAuth from '@ohos.userIAM.userAuth';

let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE;
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
// Obtain the authentication result through a callback.
try {
    let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
    auth.on("result", {
        callback: (result: userIAM_userAuth.AuthResultInfo) => {
            console.log("authV9 result " + result.result);
            console.log("authV9 token " + result.token);
            console.log("authV9 remainAttempts " + result.remainAttempts);
            console.log("authV9 lockoutDuration " + result.lockoutDuration);
        }
    });
    auth.start();
    console.log("authV9 start success");
} catch (error) {
    console.log("authV9 error = " + error);
    // do error
}
// Obtain the authentication tip information through a callback.
try {
    let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
    auth.on("tip", {
        callback : (result : userIAM_userAuth.TipInfo) => {
            switch (result.tip) {
                case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT:
                // Do something;
                case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK:
                // Do something.
                default:
                // Do others.
            }
        }
    });
    auth.start();
    console.log("authV9 start success");
} catch (error) {
    console.log("authV9 error = " + error);
    // do error
}

AuthInstance⁹⁺

Implements user authentication.

on⁹⁺

on : (name : AuthEventKey, callback : AuthEvent) => void

Subscribes to the user authentication events of the specified type.

NOTE
Use the AuthInstance instance obtained to invoke this API to subscribe to events.

System capability: SystemCapability.UserIAM.UserAuth.Core

Parameters

For details about the error codes, see User Authentication Error Codes.

Error codes

Example

import userIAM_userAuth from '@ohos.userIAM.userAuth';

let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE;
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
try {
    let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
    // Subscribe to the authentication result.
    auth.on("result", {
        callback: (result: userIAM_userAuth.AuthResultInfo) => {
            console.log("authV9 result " + result.result);
            console.log("authV9 token " + result.token);
            console.log("authV9 remainAttempts " + result.remainAttempts);
            console.log("authV9 lockoutDuration " + result.lockoutDuration);
        }
    });
    // Subscribe to authentication tip information.
    auth.on("tip", {
        callback : (result : userIAM_userAuth.TipInfo) => {
            switch (result.tip) {
                case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_BRIGHT:
                // Do something;
                case userIAM_userAuth.FaceTips.FACE_AUTH_TIP_TOO_DARK:
                // Do something.
                default:
                // Do others.
            }
        }
    });
    auth.start();
    console.log("authV9 start success");
} catch (error) {
    console.log("authV9 error = " + error);
    // do error
}

off⁹⁺

off : (name : AuthEventKey) => void

Unsubscribes from the user authentication events of the specific type.

NOTE
Use the AuthInstance instance obtained to invoke this API to unsubscribe from events.

System capability: SystemCapability.UserIAM.UserAuth.Core

For details about the error codes, see User Authentication Error Codes.

Error codes

Example

import userIAM_userAuth from '@ohos.userIAM.userAuth';

let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE;
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;
let auth;
try {
    auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
    console.log("get auth instance success");
} catch (error) {
    console.log("get auth instance failed" + error);
}

try {
    // Subscribe to the authentication result.
    auth.on("result", {
        callback: (result: userIAM_userAuth.AuthResultInfo) => {
            console.log("authV9 result " + result.result);
            console.log("authV9 token " + result.token);
            console.log("authV9 remainAttempts " + result.remainAttempts);
            console.log("authV9 lockoutDuration " + result.lockoutDuration);
        }
    });
    console.log("subscribe authentication event success");
} catch (error) {
    console.log("subscribe authentication event failed " + error);
}
// Unsubscribe from the authentication result.
try {
    auth.off("result");
    console.info("cancel subscribe authentication event success");
} catch (error) {
    console.info("cancel subscribe authentication event failed, error = " + error);
}

start⁹⁺

start : () => void

Starts authentication.

NOTE
Use the AuthInstance instance obtained to invoke this API.

Required permissions: ohos.permission.ACCESS_BIOMETRIC

System capability: SystemCapability.UserIAM.UserAuth.Core

For details about the error codes, see User Authentication Error Codes.

Error codes

Example

import userIAM_userAuth from '@ohos.userIAM.userAuth';

let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE;
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;

try {
    let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
    auth.start();
    console.info("authV9 start auth success");
} catch (error) {
    console.info("authV9 start auth failed, error = " + error);
}

cancel⁹⁺

cancel : () => void

Cancels this authentication.

NOTE
Use the AuthInstance instance obtained to invoke this API. The AuthInstance instance must be the one being authenticated.

Required permissions: ohos.permission.ACCESS_BIOMETRIC

System capability: SystemCapability.UserIAM.UserAuth.Core

For details about the error codes, see User Authentication Error Codes.

Error codes

Example

import userIAM_userAuth from '@ohos.userIAM.userAuth';

let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE;
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;

try {
    let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
    auth.cancel();
    console.info("cancel auth success");
} catch (error) {
    console.info("cancel auth failed, error = " + error);
}

userIAM_userAuth.getAuthInstance⁹⁺

getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance

Obtains an AuthInstance instance for user authentication.

NOTE
An AuthInstance instance can be used for an authentication only once.

System capability: SystemCapability.UserIAM.UserAuth.Core

Parameters

Return value

For details about the error codes, see User Authentication Error Codes.

Error codes

Example

import userIAM_userAuth from '@ohos.userIAM.userAuth';

let challenge = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
let authType = userIAM_userAuth.UserAuthType.FACE;
let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1;

try {
    let auth = userIAM_userAuth.getAuthInstance(challenge, authType, authTrustLevel);
    console.info("get auth instance success");
} catch (error) {
    console.info("get auth instance success failed, error = " + error);
}

userIAM_userAuth.getAvailableStatus⁹⁺

getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void

Checks whether the specified authentication capability is supported.

Required permissions: ohos.permission.ACCESS_BIOMETRIC

System capability: SystemCapability.UserIAM.UserAuth.Core

Parameters

For details about the error codes, see User Authentication Error Codes.

Error codes

Example

import userIAM_userAuth from '@ohos.userIAM.userAuth';

try {
    userIAM_userAuth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1);
    console.info("current auth trust level is supported");
} catch (error) {
    console.info("current auth trust level is not supported, error = " + error);
}

UserAuthResultCode⁹⁺

Enumerates the authentication result codes.

System capability: SystemCapability.UserIAM.UserAuth.Core

UserAuth⁸⁺

Provides APIs to manage an Authenticator object.

constructor^(deprecated)

constructor()

A constructor used to create an authenticator instance.

NOTE
This API is supported since API version 8 and deprecated since API version 9. You are advised to use getAuthInstance.

System capability: SystemCapability.UserIAM.UserAuth.Core

Return value

Example

import userIAM_userAuth from '@ohos.userIAM.userAuth';

let auth = new userIAM_userAuth.UserAuth();

getVersion^(deprecated)

getVersion() : number

Obtains the version of this authenticator.

NOTE
This API is supported since API version 8 and deprecated since API version 9.

Required permissions: ohos.permission.ACCESS_BIOMETRIC

System capability: SystemCapability.UserIAM.UserAuth.Core

Return value

Example

import userIAM_userAuth from '@ohos.userIAM.userAuth';

let auth = new userIAM_userAuth.UserAuth();
let version = auth.getVersion();
console.info("auth version = " + version);

getAvailableStatus^(deprecated)

getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number

Checks whether the specified authentication capability is supported.

NOTE
This API is supported since API version 8 and deprecated since API version 9. You are advised to use getAvailableStatus.

Required permissions: ohos.permission.ACCESS_BIOMETRIC

System capability: SystemCapability.UserIAM.UserAuth.Core

Parameters

Return value

Example

import userIAM_userAuth from '@ohos.userIAM.userAuth';

let auth = new userIAM_userAuth.UserAuth();
let checkCode = auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1);
if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) {
    console.info("check auth support success");
} else {
    console.error("check auth support fail, code = " + checkCode);
}

auth^(deprecated)

auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array

Performs user authentication. This API uses a callback to return the result.

NOTE
This API is supported since API version 8 and deprecated since API version 9. You are advised to use start.

Required permissions: ohos.permission.ACCESS_BIOMETRIC

System capability: SystemCapability.UserIAM.UserAuth.Core

Parameters

Return value

Example

import userIAM_userAuth from '@ohos.userIAM.userAuth';

let auth = new userIAM_userAuth.UserAuth();
auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, {
    onResult: (result, extraInfo) => {
        try {
            console.info("auth onResult result = " + result);
            console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo));
            if (result == userIAM_userAuth.ResultCode.SUCCESS) {
                // Add the logic to be executed when the authentication is successful.
            } else {
                // Add the logic to be executed when the authentication fails.
            }
        } catch (e) {
            console.info("auth onResult error = " + e);
        }
    }
});

cancelAuth^(deprecated)

cancelAuth(contextID : Uint8Array) : number

Cancels an authentication based on the context ID.

NOTE
This API is supported since API version 8 and deprecated since API version 9. You are advised to use cancel.

Required permissions: ohos.permission.ACCESS_BIOMETRIC

System capability: SystemCapability.UserIAM.UserAuth.Core

Parameters

Return value

Example

import userIAM_userAuth from '@ohos.userIAM.userAuth';

// contextId can be obtained by auth(). In this example, it is defined here.
let contextId = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]);
let auth = new userIAM_userAuth.UserAuth();
let cancelCode = auth.cancelAuth(contextId);
if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) {
    console.info("cancel auth success");
} else {
    console.error("cancel auth fail");
}

IUserAuthCallback^(deprecated)

Provides callbacks to return the authentication result.

NOTE
This object is supported since API version 8 and deprecated since API version 9. You are advised to use AuthEvent.

onResult^(deprecated)

onResult: (result : number, extraInfo : AuthResult) => void

Called to return the authentication result.

NOTE
This API is supported since API version 8 and deprecated since API version 9. You are advised to use callback.

System capability: SystemCapability.UserIAM.UserAuth.Core

Parameters

Example

import userIAM_userAuth from '@ohos.userIAM.userAuth';

let auth = new userIAM_userAuth.UserAuth();
auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, {
    onResult: (result, extraInfo) => {
        try {
            console.info("auth onResult result = " + result);
            console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo));
            if (result == userIAM_userAuth.ResultCode.SUCCESS) {
                // Add the logic to be executed when the authentication is successful.
            }  else {
                // Add the logic to be executed when the authentication fails.
            }
        } catch (e) {
            console.info("auth onResult error = " + e);
        }
    }
});

onAcquireInfo^(deprecated)

onAcquireInfo ?: (module : number, acquire : number, extraInfo : any) => void

Called to acquire authentication tip information. This API is optional.

NOTE
This API is supported since API version 8 and deprecated since API version 9. You are advised to use callback.

System capability: SystemCapability.UserIAM.UserAuth.Core

Parameters

Example

import userIAM_userAuth from '@ohos.userIAM.userAuth';

let auth = new userIAM_userAuth.UserAuth();
auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, {
    onAcquireInfo: (module, acquire, extraInfo) => {
        try {
            console.info("auth onAcquireInfo module = " + module);
            console.info("auth onAcquireInfo acquire = " + acquire);
            console.info("auth onAcquireInfo extraInfo = " + JSON.stringify(extraInfo));
        } catch (e) {
            console.info("auth onAcquireInfo error = " + e);
        }
    }
});

AuthResult^(deprecated)

Represents the authentication result object.

NOTE
This object is supported since API version 8 and deprecated since API version 9. You are advised to use AuthResultInfo.

System capability: SystemCapability.UserIAM.UserAuth.Core

ResultCode^(deprecated)

Enumerates the authentication result codes.

NOTE
This object is deprecated since API version 9. You are advised to use UserAuthResultCode.

System capability: SystemCapability.UserIAM.UserAuth.Core

FaceTips⁸⁺

Enumerates the tip codes used during the facial authentication process.

System capability: SystemCapability.UserIAM.UserAuth.Core

FingerprintTips⁸⁺

Enumerates the tip codes used during the fingerprint authentication process.

System capability: SystemCapability.UserIAM.UserAuth.Core

UserAuthType⁸⁺

Enumerates the identity authentication types.

System capability: SystemCapability.UserIAM.UserAuth.Core

AuthTrustLevel⁸⁺

Enumerates the trust levels of the authentication result.

System capability: SystemCapability.UserIAM.UserAuth.Core

userIAM_userAuth.getAuthenticator^(deprecated)

getAuthenticator(): Authenticator

Obtains an Authenticator instance for user authentication.

NOTE
This API is deprecated since API version 8. You are advised to use constructor.

System capability: SystemCapability.UserIAM.UserAuth.Core

Return value

Example

let authenticator = userIAM_userAuth.getAuthenticator();

Authenticator^(deprecated)

Defines the Authenticator object.

NOTE
This object is deprecated since API version 8. You are advised to use UserAuth.

execute^(deprecated)

execute(type: AuthType, level: SecureLevel, callback: AsyncCallback<number>): void

Performs user authentication. This API uses asynchronous callback to return the result.

NOTE
This API is deprecated since API version 8. You are advised to use auth.

Required permissions: ohos.permission.ACCESS_BIOMETRIC

System capability: SystemCapability.UserIAM.UserAuth.Core

Parameters

Parameters returned in callback

Example

let authenticator = userIAM_userAuth.getAuthenticator();
authenticator.execute("FACE_ONLY", "S2", (error, code)=>{
    if (code === userIAM_userAuth.ResultCode.SUCCESS) {
        console.info("auth success");
        return;
    }
    console.error("auth fail, code = " + code);
});

execute^(deprecated)

execute(type : AuthType, level : SecureLevel): Promise<number>

Performs user authentication. This API uses a promise to return the result.

NOTE
This API is deprecated since API version 8. You are advised to use auth.

Required permissions: ohos.permission.ACCESS_BIOMETRIC

System capability: SystemCapability.UserIAM.UserAuth.Core

Parameters

Return value

Example

let authenticator = userIAM_userAuth.getAuthenticator();
authenticator.execute("FACE_ONLY", "S2").then((code)=>{
    console.info("auth success");
}).catch((error)=>{
    console.error("auth fail, code = " + error);
});

AuthenticationResult^(deprecated)

Enumerates the authentication results.

NOTE
This object is discarded since API version 8. You are advised to use ResultCode.

System capability: SystemCapability.UserIAM.UserAuth.Core