Managing System Account Credentials (for System Application Only)

Credentials can be used to authenticate users. This topic walks you through on how to add, update, obtain, and delete credentials for a system account and authenticate the system account using the enrolled credentials.

Credential Type

The following types of credentials are supported for system accounts:

Name Value Description
PIN 1 PIN.
FACE 2 Face.
FINGERPRINT10+ 4 Fingerprint.

Credential Subtype

Credential types are further classified into the following subtypes:

Name Value Description
PIN_SIX 10000 Six-digit PIN.
PIN_NUMBER 10001 Custom PIN.
PIN_MIXED 10002 Custom mixed PIN.
FACE_2D 20000 2D face credential.
FACE_3D 20001 3D face credential.
FINGERPRINT_CAPACITIVE10+ 30000 Capacitive fingerprint.
FINGERPRINT_OPTICAL10+ 30001 Optical fingerprint.
FINGERPRINT_ULTRASONIC10+ 30002 Ultrasonic fingerprint.

NOTE
The credential types supported by the device depend on the hardware capability.

Before You Start

  1. Request the following permissions. For details, see Requesting Permissions for system_basic Applications.

    • ohos.permission.MANAGE_USER_IDM
    • ohos.permission.ACCESS_PIN_AUTH

  2. Import the osAccount module.

    import account_osAccount from '@ohos.account.osAccount';

  3. Create a UserIDM instance.

    let userIDM: account_osAccount.UserIDM = new account_osAccount.UserIDM();

Registering a PIN Inputer

Register a PIN inputer to transmit PIN data.

Procedure

  1. Define a PIN inputer and obtain the PIN.

    let pinData: Uint8Array = new Uint8Array([31, 32, 33, 34, 35, 36]); // you can obtain a PIN throught other ways.
let inputer: IInputer = {
  onGetData: (authSubType: account_osAccount.AuthSubType, callback: account_osAccount.IInputData) => {
    callback.onSetData(authSubType, pinData);
  }
}

  2. Use registerInputer to register the PIN inputer.

    let pinAuth: PINAuth = new account_osAccount.PINAuth();
pinAuth.registerInputer(inputer);

Opening a Session

Use openSession to open a session for credential management.

Procedure

Use openSession to open a session for credential management.

let challenge: Uint8Array = await userIDM.openSession();

Enrolling a PIN

Use addCredential to enroll a PIN.

Procedure

  1. Defines the PIN authentication credential.

    let credentialInfo: account_osAccount.CredentialInfo = {
  credType: account_osAccount.AuthSubType.PIN,
  token: null
};

  2. Use addCredential to add credential information. The credential is returned by a callback or promise.

    userIDM.addCredential(credentialInfo, {
  onResult: (code: number, result: account_osAccount.RequestResult) => {
    console.log('addCredential code = ' + code);
    console.log('addCredential result = ' + result);
  }
});

Authenticating a PIN

Use auth to perform PIN authentication.

Procedure

  1. Set authentication parameters, including the challenge value, authentication type, and authentication trust level.

    let challenge: Uint8Array = new Uint8Array([1, 2, 3, 4, 5]);
let authType: account_osAccount.AuthType = account_osAccount.AuthType.PIN;
let authTrustLevel: account_osAccount.AuthTrustLevel = account_osAccount.AuthTrustLevel.ATL1;

  2. Use auth to perform PIN authentication.

    let userAuth: account_osAccount.UserAuth = new account_osAccount.UserAuth();
userAuth.auth(challenge, authType, authTrustLevel, {
  onResult: (result: number, extraInfo: account_osAccount.AuthResult) => {
    console.log('pin auth result = ' + result);
    console.log('pin auth extraInfo = ' + JSON.stringify(extraInfo));
    let authToken = extraInfo.token;
  }
});

Enrolling Biometric Credentials

Biometric credentials such as face and fingerprint can be enrolled after the PIN authentication is successful. The enrollment process is similar to the PIN enrollment process.

