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