• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 管理系统帐号的凭据（仅对系统应用开放）
2
3凭据可用于认证用户的身份，本文档将介绍如何录入、认证、更新、查询和删除指定系统帐号的凭据。
4
5## 凭据类型
6
7系统帐号支持管理以下凭据类型：
8
9| 名称  | 值 | 说明             |
10| ----- | ----- | ---------------- |
11| PIN   | 1     | 表示PIN认证类型。 |
12| FACE  | 2     | 表示人脸认证类型。|
13| FINGERPRINT<sup>10+</sup>   | 4     | 表示指纹认证类型。 |
14
15## 凭据子类型
16
17凭据类型进一步细分为以下子类型：
18
19| 名称       | 值 | 说明               |
20| ---------- | ----- | ------------------ |
21| PIN_SIX    | 10000 | 表示6位凭证。       |
22| PIN_NUMBER | 10001 | 表示自定义数字凭证。 |
23| PIN_MIXED  | 10002 | 表示自定义混合凭据。 |
24| FACE_2D    | 20000 | 表示2D 人脸凭证。   |
25| FACE_3D    | 20001 | 表示3D 人脸凭证。   |
26| FINGERPRINT_CAPACITIVE<sup>10+</sup>    | 30000 | 表示电容式指纹。   |
27| FINGERPRINT_OPTICAL<sup>10+</sup>    | 30001 | 表示光学指纹。   |
28| FINGERPRINT_ULTRASONIC<sup>10+</sup>    | 30002 | 表示超声波指纹。   |
29
30备注：实际设备可支持的凭据类型取决于硬件能力。
31
32## 开发准备
33
341. 申请权限，申请流程请参考：[申请应用权限](../../security/AccessToken/determine-application-mode.md#system_basic等级的应用申请权限)。
35   - ohos.permission.MANAGE_USER_IDM
36   - ohos.permission.ACCESS_PIN_AUTH
37
382. 导入系统帐号模块。
39
40   ```ts
41   import account_osAccount from '@ohos.account.osAccount';
42   ```
43
443. 创建凭据管理对象。
45
46   ```ts
47   let userIDM: account_osAccount.UserIDM = new account_osAccount.UserIDM();
48   ```
49
50## 注册PIN码输入器
51
52输入器用于传递PIN码数据，录入、认证PIN码前需要先注册输入器。
53
54具体开发实例如下：
55
561. 定义PIN码输入器，并获取PIN码。
57
58   ```ts
59   let pinData: Uint8Array = new Uint8Array([31, 32, 33, 34, 35, 36]); // you can obtain a PIN throught other ways.
60   let inputer: IInputer = {
61     onGetData: (authSubType: account_osAccount.AuthSubType, callback: account_osAccount.IInputData) => {
62       callback.onSetData(authSubType, pinData);
63     }
64   }
65   ```
66
672. 调用[registerInputer](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#registerinputer8)注册PIN码输入器。
68
69   ```ts
70   let pinAuth: PINAuth = new account_osAccount.PINAuth();
71   pinAuth.registerInputer(inputer);
72   ```
73
74## 打开会话
75
76在进行凭据管理前，请先打开一个新的会话。开发者可以使用[openSession](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#opensession8)接口完成此操作。
77
78具体开发实例如下：
79
801. 调用[openSession](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#opensession8)接口打开凭据管理新会话。
81
82   ```ts
83   let challenge: Uint8Array = await userIDM.openSession();
84   ```
85
86## 录入PIN码
87
88前述操作完成后，可以进行PIN码录入。开发者可以使用[addCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8)接口完成此操作。
89
90具体开发实例如下：
91
921. 定义PIN码凭据信息。
93
94   ```ts
95   let credentialInfo: account_osAccount.CredentialInfo = {
96     credType: account_osAccount.AuthSubType.PIN,
97     token: null
98   };
99   ```
100
1012. 调用[addCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8)接口添加指定的凭据信息，执行结果通过回调获取。
102
103   ```ts
104   userIDM.addCredential(credentialInfo, {
105     onResult: (code: number, result: account_osAccount.RequestResult) => {
106       console.log('addCredential code = ' + code);
107       console.log('addCredential result = ' + result);
108     }
109   });
110   ```
111
112## 认证PIN码
113
114录入完PIN码，用户可以进行PIN码认证。开发者可以使用[auth](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#auth8)接口完成此操作。
115
116具体开发实例如下：
117
1181. 定义认证参数，包括挑战值、认证类型、认证可信等级。
119
120   ```ts
121   let challenge: Uint8Array = new Uint8Array([1, 2, 3, 4, 5]);
122   let authType: account_osAccount.AuthType = account_osAccount.AuthType.PIN;
123   let authTrustLevel: account_osAccount.AuthTrustLevel = account_osAccount.AuthTrustLevel.ATL1;
124   ```
125
1262. 调用[auth](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#auth8)接口进行认证。
127
128   ```ts
129   let userAuth: account_osAccount.UserAuth = new account_osAccount.UserAuth();
130   userAuth.auth(challenge, authType, authTrustLevel, {
131     onResult: (result: number, extraInfo: account_osAccount.AuthResult) => {
132       console.log('pin auth result = ' + result);
133       console.log('pin auth extraInfo = ' + JSON.stringify(extraInfo));
134       let authToken = extraInfo.token;
135     }
136   });
137   ```
138
139## 录入生物识别凭据
140
141PIN码认证成功后，可以录入人脸/指纹，操作流程与录入PIN码类似。
142
143具体开发实例如下：
144
1451. 认证PIN码，获取授权令牌authToken。
146
1472. 定义人脸凭据信息（以2D人脸为例）。
148
149   ```ts
150   let faceCredInfo: account_osAccount.CredentialInfo = {
151     credType: account_osAccount.AuthType.FACE,
152     credSubType: account_osAccount.AuthSubType.FACE_2D,
153     token: authToken
154   }
155   ```
156
1573. 调用[addCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8)录入人脸凭据。
158
159   ```ts
160   userIDM.addCredential(faceCredInfo, {
161     onResult: (code: number, result: account_osAccount.RequestResult) => {
162       console.log('add face credential, resultCode: ' + code);
163       console.log('add face credential, request result: ' + result);
164     }
165   });
166   ```
167
1684. 定义指纹凭据信息。
169
170   ```ts
171   let fingerprintCredInfo: account_osAccount.CredentialInfo = {
172     credType: account_osAccount.AuthType.FINGERPRINT,
173     credSubType: account_osAccount.AuthSubType.FINGERPRINT_CAPACITIVE,
174     token: authToken
175   }
176   ```
177
1785. 调用[addCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8)录入指纹凭据。
179
180   ```ts
181   userIDM.addCredential(fingerprintCredInfo, {
182     onResult: (code: number, result: account_osAccount.RequestResult) => {
183       console.log('add fingerprint credential, resultCode: ' + code);
184       console.log('add fingerprint credential, request result: ' + result);
185     }
186   });
187   ```
188
189## 认证生物识别凭据
190
191录入完生物识别凭据后，用户可以进行生物识别认证。类似PIN码认证，开发者可以使用[auth](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#auth8)接口完成此操作。
192
193具体开发实例如下：
194
1951. 定义认证参数（以人脸认证为例），包括挑战值、认证类型、认证可性等级。
196
197   ```ts
198   let challenge: Uint8Array = new Uint8Array([1, 2, 3, 4, 5]);
199   let authType: account_osAccount.AuthType = account_osAccount.AuthType.FACE;
200   let authTrustLevel: account_osAccount.AuthTrustLevel = account_osAccount.AuthTrustLevel.ATL1;
201   ```
202
2032. 调用auth接口进行认证。
204
205   ```ts
206   let userAuth: account_osAccount.UserAuth = new account_osAccount.UserAuth();
207   userAuth.auth(challenge, authType, authTrustLevel, {
208     onResult: (result: number, extraInfo: account_osAccount.AuthResult) => {
209       console.log('face auth result = ' + result);
210       console.log('face auth extraInfo = ' + JSON.stringify(extraInfo));
211     }
212   });
213   ```
214
215## 更新凭据
216
217用户可以修改系统帐号的凭据。开发者可以使用[updateCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#updatecredential8)接口完成此操作。
218
219具体开发实例如下：
220
2211. 认证PIN码，获取授权令牌authToken。
222
2232. 定义待更新凭据信息。
224
225   ```ts
226   let credentialInfo: account_osAccount.CredentialInfo = {
227     credType: account_osAccount.AuthType.PIN,
228     credSubType: account_osAccount.AuthSubType.PIN_SIX,
229     token: authToken,
230   };
231   ```
232
2333. 调用[updateCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#updatecredential8)更新凭据。其中：
234
235   ```ts
236   userIDM.updateCredential(credentialInfo, {
237     onResult: (result: number, extraInfo: account_osAccount.RequestResult) => {
238       console.log('updateCredential result = ' + result);
239       console.log('updateCredential extraInfo = ' + extraInfo);
240     }
241   });
242   ```
243
244## 查询凭据信息
245
246凭据管理界面需要向用户展示已录入的凭据信息；锁屏界面需要展示可认证的凭据类型。开发者可以使用[getAuthInfo](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#getauthinfo8)接口查询已录入的凭据信息，实现前述业务场景功能。
247
248具体开发实例如下：
249
2501. 查询所有已录入的凭据信息。
251
252   ```ts
253   let enrolledCredInfoList: account_osAccount.EnrolledCredInfo = await userIDM.getAuthInfo();
254   ```
255
2562. 调用[getAuthInfo](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#getauthinfo8)接口，获取指定类型的凭据信息（以指纹凭据为例）。
257
258   ```ts
259   let enrolledFingerCredInfoList: account_osAccount.EnrolledCredInfo = await userIDM.getAuthInfo(account_osAccount.AuthType.Fingerprint);
260   ```
261
262## 删除凭据
263
264删除凭据前，需要先进行[认证PIN码](#认证pin码)，并获取待删除凭据的标识（参考[查询凭据信息](#查询凭据信息)）。
265
266以删除指纹凭据为例，具体开发实例如下：
267
2681. 获取指纹类型的凭据信息。
269
270   ```ts
271   let credInfoList: account_osAccount.EnrolledCredInfo = await userIDM.getAuthInfo(account_osAccount.AuthType.Fingerprint);
272   let credentialId: number = 0;
273   if (credInfoList.length != 0) {
274     credentialId = credInfoList[0].credentialId;
275   }
276   ```
277
2782. [认证PIN码](#认证pin码)，获取授权令牌。
279
2803. 调用[delCred](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#delcred8)接口，删除指定凭据。
281
282   ```ts
283   userIDM.delCred(credentialId, token, {
284     onResult: (result: number, extraInfo: account_osAccount.RequestResult) => {
285       console.log('delCred result = ' + result);
286       console.log('delCred extraInfo = ' + JSON.stringify(extraInfo));
287     }
288   });
289   ```
290
291## 注销PIN码输入器
292
293不再使用输入器时，可以调用[unregisterInputer](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#unregisterinputer8)注销PIN码输入器。
294
295具体开发实例如下：
296
297```ts
298pinAuth.unregisterInputer();
299```
300
301## 关闭会话
302
303调用[closeSession](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#closesession8)关闭会话，结束凭据管理。
304
305具体开发实例如下：
306
307```ts
308userIDM.closeSession();
309```
310