Procedure

  1. Perform PIN authentication to obtain the authorization token (authToken).

  2. Set face credential information. The following uses 2D face credential as an example.

    let faceCredInfo: account_osAccount.CredentialInfo = {
  credType: account_osAccount.AuthType.FACE,
  credSubType: account_osAccount.AuthSubType.FACE_2D,
  token: authToken
}

  3. Use addCredential to enroll face credentials.

    userIDM.addCredential(faceCredInfo, {
  onResult: (code: number, result: account_osAccount.RequestResult) => {
    console.log('add face credential, resultCode: ' + code);
    console.log('add face credential, request result: ' + result);
  }
});

  4. Set fingerprint credential information.

    let fingerprintCredInfo: account_osAccount.CredentialInfo = {
  credType: account_osAccount.AuthType.FINGERPRINT,
  credSubType: account_osAccount.AuthSubType.FINGERPRINT_CAPACITIVE,
  token: authToken
}

  5. Use addCredential to enroll the fingerprint.

    userIDM.addCredential(fingerprintCredInfo, {
  onResult: (code: number, result: account_osAccount.RequestResult) => {
    console.log('add fingerprint credential, resultCode: ' + code);
    console.log('add fingerprint credential, request result: ' + result);
  }
});

Authenticating Biometric Credentials

Biometric authentication can be performed after the biometric credentials are enrolled. You can use auth to perform biometric authentication.

Procedure

  1. Set authentication parameters, including the challenge value, authentication type, and authentication trust level. The following uses facial authentication as an example.

    let challenge: Uint8Array = new Uint8Array([1, 2, 3, 4, 5]);
let authType: account_osAccount.AuthType = account_osAccount.AuthType.FACE;
let authTrustLevel: account_osAccount.AuthTrustLevel = account_osAccount.AuthTrustLevel.ATL1;

  2. Use auth() to perform authentication.

    let userAuth: account_osAccount.UserAuth = new account_osAccount.UserAuth();
userAuth.auth(challenge, authType, authTrustLevel, {
  onResult: (result: number, extraInfo: account_osAccount.AuthResult) => {
    console.log('face auth result = ' + result);
    console.log('face auth extraInfo = ' + JSON.stringify(extraInfo));
  }
});

Updating a Credential

The user can update credentials as required. You can use updateCredential to update credential information.

Procedure

  1. Perform PIN authentication to obtain the authorization token (authToken).

  2. Specify the credential information to be updated.

    let credentialInfo: account_osAccount.CredentialInfo = {
  credType: account_osAccount.AuthType.PIN,
  credSubType: account_osAccount.AuthSubType.PIN_SIX,
  token: authToken,
};

  3. Use updateCredential to update the credential.

    userIDM.updateCredential(credentialInfo, {
  onResult: (result: number, extraInfo: account_osAccount.RequestResult) => {
    console.log('updateCredential result = ' + result);
    console.log('updateCredential extraInfo = ' + extraInfo);
  }
});

Obtaining Credential Information

The enrolled credentials need to be displayed on the credential management page, and the available credential types need to be displayed on the lock screen page. You can use getAuthInfo to obtain the credential information to be displayed.

Procedure

  1. Obtain information about all the credentials enrolled.

    let enrolledCredInfoList: account_osAccount.EnrolledCredInfo = await userIDM.getAuthInfo();

  2. Use getAuthInfo to obtain the credential of the specified type. In the following example, the fingerprint enrolled is obtained.

    let enrolledFingerCredInfoList: account_osAccount.EnrolledCredInfo = await userIDM.getAuthInfo(account_osAccount.AuthType.Fingerprint);

Deleting a Credential

Before a credential is deleted, PIN Authentication is required and the ID of the credential to be deleted needs to be obtained.

For example, delete a fingerprint, do as follows:

  1. Obtain the fingerprint information.

    let credInfoList: account_osAccount.EnrolledCredInfo = await userIDM.getAuthInfo(account_osAccount.AuthType.Fingerprint);
let credentialId: number = 0;
if (credInfoList.length != 0) {
  credentialId = credInfoList[0].credentialId;
}

  2. Perform PIN authentication to obtain the authentication token.

  3. Use delCred to delete the fingerprint credential.

    userIDM.delCred(credentialId, token, {
  onResult: (result: number, extraInfo: account_osAccount.RequestResult) => {
    console.log('delCred result = ' + result);
    console.log('delCred extraInfo = ' + JSON.stringify(extraInfo));
  }
});

Unregistering a PIN Inputer

Use unregisterInputer to unregister the PIN inputer that is no longer required.

Procedure

pinAuth.unregisterInputer();

Closing a Session

Use closeSession to close a session to terminate credential management.

Procedure

userIDM.closeSession();