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