管理系统帐号的凭据（仅对系统应用开放）

凭据可用于认证用户的身份，本文档将介绍如何录入、认证、更新、查询和删除指定系统帐号的凭据。

凭据类型

系统帐号支持管理以下凭据类型：

名称	值	说明
PIN	1	表示PIN认证类型。
FACE	2	表示人脸认证类型。
FINGERPRINT¹⁰⁺	4	表示指纹认证类型。

凭据子类型

凭据类型进一步细分为以下子类型：

名称	值	说明
PIN_SIX	10000	表示6位凭证。
PIN_NUMBER	10001	表示自定义数字凭证。
PIN_MIXED	10002	表示自定义混合凭据。
FACE_2D	20000	表示2D 人脸凭证。
FACE_3D	20001	表示3D 人脸凭证。
FINGERPRINT_CAPACITIVE¹⁰⁺	30000	表示电容式指纹。
FINGERPRINT_OPTICAL¹⁰⁺	30001	表示光学指纹。
FINGERPRINT_ULTRASONIC¹⁰⁺	30002	表示超声波指纹。

备注：实际设备可支持的凭据类型取决于硬件能力。

开发准备

申请权限，申请流程请参考：申请应用权限。
- ohos.permission.MANAGE_USER_IDM
- ohos.permission.ACCESS_PIN_AUTH

导入系统帐号模块。

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

创建凭据管理对象。

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

注册PIN码输入器

输入器用于传递PIN码数据，录入、认证PIN码前需要先注册输入器。

具体开发实例如下：

定义PIN码输入器，并获取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);
  }
}

调用registerInputer注册PIN码输入器。

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

打开会话

在进行凭据管理前，请先打开一个新的会话。开发者可以使用openSession接口完成此操作。

具体开发实例如下：

调用openSession接口打开凭据管理新会话。

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

录入PIN码

前述操作完成后，可以进行PIN码录入。开发者可以使用addCredential接口完成此操作。

具体开发实例如下：

定义PIN码凭据信息。

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

调用addCredential接口添加指定的凭据信息，执行结果通过回调获取。

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

认证PIN码

录入完PIN码，用户可以进行PIN码认证。开发者可以使用auth接口完成此操作。

具体开发实例如下：

定义认证参数，包括挑战值、认证类型、认证可信等级。

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;

调用auth接口进行认证。

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

录入生物识别凭据

PIN码认证成功后，可以录入人脸/指纹，操作流程与录入PIN码类似。

具体开发实例如下：

认证PIN码，获取授权令牌authToken。

定义人脸凭据信息（以2D人脸为例）。

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

调用addCredential录入人脸凭据。

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

定义指纹凭据信息。

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

调用addCredential录入指纹凭据。

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

认证生物识别凭据

录入完生物识别凭据后，用户可以进行生物识别认证。类似PIN码认证，开发者可以使用auth接口完成此操作。

具体开发实例如下：

定义认证参数（以人脸认证为例），包括挑战值、认证类型、认证可性等级。

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;

调用auth接口进行认证。

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

更新凭据

用户可以修改系统帐号的凭据。开发者可以使用updateCredential接口完成此操作。

具体开发实例如下：

认证PIN码，获取授权令牌authToken。

定义待更新凭据信息。

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

调用updateCredential更新凭据。其中：

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

查询凭据信息

凭据管理界面需要向用户展示已录入的凭据信息；锁屏界面需要展示可认证的凭据类型。开发者可以使用getAuthInfo接口查询已录入的凭据信息，实现前述业务场景功能。

具体开发实例如下：

查询所有已录入的凭据信息。

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

调用getAuthInfo接口，获取指定类型的凭据信息（以指纹凭据为例）。

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

删除凭据

删除凭据前，需要先进行认证PIN码，并获取待删除凭据的标识（参考查询凭据信息）。

以删除指纹凭据为例，具体开发实例如下：

获取指纹类型的凭据信息。

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

认证PIN码，获取授权令牌。

调用delCred接口，删除指定凭据。

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

注销PIN码输入器

不再使用输入器时，可以调用unregisterInputer注销PIN码输入器。

具体开发实例如下：

pinAuth.unregisterInputer();

关闭会话

调用closeSession关闭会话，结束凭据管理。

具体开发实例如下：

userIDM.closeSession();