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:

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_CAPACITIVE10+	30000	Capacitive fingerprint.
FINGERPRINT_OPTICAL10+	30001	Optical fingerprint.
FINGERPRINT_ULTRASONIC10+	30002	Ultrasonic fingerprint.

Getting Started

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 { osAccount } from '@kit.BasicServicesKit';

3. Create a UserIDM instance.

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

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]);
	// ···
      let inputer: osAccount.IInputer = {
        onGetData: (authSubType: osAccount.AuthSubType, callback: osAccount.IInputData) => {
          callback.onSetData(authSubType, pinData);
        }
      }

2. 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 session: Uint8Array = await userIDM.openSession();

Enrolling a PIN

Use addCredential to enroll a PIN.

Procedure

1. Define the PIN authentication credential.

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

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

        userIDM.addCredential(credentialInfo,{
          onResult: (err, extraInfo)=>{
            console.info('addCredential result: ' + JSON.stringify(err));
            console.info('edential info: ' + JSON.stringify(extraInfo));
			// ···
          }})

Authenticating a PIN

Use auth to perform PIN authentication.

Procedure

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

   Define the challenge value:

   let challenge: Uint8Array = new Uint8Array([1, 2, 3, 4, 5]);
   

   Define the authentication type and authentication trust level:

        let authType: osAccount.AuthType = osAccount.AuthType.PIN;
        let authTrustLevel: osAccount.AuthTrustLevel = osAccount.AuthTrustLevel.ATL1;

2. 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.info('pin auth result = ' + result);
            console.info('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: osAccount.CredentialInfo = {
      credType: osAccount.AuthType.FACE,
      credSubType: osAccount.AuthSubType.FACE_2D,
      token: new Uint8Array([1, 2, 3, 4, 5])
    }

3. Use addCredential to enroll face credentials.

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

4. 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])
    }

5. Use addCredential to enroll the fingerprint.

            userIDM.addCredential(fingerprintCredInfo, {
              onResult: (code: number, result: osAccount.RequestResult) => {
                console.info('add fingerprint credential, resultCode: ' + code);
                console.info('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.

   Define the challenge value:

   let challenge: Uint8Array = new Uint8Array([1, 2, 3, 4, 5]);
   

   Define the authentication type and authentication trust level:

        let authType: osAccount.AuthType = osAccount.AuthType.FACE;
        let authTrustLevel: osAccount.AuthTrustLevel = osAccount.AuthTrustLevel.ATL1;

2. Use auth() to perform authentication.

        let userAuth: osAccount.UserAuth = new osAccount.UserAuth();
        userAuth.auth(challenge, authType, authTrustLevel, {
          onResult: (result: number, extraInfo: osAccount.AuthResult) => {
            console.info('face auth result = ' + result);
            console.info('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 :osAccount.CredentialInfo = {
	// ···
      credType:osAccount.AuthType.PIN,
      credSubType:osAccount.AuthSubType.PIN_SIX,
      token:new Uint8Array([1, 2, 3, 4, 5])
    };

3. Use updateCredential to update the credential.

          userIDM.updateCredential(credentialInfo, {
            onResult:(result: number, extraInfo: osAccount.RequestResult)=>{
              console.info('updateCredential result: ' + JSON.stringify(result));
              console.info('updateCredential extraInfo: ' + JSON.stringify(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: 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: osAccount.EnrolledCredInfo[] =
        await userIDM.getAuthInfo(osAccount.AuthType.PIN);

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

2. Perform PIN authentication to obtain the authentication token.

3. Use delCred to delete the fingerprint credential.

            userIDM.delCred(credentialId, authResult.token, {
              onResult: (result: number, extraInfo: osAccount.RequestResult) => {
                console.info('delCred result = ' + result);
                console.info('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(this.cid);

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 manage-distributed-account-sys

openharmony 鸿蒙 account-overview-sys

openharmony 鸿蒙 manage-domain-account-sys

openharmony 鸿蒙 auth-domain-account-sys

openharmony 鸿蒙 Readme-EN

openharmony 鸿蒙 manage-os-account-sys

openharmony 鸿蒙 manage-application-account

openharmony 鸿蒙 manage-domain-plugin-sys

openharmony 鸿蒙 control-os-account-by-constraints-sys