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| Name      | Value| Description              |
20| ---------- | ----- | ------------------ |
21| PIN_SIX    | 10000 | Six-digit PIN.      |
22| PIN_NUMBER | 10001 | Custom PIN.|
23| PIN_MIXED  | 10002 | Custom mixed PIN.|
24| FACE_2D    | 20000 | 2D face credential.  |
25| FACE_3D    | 20001 | 3D face credential.  |
26| FINGERPRINT_CAPACITIVE<sup>10+</sup>    | 30000 | Capacitive fingerprint.  |
27| FINGERPRINT_OPTICAL<sup>10+</sup>    | 30001 | Optical fingerprint.  |
28| FINGERPRINT_ULTRASONIC<sup>10+</sup>    | 30002 | Ultrasonic fingerprint.  |
29
30**NOTE**<br>The credential types supported by the device depend on the hardware capability.
31
32## Before You Start
33
341. 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).
35   - ohos.permission.MANAGE_USER_IDM
36   - ohos.permission.ACCESS_PIN_AUTH
37
382. Import the **osAccount** module.
39
40   ```ts
41   import { osAccount } from '@kit.BasicServicesKit';
42   ```
43
443. Create a **UserIDM** instance.
45
46   ```ts
47   let userIDM: osAccount.UserIdentityManager = new osAccount.UserIdentityManager();
48   ```
49
50## Registering a PIN Inputer
51
52Register a PIN inputer to transmit PIN data.
53
54**Procedure**
55
561. Define a PIN inputer and obtain the 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: osAccount.IInputer = {
61     onGetData: (authSubType: osAccount.AuthSubType, callback: osAccount.IInputData) => {
62       callback.onSetData(authSubType, pinData);
63     }
64   }
65   ```
66
672. Use [registerInputer](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#registerinputer8) to register the PIN inputer.
68
69   ```ts
70   let pinAuth: osAccount.PINAuth = new osAccount.PINAuth();
71   pinAuth.registerInputer(inputer);
72   ```
73
74## Opening a Session
75
76Use [openSession](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#opensession8) to open a session for credential management.
77
78**Procedure**
79
801. Use [openSession](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#opensession8) to open a session for credential management.
81
82   ```ts
83   let challenge: Uint8Array = await userIDM.openSession();
84   ```
85
86## Enrolling a PIN
87
88Use [addCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8) to enroll a PIN.
89
90**Procedure**
91
921. Defines the PIN authentication credential.
93
94   ```ts
95   let credentialInfo: osAccount.CredentialInfo = {
96     credType: osAccount.AuthType.PIN,
97     credSubType: osAccount.AuthSubType.PIN_SIX;
98     token: new Uint8Array([0])
99   };
100   ```
101
1022. 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.
103
104   ```ts
105   userIDM.addCredential(credentialInfo, {
106     onResult: (code: number, result: osAccount.RequestResult) => {
107       console.log('addCredential code = ' + code);
108       console.log('addCredential result = ' + result);
109     }
110   });
111   ```
112
113## Authenticating a PIN
114
115Use [auth](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#auth8) to perform PIN authentication.
116
117**Procedure**
118
1191. Set authentication parameters, including the challenge value, authentication type, and authentication trust level.
120
121   ```ts
122   let challenge: Uint8Array = new Uint8Array([1, 2, 3, 4, 5]);
123   let authType: osAccount.AuthType = osAccount.AuthType.PIN;
124   let authTrustLevel: osAccount.AuthTrustLevel = osAccount.AuthTrustLevel.ATL1;
125   ```
126
1272. Use [auth](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#auth8) to perform PIN authentication.
128
129   ```ts
130   let userAuth: osAccount.UserAuth = new osAccount.UserAuth();
131   userAuth.auth(challenge, authType, authTrustLevel, {
132     onResult: (result: number, extraInfo: osAccount.AuthResult) => {
133       console.log('pin auth result = ' + result);
134       console.log('pin auth extraInfo = ' + JSON.stringify(extraInfo));
135       let authToken = extraInfo.token;
136     }
137   });
138   ```
139
140## Enrolling Biometric Credentials
141
142Biometric 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.
143
144**Procedure**
145
1461. Perform PIN authentication to obtain the authorization token (**authToken**).
147
1482. Set face credential information. The following uses 2D face credential as an example.
149
150   ```ts
151   let faceCredInfo: osAccount.CredentialInfo = {
152     credType: osAccount.AuthType.FACE,
153     credSubType: osAccount.AuthSubType.FACE_2D,
154     token: new Uint8Array([1, 2, 3, 4, 5])
155   }
156   ```
157
1583. Use [addCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8) to enroll face credentials.
159
160   ```ts
161   userIDM.addCredential(faceCredInfo, {
162     onResult: (code: number, result: osAccount.RequestResult) => {
163       console.log('add face credential, resultCode: ' + code);
164       console.log('add face credential, request result: ' + result);
165     }
166   });
167   ```
168
1694. Set fingerprint credential information.
170
171   ```ts
172   let fingerprintCredInfo: osAccount.CredentialInfo = {
173     credType: osAccount.AuthType.FINGERPRINT,
174     credSubType: osAccount.AuthSubType.FINGERPRINT_CAPACITIVE,
175     token: new Uint8Array([1, 2, 3, 4, 5])
176   }
177   ```
178
1795. Use [addCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8) to enroll the fingerprint.
180
181   ```ts
182   userIDM.addCredential(fingerprintCredInfo, {
183     onResult: (code: number, result: osAccount.RequestResult) => {
184       console.log('add fingerprint credential, resultCode: ' + code);
185       console.log('add fingerprint credential, request result: ' + result);
186     }
187   });
188   ```
189
190## Authenticating Biometric Credentials
191
192Biometric 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.
193
194**Procedure**
195
1961. Set authentication parameters, including the challenge value, authentication type, and authentication trust level. The following uses facial authentication as an example.
197
198   ```ts
199   let challenge: Uint8Array = new Uint8Array([1, 2, 3, 4, 5]);
200   let authType: osAccount.AuthType = osAccount.AuthType.FACE;
201   let authTrustLevel: osAccount.AuthTrustLevel = osAccount.AuthTrustLevel.ATL1;
202   ```
203
2042. Use **auth()** to perform authentication.
205
206   ```ts
207   let userAuth: osAccount.UserAuth = new osAccount.UserAuth();
208   userAuth.auth(challenge, authType, authTrustLevel, {
209     onResult: (result: number, extraInfo: osAccount.AuthResult) => {
210       console.log('face auth result = ' + result);
211       console.log('face auth extraInfo = ' + JSON.stringify(extraInfo));
212     }
213   });
214   ```
215
216## Updating a Credential
217
218The 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.
219
220**Procedure**
221
2221. Perform PIN authentication to obtain the authorization token (**authToken**).
223
2242. Specify the credential information to be updated.
225
226   ```ts
227   let credentialInfo: osAccount.CredentialInfo = {
228     credType: osAccount.AuthType.PIN,
229     credSubType: osAccount.AuthSubType.PIN_SIX,
230     token: new Uint8Array([1, 2, 3, 4, 5])
231   };
232   ```
233
2343. Use [updateCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#updatecredential8) to update the credential.  
235
236   ```ts
237   userIDM.updateCredential(credentialInfo, {
238     onResult: (result: number, extraInfo: osAccount.RequestResult) => {
239       console.log('updateCredential result = ' + result);
240       console.log('updateCredential extraInfo = ' + extraInfo);
241     }
242   });
243   ```
244
245## Obtaining Credential Information
246
247The 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.
248
249**Procedure**
250
2511. Obtain information about all the credentials enrolled.
252
253   ```ts
254   let enrolledCredInfoList: osAccount.EnrolledCredInfo[] = await userIDM.getAuthInfo();
255   ```
256
2572. 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.
258
259   ```ts
260   let enrolledFingerCredInfoList: osAccount.EnrolledCredInfo[] = await userIDM.getAuthInfo(osAccount.AuthType.FINGERPRINT);
261   ```
262
263## Deleting a Credential
264
265Before 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).
266
267For example, delete a fingerprint, do as follows:
268
2691. Obtain the fingerprint information.
270
271   ```ts
272   let credentialId: Uint8Array = new Uint8Array([1, 2, 3, 4, 5]);
273   let token: Uint8Array = new Uint8Array([1, 2, 3, 4, 5])
274   let credInfoList: osAccount.EnrolledCredInfo[] = await userIDM.getAuthInfo(osAccount.AuthType.FINGERPRINT);
275   if (credInfoList.length != 0) {
276     credentialId = credInfoList[0].credentialId;
277   }
278   ```
279
2802. [Perform PIN authentication](#authenticating-a-pin) to obtain the authentication token.
281
2823. Use [delCred](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#delcred8) to delete the fingerprint credential.
283
284   ```ts
285   userIDM.delCred(credentialId, token, {
286     onResult: (result: number, extraInfo: osAccount.RequestResult) => {
287       console.log('delCred result = ' + result);
288       console.log('delCred extraInfo = ' + JSON.stringify(extraInfo));
289     }
290   });
291   ```
292
293## Unregistering a PIN Inputer
294
295Use [unregisterInputer](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#unregisterinputer8) to unregister the PIN inputer that is no longer required.
296
297**Procedure**
298
299```ts
300pinAuth.unregisterInputer();
301```
302
303## Closing a Session
304
305Use [closeSession](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#closesession8) to close a session to terminate credential management.
306
307**Procedure**
308
309```ts
310userIDM.closeSession();
311```
312