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 22| 名称 | 值 | 说明 | 23| ---------- | ----- | ------------------ | 24| PIN_SIX | 10000 | 表示6位凭证。 | 25| PIN_NUMBER | 10001 | 表示自定义数字凭证。 | 26| PIN_MIXED | 10002 | 表示自定义混合凭据。 | 27| FACE_2D | 20000 | 表示2D 人脸凭证。 | 28| FACE_3D | 20001 | 表示3D 人脸凭证。 | 29| FINGERPRINT_CAPACITIVE<sup>10+</sup> | 30000 | 表示电容式指纹。 | 30| FINGERPRINT_OPTICAL<sup>10+</sup> | 30001 | 表示光学指纹。 | 31| FINGERPRINT_ULTRASONIC<sup>10+</sup> | 30002 | 表示超声波指纹。 | 32 33## 开发准备 34 351. 申请权限，申请流程请参考：[申请应用权限](../../security/AccessToken/determine-application-mode.md#system_basic等级应用申请权限的方式)。 36 - ohos.permission.MANAGE_USER_IDM 37 - ohos.permission.ACCESS_PIN_AUTH 38 392. 导入系统账号模块。 40 41 ```ts 42 import { osAccount } from '@kit.BasicServicesKit'; 43 ``` 44 453. 创建凭据管理对象。 46 47 ```ts 48 let userIDM: osAccount.UserIdentityManager = new osAccount.UserIdentityManager(); 49 ``` 50 51## 注册PIN码输入器 52 53输入器用于传递PIN码数据，录入、认证PIN码前需要先注册输入器。 54 55具体开发实例如下： 56 571. 定义PIN码输入器，并获取PIN码。 58 59 ```ts 60 let pinData: Uint8Array = new Uint8Array([31, 32, 33, 34, 35, 36]); // you can obtain a PIN throught 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. 调用[registerInputer](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#registerinputer8)注册PIN码输入器。 69 70 ```ts 71 let pinAuth: osAccount.PINAuth = new osAccount.PINAuth(); 72 pinAuth.registerInputer(inputer); 73 ``` 74 75## 打开会话 76 77在进行凭据管理前，请先打开一个新的会话。开发者可以使用[openSession](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#opensession8)接口完成此操作。 78 79具体开发实例如下： 80 81调用[openSession](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#opensession8)接口打开凭据管理新会话。 82 83 ```ts 84 let challenge: Uint8Array = await userIDM.openSession(); 85 ``` 86 87## 录入PIN码 88 89前述操作完成后，可以进行PIN码录入。开发者可以使用[addCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8)接口完成此操作。 90 91具体开发实例如下： 92 931. 定义PIN码凭据信息。 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. 调用[addCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8)接口添加指定的凭据信息，执行结果通过回调获取。 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## 认证PIN码 115 116录入完PIN码，用户可以进行PIN码认证。开发者可以使用[auth](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#auth8)接口完成此操作。 117 118具体开发实例如下： 119 1201. 定义认证参数，包括挑战值、认证类型、认证可信等级。 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. 调用[auth](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#auth8)接口进行认证。 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## 录入生物识别凭据 142 143PIN码认证成功后，可以录入人脸/指纹，操作流程与录入PIN码类似。 144 145具体开发实例如下： 146 1471. 认证PIN码，获取授权令牌authToken。 148 1492. 定义人脸凭据信息（以2D人脸为例）。 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. 调用[addCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8)录入人脸凭据。 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. 定义指纹凭据信息。 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. 调用[addCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8)录入指纹凭据。 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## 认证生物识别凭据 192 193录入完生物识别凭据后，用户可以进行生物识别认证。类似PIN码认证，开发者可以使用[auth](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#auth8)接口完成此操作。 194 195具体开发实例如下： 196 1971. 定义认证参数（以人脸认证为例），包括挑战值、认证类型、认证可性等级。 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. 调用auth接口进行认证。 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## 更新凭据 218 219用户可以修改系统账号的凭据。开发者可以使用[updateCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#updatecredential8)接口完成此操作。 220 221具体开发实例如下： 222 2231. 认证PIN码，获取授权令牌authToken。 224 2252. 定义待更新凭据信息。 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. 调用[updateCredential](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#updatecredential8)更新凭据。 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## 查询凭据信息 247 248凭据管理界面需要向用户展示已录入的凭据信息；锁屏界面需要展示可认证的凭据类型。开发者可以使用[getAuthInfo](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#getauthinfo8)接口查询已录入的凭据信息，实现前述业务场景功能。 249 250具体开发实例如下： 251 2521. 查询所有已录入的凭据信息。 253 254 ```ts 255 let enrolledCredInfoList: osAccount.EnrolledCredInfo[] = await userIDM.getAuthInfo(); 256 ``` 257 2582. 调用[getAuthInfo](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#getauthinfo8)接口，获取指定类型的凭据信息（以指纹凭据为例）。 259 260 ```ts 261 let enrolledFingerCredInfoList: osAccount.EnrolledCredInfo[] = await userIDM.getAuthInfo(osAccount.AuthType.FINGERPRINT); 262 ``` 263 264## 删除凭据 265 266删除凭据前，需要先进行[认证PIN码](#认证pin码)，并获取待删除凭据的标识（参考[查询凭据信息](#查询凭据信息)）。 267 268以删除指纹凭据为例，具体开发实例如下： 269 2701. 获取指纹类型的凭据信息。 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. [认证PIN码](#认证pin码)，获取授权令牌。 282 2833. 调用[delCred](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#delcred8)接口，删除指定凭据。 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## 注销PIN码输入器 295 296不再使用输入器时，可以调用[unregisterInputer](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#unregisterinputer8)注销PIN码输入器。 297 298具体开发实例如下： 299 300```ts 301pinAuth.unregisterInputer(); 302``` 303 304## 关闭会话 305 306调用[closeSession](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#closesession8)关闭会话，结束凭据管理。 307 308具体开发实例如下： 309 310```ts 311userIDM.closeSession(); 312``` 313