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

Example

// API version 6
import userIAM_userAuth from '@ohos.userIAM.userAuth';

export default {
    startAuth() {
        console.info("start auth");
        let auth = userIAM_userAuth.getAuthenticator();
        auth.execute("FACE_ONLY", "S2").then((code)=>{
            console.info("auth success");
            // Add the logic to be executed when the authentication is successful.
        }).catch((code)=>{
            console.error("auth fail, code = " + code);
            // Add the logic to be executed when the authentication fails.
        });
    }
}

// API version 8
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let auth = new userIAM_userAuth.UserAuth();

export default {
    getVersion() {
        console.info("start get version");
        let version = this.auth.getVersion();
        console.info("auth version = " + version);
    },

    startAuth() {
        console.info("start auth");
        this.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 == '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: (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);
                }
            }
        });
    },

    checkAuthSupport() {
        console.info("start check auth support");
        let checkCode = this.auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1);
        if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) {
            console.info("check auth support success");
            // Add the logic to be executed if the specified authentication type is supported.
        } else {
            console.error("check auth support fail, code = " + checkCode);
            // Add the logic to be executed if the specified authentication type is not supported.
        }
    },

    cancelAuth() {
        console.info("start cancel auth");
        // Obtain contextId using auth().
        let contextId = auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, {
            onResult: (result, extraInfo) => {
                console.info("auth onResult result = " + result);
            },

            onAcquireInfo: (module, acquire, extraInfo) => {
                console.info("auth onAcquireInfo module = " + module);
            }
        });
        let cancelCode = this.auth.cancel(contextId);
        if (cancelCode == userIAM_userAuth.Result.SUCCESS) {
            console.info("cancel auth success");
        } else {
            console.error("cancel auth fail");
        }
    }
}

userIAM_userAuth.getAuthenticator^(deprecated)

getAuthenticator(): Authenticator

NOTE
This API is not longer maintained since API version 8. You are advised to use constructor.

Obtains an Authenticator object for user authentication.

Required permissions: ohos.permission.ACCESS_BIOMETRIC

System capability: SystemCapability.UserIAM.UserAuth.Core

Return value

Example

let authenticator = userIAM_userAuth.getAuthenticator();

Authenticator^(deprecated)

NOTE
This object is not longer maintained since API version 8. You are advised to use UserAuth.

Provides methods to manage an Authenticator object.

execute^(deprecated)

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

NOTE
This API is not longer maintained since API version 8. You are advised to use auth.

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

Required permissions: ohos.permission.ACCESS_BIOMETRIC

System capability: SystemCapability.UserIAM.UserAuth.Core

Parameters

Parameters returned in callback

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^(deprecated)

execute(type:string, level:string): Promise<number>

NOTE
This API is not longer maintained since API version 8. You are advised to use auth.

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

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((code)=>{
    console.error("auth fail, code = " + code);
});

AuthenticationResult^(deprecated)

NOTE
This parameter is not longer maintained since API version 8. You are advised to use ResultCode.

Enumerates the authentication results.

System capability: SystemCapability.UserIAM.UserAuth.Core

UserAuth⁸⁺

Provides methods to manage an Authenticator object.

constructor⁸⁺

constructor()

A constructor used to create an authenticator object.

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();

getVersion⁸⁺

getVersion() : number

Obtains the authentication executor version.

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⁸⁺

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

Checks whether the authentication capability of the specified trust level is available.

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");
    // Add the logic to be executed if the specified authentication type is supported.
} else {
    console.error("check auth support fail, code = " + checkCode);
    // Add the logic to be executed if the specified authentication type is not supported.
}

auth⁸⁺

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

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

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⁸⁺

cancelAuth(contextID : Uint8Array) : number

Cancels an authentication.

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 using auth(). In this example, it is defined here.
let contextId = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]);
let cancelCode = auth.cancel(contextId);
if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) {
    console.info("cancel auth success");
} else {
    console.error("cancel auth fail");
}

IUserAuthCallback⁸⁺

Defines the object of the result returned by the callback during authentication.

onResult⁸⁺

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

Obtains the authentication result.

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 == 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: (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);
        }
    }
});

onAcquireInfo⁸⁺

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

Obtains the tip code information during authentication. This function is optional.

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 == 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: (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⁸⁺

Represents the authentication result object.

System capability: SystemCapability.UserIAM.UserAuth.Core

ResultCode⁸⁺

Enumerates the operation results.

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