harmony 鸿蒙Managing System Account Credentials (for System Application Only)

2025-06-06
浏览 (2)

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.
FINGERPRINT¹⁰⁺	4	Fingerprint.

Credential Subtype

Credential types are further classified into the following subtypes:

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

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_CAPACITIVE¹⁰⁺	30000	Capacitive fingerprint.
FINGERPRINT_OPTICAL¹⁰⁺	30001	Optical fingerprint.
FINGERPRINT_ULTRASONIC¹⁰⁺	30002	Ultrasonic fingerprint.

Before You Start

Request the following permissions. For details, see Requesting Permissions for system_basic Applications.
- ohos.permission.MANAGE_USER_IDM
- ohos.permission.ACCESS_PIN_AUTH
Import the osAccount module.

   import { osAccount } from '@kit.BasicServicesKit';

Create a UserIDM instance.

   let userIDM: osAccount.UserIdentityManager = new osAccount.UserIdentityManager();

Registering a PIN Inputer

Procedure

Define a PIN inputer and obtain the PIN.

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

Use registerInputer to register the PIN inputer.

   let pinAuth: osAccount.PINAuth = new 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

Define the PIN authentication credential.

   let credentialInfo: osAccount.CredentialInfo = {
     credType: osAccount.AuthType.PIN,
     credSubType: osAccount.AuthSubType.PIN_SIX,
     token: new Uint8Array([0])
   };

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

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

Authenticating a PIN

Use auth to perform PIN authentication.

Procedure

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: osAccount.AuthType = osAccount.AuthType.PIN;
   let authTrustLevel: osAccount.AuthTrustLevel = osAccount.AuthTrustLevel.ATL1;

Use auth to perform PIN authentication.

   let userAuth: osAccount.UserAuth = new osAccount.UserAuth();
   userAuth.auth(challenge, authType, authTrustLevel, {
     onResult: (result: number, extraInfo: 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

Perform PIN authentication to obtain the authorization token (authToken).
Set face credential information. The following uses 2D face credential as an example.

   let faceCredInfo: osAccount.CredentialInfo = {
     credType: osAccount.AuthType.FACE,
     credSubType: osAccount.AuthSubType.FACE_2D,
     token: new Uint8Array([1, 2, 3, 4, 5])
   }

Use addCredential to enroll face credentials.

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

Set fingerprint credential information.

   let fingerprintCredInfo: osAccount.CredentialInfo = {
     credType: osAccount.AuthType.FINGERPRINT,
     credSubType: osAccount.AuthSubType.FINGERPRINT_CAPACITIVE,
     token: new Uint8Array([1, 2, 3, 4, 5])
   }

Use addCredential to enroll the fingerprint.

   userIDM.addCredential(fingerprintCredInfo, {
     onResult: (code: number, result: 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

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: osAccount.AuthType = osAccount.AuthType.FACE;
   let authTrustLevel: osAccount.AuthTrustLevel = osAccount.AuthTrustLevel.ATL1;

Use auth() to perform authentication.

   let userAuth: osAccount.UserAuth = new osAccount.UserAuth();
   userAuth.auth(challenge, authType, authTrustLevel, {
     onResult: (result: number, extraInfo: 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

Perform PIN authentication to obtain the authorization token (authToken).
Specify the credential information to be updated.

   let credentialInfo: osAccount.CredentialInfo = {
     credType: osAccount.AuthType.PIN,
     credSubType: osAccount.AuthSubType.PIN_SIX,
     token: new Uint8Array([1, 2, 3, 4, 5])
   };

Use updateCredential to update the credential.

   userIDM.updateCredential(credentialInfo, {
     onResult: (result: number, extraInfo: 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

Obtain information about all the credentials enrolled.

   let enrolledCredInfoList: osAccount.EnrolledCredInfo[] = await userIDM.getAuthInfo();

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

   let enrolledFingerCredInfoList: osAccount.EnrolledCredInfo[] = await userIDM.getAuthInfo(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:

Obtain the fingerprint information.

   let credentialId: Uint8Array = new Uint8Array([1, 2, 3, 4, 5]);
   let token: Uint8Array = new Uint8Array([1, 2, 3, 4, 5])
   let credInfoList: osAccount.EnrolledCredInfo[] = await userIDM.getAuthInfo(osAccount.AuthType.FINGERPRINT);
   if (credInfoList.length != 0) {
     credentialId = credInfoList[0].credentialId;
   }

Perform PIN authentication to obtain the authentication token.
Use delCred to delete the fingerprint credential.

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