1# Managing System Account Credentials (for System Application Only)
2
3Credentials 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.
4
5## Credential Type
6
7The following types of credentials are supported for system accounts:
8
9| Name | Value| Description            |
10| ----- | ----- | ---------------- |
11| PIN   | 1     | PIN.|
12| FACE  | 2     | Face.|
13| FINGERPRINT<sup>10+</sup>   | 4     | Fingerprint.|
14
15## Credential Subtype
16
17Credential types are further classified into the following subtypes:
18
19> **NOTE**<br>
20> The credential types supported by the device depend on the hardware capability.
21
22| Name      | Value| Description              |
23| ---------- | ----- | ------------------ |
24| PIN_SIX    | 10000 | Six-digit PIN.      |
25| PIN_NUMBER | 10001 | Custom PIN.|
26| PIN_MIXED  | 10002 | Custom mixed PIN.|
27| FACE_2D    | 20000 | 2D face credential.  |
28| FACE_3D    | 20001 | 3D face credential.  |
29| FINGERPRINT_CAPACITIVE<sup>10+</sup>    | 30000 | Capacitive fingerprint.  |
30| FINGERPRINT_OPTICAL<sup>10+</sup>    | 30001 | Optical fingerprint.  |
31| FINGERPRINT_ULTRASONIC<sup>10+</sup>    | 30002 | Ultrasonic fingerprint.  |
32
33## Before You Start
34
351. Request the following permissions. For details, see [Requesting Permissions for system_basic Applications](../../security/AccessToken/determine-application-mode.md#requesting-permissions-for-system_basic-applications).
36   - ohos.permission.MANAGE_USER_IDM
37   - ohos.permission.ACCESS_PIN_AUTH
38
392. Import the **osAccount** module.
40
41   ```ts
42   import { osAccount } from '@kit.BasicServicesKit';
43   ```
44
453. Create a **UserIDM** instance.
46
47   ```ts
48   let userIDM: osAccount.UserIdentityManager = new osAccount.UserIdentityManager();
49   ```
50
51## Registering a PIN Inputer
52
53Register a PIN inputer to transmit PIN data.
54
55**Procedure**
56
571. Define a PIN inputer and obtain the PIN.
58
59   ```ts
60   let pinData: Uint8Array = new Uint8Array([31, 32, 33, 34, 35, 36]); // you can obtain a PIN through other ways.
61   let inputer: osAccount.IInputer = {
62     onGetData: (authSubType: osAccount.AuthSubType, callback: osAccount.IInputData) => {
63       callback.onSetData(authSubType, pinData);
64     }
65   }
66   ```
67
682. Use [registerInputer](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#registerinputer8) to register the PIN inputer.
69
70   ```ts
71   let pinAuth: osAccount.PINAuth = new osAccount.PINAuth();
72   pinAuth.registerInputer(inputer);
73   ```
74
75## Opening a Session
76
77Use [openSession](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#opensession8) to open a session for credential management.
78
79**Procedure**
80
81Use [openSession](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#opensession8) to open a session for credential management.
82
83   ```ts
84   let challenge: Uint8Array = await userIDM.openSession();
85   ```
86
87## Enrolling a PIN
88
89Use [addCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8) to enroll a PIN.
90
91**Procedure**
92
931. Define the PIN authentication credential.
94
95   ```ts
96   let credentialInfo: osAccount.CredentialInfo = {
97     credType: osAccount.AuthType.PIN,
98     credSubType: osAccount.AuthSubType.PIN_SIX,
99     token: new Uint8Array([0])
100   };
101   ```
102
1032. Use [addCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8) to add credential information. The credential is returned by a callback or promise.
104
105   ```ts
106   userIDM.addCredential(credentialInfo, {
107     onResult: (code: number, result: osAccount.RequestResult) => {
108       console.log('addCredential code = ' + code);
109       console.log('addCredential result = ' + result);
110     }
111   });
112   ```
113
114## Authenticating a PIN
115
116Use [auth](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#auth8) to perform PIN authentication.
117
118**Procedure**
119
1201. Set authentication parameters, including the challenge value, authentication type, and authentication trust level.
121
122   ```ts
123   let challenge: Uint8Array = new Uint8Array([1, 2, 3, 4, 5]);
124   let authType: osAccount.AuthType = osAccount.AuthType.PIN;
125   let authTrustLevel: osAccount.AuthTrustLevel = osAccount.AuthTrustLevel.ATL1;
126   ```
127
1282. Use [auth](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#auth8) to perform PIN authentication.
129
130   ```ts
131   let userAuth: osAccount.UserAuth = new osAccount.UserAuth();
132   userAuth.auth(challenge, authType, authTrustLevel, {
133     onResult: (result: number, extraInfo: osAccount.AuthResult) => {
134       console.log('pin auth result = ' + result);
135       console.log('pin auth extraInfo = ' + JSON.stringify(extraInfo));
136       let authToken = extraInfo.token;
137     }
138   });
139   ```
140
141## Enrolling Biometric Credentials
142
143Biometric 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.
144
145**Procedure**
146
1471. Perform PIN authentication to obtain the authorization token (**authToken**).
148
1492. Set face credential information. The following uses 2D face credential as an example.
150
151   ```ts
152   let faceCredInfo: osAccount.CredentialInfo = {
153     credType: osAccount.AuthType.FACE,
154     credSubType: osAccount.AuthSubType.FACE_2D,
155     token: new Uint8Array([1, 2, 3, 4, 5])
156   }
157   ```
158
1593. Use [addCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8) to enroll face credentials.
160
161   ```ts
162   userIDM.addCredential(faceCredInfo, {
163     onResult: (code: number, result: osAccount.RequestResult) => {
164       console.log('add face credential, resultCode: ' + code);
165       console.log('add face credential, request result: ' + result);
166     }
167   });
168   ```
169
1704. Set fingerprint credential information.
171
172   ```ts
173   let fingerprintCredInfo: osAccount.CredentialInfo = {
174     credType: osAccount.AuthType.FINGERPRINT,
175     credSubType: osAccount.AuthSubType.FINGERPRINT_CAPACITIVE,
176     token: new Uint8Array([1, 2, 3, 4, 5])
177   }
178   ```
179
1805. Use [addCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8) to enroll the fingerprint.
181
182   ```ts
183   userIDM.addCredential(fingerprintCredInfo, {
184     onResult: (code: number, result: osAccount.RequestResult) => {
185       console.log('add fingerprint credential, resultCode: ' + code);
186       console.log('add fingerprint credential, request result: ' + result);
187     }
188   });
189   ```
190
191## Authenticating Biometric Credentials
192
193Biometric authentication can be performed after the biometric credentials are enrolled. You can use [auth](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#auth8) to perform biometric authentication.
194
195**Procedure**
196
1971. Set authentication parameters, including the challenge value, authentication type, and authentication trust level. The following uses facial authentication as an example.
198
199   ```ts
200   let challenge: Uint8Array = new Uint8Array([1, 2, 3, 4, 5]);
201   let authType: osAccount.AuthType = osAccount.AuthType.FACE;
202   let authTrustLevel: osAccount.AuthTrustLevel = osAccount.AuthTrustLevel.ATL1;
203   ```
204
2052. Use **auth()** to perform authentication.
206
207   ```ts
208   let userAuth: osAccount.UserAuth = new osAccount.UserAuth();
209   userAuth.auth(challenge, authType, authTrustLevel, {
210     onResult: (result: number, extraInfo: osAccount.AuthResult) => {
211       console.log('face auth result = ' + result);
212       console.log('face auth extraInfo = ' + JSON.stringify(extraInfo));
213     }
214   });
215   ```
216
217## Updating a Credential
218
219The user can update credentials as required. You can use [updateCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#updatecredential8) to update credential information.
220
221**Procedure**
222
2231. Perform PIN authentication to obtain the authorization token (**authToken**).
224
2252. Specify the credential information to be updated.
226
227   ```ts
228   let credentialInfo: osAccount.CredentialInfo = {
229     credType: osAccount.AuthType.PIN,
230     credSubType: osAccount.AuthSubType.PIN_SIX,
231     token: new Uint8Array([1, 2, 3, 4, 5])
232   };
233   ```
234
2353. Use [updateCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#updatecredential8) to update the credential.
236
237   ```ts
238   userIDM.updateCredential(credentialInfo, {
239     onResult: (result: number, extraInfo: osAccount.RequestResult) => {
240       console.log('updateCredential result = ' + result);
241       console.log('updateCredential extraInfo = ' + extraInfo);
242     }
243   });
244   ```
245
246## Obtaining Credential Information
247
248The 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](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#getauthinfo8) to obtain the credential information to be displayed.
249
250**Procedure**
251
2521. Obtain information about all the credentials enrolled.
253
254   ```ts
255   let enrolledCredInfoList: osAccount.EnrolledCredInfo[] = await userIDM.getAuthInfo();
256   ```
257
2582. Use [getAuthInfo](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#getauthinfo8) to obtain the credential of the specified type. In the following example, the fingerprint enrolled is obtained.
259
260   ```ts
261   let enrolledFingerCredInfoList: osAccount.EnrolledCredInfo[] = await userIDM.getAuthInfo(osAccount.AuthType.FINGERPRINT);
262   ```
263
264## Deleting a Credential
265
266Before a credential is deleted, [PIN Authentication](#authenticating-a-pin) is required and the ID of the credential to be deleted needs to be [obtained](#obtaining-credential-information).
267
268For example, delete a fingerprint, do as follows:
269
2701. Obtain the fingerprint information.
271
272   ```ts
273   let credentialId: Uint8Array = new Uint8Array([1, 2, 3, 4, 5]);
274   let token: Uint8Array = new Uint8Array([1, 2, 3, 4, 5])
275   let credInfoList: osAccount.EnrolledCredInfo[] = await userIDM.getAuthInfo(osAccount.AuthType.FINGERPRINT);
276   if (credInfoList.length != 0) {
277     credentialId = credInfoList[0].credentialId;
278   }
279   ```
280
2812. [Perform PIN authentication](#authenticating-a-pin) to obtain the authentication token.
282
2833. Use [delCred](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#delcred8) to delete the fingerprint credential.
284
285   ```ts
286   userIDM.delCred(credentialId, token, {
287     onResult: (result: number, extraInfo: osAccount.RequestResult) => {
288       console.log('delCred result = ' + result);
289       console.log('delCred extraInfo = ' + JSON.stringify(extraInfo));
290     }
291   });
292   ```
293
294## Unregistering a PIN Inputer
295
296Use [unregisterInputer](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#unregisterinputer8) to unregister the PIN inputer that is no longer required.
297
298**Procedure**
299
300```ts
301pinAuth.unregisterInputer();
302```
303
304## Closing a Session
305
306Use [closeSession](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#closesession8) to close a session to terminate credential management.
307
308**Procedure**
309
310```ts
311userIDM.closeSession();
312```
313
314