Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
未验证 提交 0a00363b 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!21532 useriam api10 doc delete about AuthWidget for beta2 

Merge pull request !21532 from liuhanxiong/OpenHarmony-4.0-Beta2
上级 4f81ffe2 fec4969c
隐藏空白更改
内联 并排
Showing with 45 addition and 1359 deletion
en/application-dev/reference/apis/js-apis-useriam-userauth.md
浏览文件 @ 0a00363b
...@@ -13,671 +13,6 @@ The **userIAM.userAuth** module provides user authentication capabilities in ide ...@@ -13,671 +13,6 @@ The **userIAM.userAuth** module provides user authentication capabilities in ide
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
``` ```
## WindowModeType<sup>10+</sup>
Enumerates the window types of the authentication widget.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Value | Description |
| ---------- | ---- | ---------- |
| DIALOG_BOX | 1 | Dialog box.|
| FULLSCREEN | 2 | Full screen.|
## AuthParam<sup>10+</sup>
Defines the user authentication parameters.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Type | Mandatory| Description |
| -------------- | ---------------------------------- | ---- | -------------------------------------- |
| challenge | Uint8Array | Yes | Challenge value. The maximum length is 32 bytes. The value can be **null**.|
| authType | [UserAuthType](#userauthtype8)[] | Yes | Authentication type. |
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. |
## WidgetParam<sup>10+</sup>
Defines the parameters of the authentication widget.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Type | Mandatory| Description |
| -------------------- | ----------------------------------- | ---- | -------------------- |
| title | string | Yes | Title of the authentication component. |
| navigationButtonText | string | No | Description text of the navigation button.|
| windowModeType | [WindowModeType](#windowmodetype10) | No | Type of the window. |
## UserAuthResult<sup>10+</sup>
Defines the user authentication result.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Type | Mandatory| Description |
| -------- | ------------------------------ | ---- | ------------------------------------------------------------ |
| result | number | Yes | User authentication result. If the operation is successful, **0** is returned. If the operation fails, an error code is returned. For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).|
| token | Uint8Array | No | Authentication token information. |
| authType | [UserAuthType](#userauthtype8) | No | Authentication type. |
## IAuthCallback<sup>10+</sup>
Provides callbacks to return the authentication result.
### onResult<sup>10+</sup>
onResult(result: UserAuthResult): void
Called to return the authentication result.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------------------------------- | ---- | ---------- |
| result | [UserAuthResult](userauthresult10) | Yes | Authentication result.|
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
AuthParam authParam = {
challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
authType: userIAM_userAuth.UserAuthType.PIN;
authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1;
}
WidgetParam widgetParam = {
title: "Enter Password";
windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX;
}
let userAuthInstance;
try {
userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
console.info("get userAuth instance success");
} catch (error) {
console.info("get userAuth instance failed, error = " + error);
}
try {
userAuthInstance.on('result', {
callback: onResult(result) {
console.log("authV10 result " + result.result);
console.log("authV10 token " + result.token);
console.log("authV10 authType " + result.authType);
}
});
console.info("subscribe authentication event success");
} catch (error) {
console.info("subscribe authentication event failed" + error);
//do error
}
```
## UserAuthInstance<sup>10+</sup>
Provides APIs for user authentication. The user authentication widget is supported.
Before using the APIs, you need to obtain a **UserAuthInstance** instance by using [getUserAuthInstance](#useriam_userauthgetuserauthinstance10).
### on<sup>10+</sup>
on(type: 'result', callback: IAuthCallback): void
Subscribes to the user authentication result.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------- | ---- | ------------------------------------------ |
| type | 'result' | Yes | Event type to subscribe to. **result** indicates the authentication result.|
| callback | [IAuthCallback](iauthcallback10) | Yes | Callback invoked to return the user authentication result. |
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message |
| -------- | ------------------------ |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
AuthParam authParam = {
challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
authType: userIAM_userAuth.UserAuthType.PIN;
authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1;
}
WidgetParam widgetParam = {
title: "Enter Password";
windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX;
}
let userAuthInstance;
try {
userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
console.info("get userAuth instance success");
} catch (error) {
console.info("get userAuth instance failed, error = " + error);
}
try {
userAuthInstance.on('result', {
callback: onResult(result) {
console.log("authV10 result " + result.result);
console.log("authV10 token " + result.token);
console.log("authV10 authType " + result.authType);
}
});
console.info("subscribe authentication event success");
} catch (error) {
console.info("subscribe authentication event failed" + error);
//do error
}
```
### off<sup>10+</sup>
off(type: 'result', callback?: IAuthCallback): void
Unsubscribes from the user authentication result.
> **NOTE**<br>You need to use the [UserAuthInstance](#userauthinstance10) instance that has successfully subscribed to the event to call this API to cancel the subscription.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------- | ---- | ------------------------------------------ |
| type | 'result' | Yes | Event type to unsubscribe from. **result** indicates the authentication result.|
| callback | [IAuthCallback](iauthcallback10) | No | Callback for the user authentication result. |
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message |
| -------- | ------------------------ |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
AuthParam authParam = {
challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
authType: userIAM_userAuth.UserAuthType.PIN;
authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1;
}
WidgetParam widgetParam = {
title: "Enter Password";
windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX;
}
let userAuthInstance;
try {
userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
console.info("get userAuth instance success");
} catch (error) {
console.info("get userAuth instance failed, error = " + error);
}
// Subscribe to the authentication result.
try {
userAuthInstance.on('result', {
callback: onResult(result) {
console.log("authV10 result " + result.result);
console.log("authV10 token " + result.token);
console.log("authV10 authType " + result.authType);
}
});
console.info("subscribe authentication event success");
} catch (error) {
console.info("subscribe authentication event failed" + error);
//do error
}
// Unsubscribe from the authentication result.
try {
userAuthInstance.off('result');
console.info("cancel subscribe authentication event success");
} catch (error) {
console.info("cancel subscribe authentication event failed" + error);
//do error
}
```
### start<sup>10+</sup>
start(): void
Starts an authentication.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message |
| -------- | ------------------------------------------------ |
| 201 | Permission verification failed. |
| 401 | Incorrect parameters. |
| 12500001 | Authentication failed. |
| 12500002 | General operation error. |
| 12500003 | The operation is canceled. |
| 12500004 | The operation is time-out. |
| 12500005 | The authentication type is not supported. |
| 12500006 | The authentication trust level is not supported. |
| 12500007 | The authentication task is busy. |
| 12500009 | The authenticator is locked. |
| 12500010 | The type of credential has not been enrolled. |
| 12500011 | The authentication is canceled from widget's navigation button. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
AuthParam authParam = {
challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
authType: userIAM_userAuth.UserAuthType.PIN;
authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1;
}
WidgetParam widgetParam = {
title: "Enter Password";
windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX;
}
let userAuthInstance;
try {
userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
console.info("get userAuth instance success");
} catch (error) {
console.info("get userAuth instance failed, error = " + error);
}
try {
userAuthInstance.start();
console.info("userAuthInstanceV10 start auth success");
} catch (error) {
console.info("userAuthInstanceV10 start auth failed, error = " + error);
//do error
}
```
### cancel<sup>10+</sup>
cancel(): void
Cancels this authentication.
> **NOTE**<br>**UserAuthInstance** must be the instance being authenticated.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Error codes**
| ID| Error Message |
| -------- | ------------------------------- |
| 201 | Permission verification failed. |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
AuthParam authParam = {
challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
authType: userIAM_userAuth.UserAuthType.PIN;
authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1;
}
WidgetParam widgetParam = {
title: "Enter Password";
windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX;
}
let userAuthInstance;
try {
userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
console.info("get userAuth instance success");
} catch (error) {
console.info("get userAuth instance failed, error = " + error);
}
// Start user authentication.
try {
userAuthInstance.start();
console.info("userAuthInstanceV10 start auth success");
} catch (error) {
console.info("userAuthInstanceV10 start auth failed, error = " + error);
//do error
}
// Cancel the authentication.
try {
userAuthInstance.cancel();
console.info("cancel auth success");
} catch (error) {
console.info("cancel auth failed, error = " + error);
//do error
}
```
## userIAM_userAuth.getUserAuthInstance<sup>10+</sup>
getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance
Obtains a [UserAuthInstance](#userauthinstance10) instance for user authentication. The user authentication widget is supported.
> **NOTE**<br>
> A **UserAuthInstance** instance can be used for an authentication only once.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | ----------------------------- | ---- | -------------------------------------- |
| authParam | [AuthParam](authparam10) | Yes | Challenge value. The maximum length is 32 bytes. The value can be **null**.|
| widgetParam | [WidgetParam](#widgetparam10) | Yes | Authentication type. Only **FACE** is supported. |
**Return value**
| Type | Description |
| --------------------------------------- | ------------ |
| [UserAuthInstance](#userauthinstance10) | **UserAuthInstance** instance obtained.|
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message |
| -------- | ------------------------------------------------ |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
| 12500005 | The authentication type is not supported. |
| 12500006 | The authentication trust level is not supported. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
AuthParam authParam = {
challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
authType: userIAM_userAuth.UserAuthType.PIN;
authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1;
}
WidgetParam widgetParam = {
title: "Enter Password";
windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX;
}
try {
let userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
console.info("get userAuth instance success");
} catch (error) {
console.info("get userAuth instance failed, error = " + error);
}
```
## NoticeType<sup>10+</sup>
Defines the type of the user authentication notification.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Value | Description |
| ------------- | ---- | -------------------- |
| WIDGET_NOTICE | 1 | Notification from the user authentication widget.|
## userIAM_userAuth.sendNotice<sup>10+</sup>
sendNotice(noticeType: NoticeType, eventData: string): void
Sends a notification from the user authentication widget.
**Required permissions**: ohos.permission.SUPPORT_USER_AUTH
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------------------------- | ---- | ---------- |
| noticeType | [NoticeType](#noticetype) | Yes | Notification type.|
| eventData | string | Yes | Event data.|
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message |
| -------- | --------------------------------------- |
| 201 | Permission verification failed. |
| 202 | The caller is not a system application. |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let noticeType = userIAM_userAuth.NoticeType.WIDGET_NOTICE;
sendNotice(noticeType, {"eventData" : "EVENT_AUTH_TYPE_READY"});
```
## UserAuthWidgetMgr<sup>10+</sup>
Provides APIs for managing the user authentication widget. You can use the APIs to register the user authentication widget with UserAuthWidgetMgr for management and scheduling.
### on<sup>10+</sup>
on(type: 'command', callback: IAuthWidgetCallback): void
Subscribes to commands from the user authentication framework.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | 'command' | Yes | Event type to subscribe to. **command** indicates the command sent from the user authentication framework to the user authentication widget.|
| callback | [IAuthWidgetCallback](#iauthwidgetcallback10) | Yes | Callback invoked to send the command from the user authentication framework to the user authentication widget.|
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message |
| -------- | ------------------------ |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let version = 1;
let userAuthWidgetMgr;
try {
userAuthWidgetMgr = userIAM_userAuth.getUserAuthWidgetMgr(version);
console.info("get userAuthWidgetMgr instance success");
} catch (error) {
console.info("get userAuthWidgetMgr instance failed, error = " + error);
}
try {
userAuthWidgetMgr.on('command', {
callback: sendCommand(cmdData) {
console.log("The cmdData is " + cmdData);
}
})
console.info("subscribe authentication event success");
} catch (error) {
console.info("subscribe authentication event failed, error = " + error);
}
```
### off<sup>10+</sup>
off(type: 'command', callback?: IAuthWidgetCallback): void
Unsubscribes from commands sent from the user authentication framework.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | 'command' | Yes | Event type to unsubscribe from. **command** indicates the command sent from the user authentication framework to the user authentication widget.|
| callback | [IAuthWidgetCallback](#iauthwidgetcallback10) | No | Callback for the command sent from the user authentication framework to the user authentication widget.|
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message |
| -------- | ------------------------ |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let version = 1;
let userAuthWidgetMgr;
try {
userAuthWidgetMgr = userIAM_userAuth.getUserAuthWidgetMgr(version);
console.info("get userAuthWidgetMgr instance success");
} catch (error) {
console.info("get userAuthWidgetMgr instance failed, error = " + error);
}
// Subscribe to the commands sent from the user authentication framework.
try {
userAuthWidgetMgr.on('command', {
callback: sendCommand(cmdData) {
console.log("The cmdData is " + cmdData);
}
})
console.info("subscribe authentication event success");
} catch (error) {
console.info("subscribe authentication event failed, error = " + error);
}
// Unsubscribe from the commands sent from the user authentication framework.
try {
userAuthWidgetMgr.off('command');
console.info("cancel subscribe authentication event success");
} catch (error) {
console.info("cancel subscribe authentication event failed, error = " + error);
}
```
## userIAM_userAuth.getUserAuthWidgetMgr<sup>10+</sup>
getUserAuthWidgetMgr(version: number): UserAuthWidgetMgr
Obtains a **UserAuthWidgetMgr** instance for user authentication.
> **NOTE**<br>
> A **UserAuthInstance** instance can be used for an authentication only once.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------ | ---- | -------------------- |
| version | number | Yes | Version of the user authentication widget.|
**Return value**
| Type | Description |
| ----------------------------------------- | ------------ |
| [UserAuthWidgetMgr](#userauthwidgetmgr10) | **UserAuthWidgetMgr** instance obtained.|
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message |
| -------- | --------------------------------------- |
| 201 | Permission verification failed. |
| 202 | The caller is not a system application. |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let version = 1;
try {
let userAuthWidgetMgr = userIAM_userAuth.getUserAuthWidgetMgr(version);
console.info("get userAuthWidgetMgr instance success");
} catch (error) {
console.info("get userAuthWidgetMgr instance failed, error = " + error);
}
```
## IAuthWidgetCallback<sup>10+</sup>
Provides the callback for returning the commands sent from the user authentication framework to the user authentication widget.
### sendCommand<sup>10+</sup>
sendCommand(cmdData: string): void
Called to return the command sent from the user authentication framework to the user authentication widget.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------ | ---- | ---------------------------------- |
| cmdData | string | Yes | Command sent from the user identity authentication framework to the user authentication widget.|
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let version = 1;
try {
let userAuthWidgetMgr = userIAM_userAuth.getUserAuthWidgetMgr(version);
userAuthWidgetMgr.on('command', {
callback: sendCommand(cmdData) {
console.log("The cmdData is " + cmdData);
}
})
console.info("subscribe authentication event success");
} catch (error) {
console.info("subscribe authentication event failed, error = " + error);
}
```
## AuthResultInfo<sup>9+</sup> ## AuthResultInfo<sup>9+</sup>
Defines the authentication result. Defines the authentication result.
...@@ -715,14 +50,14 @@ Enumerates the authentication event information types. ...@@ -715,14 +50,14 @@ Enumerates the authentication event information types.
## AuthEventKey<sup>9+</sup> ## AuthEventKey<sup>9+</sup>
Defines the keyword of the authentication event type. It is used as a parameter of [on](#ondeprecated). Defines the keyword of the authentication event type. It is used as a parameter of [on](#on9).
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
| Value | Description | | Value | Description |
| ---------- | ----------------------- | | ---------- | ----------------------- |
| "result" | If the first parameter of [on](#ondeprecated) is **result**, the [callback](#callback9) returns the authentication result.| | "result" | If the first parameter of [on](#on9) is **result**, the [callback](#callback9) returns the authentication result.|
| "tip" | If the first parameter of [on](#ondeprecated) is **tip**, the [callback](#callback9) returns the authentication tip information.| | "tip" | If the first parameter of [on](#on9) is **tip**, the [callback](#callback9) returns the authentication tip information.|
## AuthEvent<sup>9+</sup> ## AuthEvent<sup>9+</sup>
...@@ -790,14 +125,14 @@ try { ...@@ -790,14 +125,14 @@ try {
} }
``` ```
## AuthInstance<sup>(deprecated)</sup> ## AuthInstance<sup>9+</sup>
Implements user authentication. Implements user authentication.
> **NOTE**<br> > **NOTE**<br>
> This API is supported since API version 9 and deprecated since API version 10. Use [UserAuthInstance](#userauthinstance10) instead. > This API is supported since API version 9.
### on<sup>(deprecated)</sup> ### on<sup>9+</sup>
on : (name : AuthEventKey, callback : AuthEvent) => void on : (name : AuthEventKey, callback : AuthEvent) => void
...@@ -807,7 +142,7 @@ Subscribes to the user authentication events of the specified type. ...@@ -807,7 +142,7 @@ Subscribes to the user authentication events of the specified type.
> This API is supported since API version 9 and deprecated since API version 10. > This API is supported since API version 9 and deprecated since API version 10.
> **NOTE**<br> > **NOTE**<br>
> Use the [AuthInstance](#authinstancedeprecated) instance obtained to invoke this API to subscribe to events. > Use the [AuthInstance](#authinstance9) instance obtained to invoke this API to subscribe to events.
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
...@@ -867,17 +202,17 @@ try { ...@@ -867,17 +202,17 @@ try {
} }
``` ```
### off<sup>(deprecated)</sup> ### off<sup>9+</sup>
off : (name : AuthEventKey) => void off : (name : AuthEventKey) => void
Unsubscribes from the user authentication events of the specific type. Unsubscribes from the user authentication events of the specific type.
>**NOTE**<br> >**NOTE**<br>
>This API is supported since API version 9 and deprecated since API version 10. >This API is supported since API version 9.
> **NOTE**<br> > **NOTE**<br>
> Use the [AuthInstance](#authinstancedeprecated) instance obtained to invoke this API to unsubscribe from events. > Use the [AuthInstance](#authinstance9) instance obtained to invoke this API to unsubscribe from events.
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
...@@ -933,17 +268,17 @@ try { ...@@ -933,17 +268,17 @@ try {
} }
``` ```
### start<sup>(deprecated)</sup> ### start<sup>9+</sup>
start : () => void start : () => void
Starts authentication. Starts authentication.
> **NOTE**<br> > **NOTE**<br>
> This API is supported since API version 9 and deprecated since API version 10. > This API is supported since API version 9.
> **NOTE**<br> > **NOTE**<br>
> Use the [AuthInstance](#authinstancedeprecated) instance obtained to invoke this API. > Use the [AuthInstance](#authinstance9) instance obtained to invoke this API.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC **Required permissions**: ohos.permission.ACCESS_BIOMETRIC
...@@ -985,17 +320,17 @@ try { ...@@ -985,17 +320,17 @@ try {
} }
``` ```
### cancel<sup>(deprecated)</sup> ### cancel<sup>9+</sup>
cancel : () => void cancel : () => void
Cancels this authentication. Cancels this authentication.
> **NOTE**<br> > **NOTE**<br>
> This API is supported since API version 9 and deprecated since API version 10. > This API is supported since API version 9.
> **NOTE**<br> > **NOTE**<br>
> Use the [AuthInstance](#authinstancedeprecated) instance obtained to invoke this API. The [AuthInstance](#authinstancedeprecated) instance must be the instance being authenticated. > Use the [AuthInstance](#authinstance9) instance obtained to invoke this API. The [AuthInstance](#authinstance9) instance must be the instance being authenticated.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC **Required permissions**: ohos.permission.ACCESS_BIOMETRIC
...@@ -1029,14 +364,14 @@ try { ...@@ -1029,14 +364,14 @@ try {
} }
``` ```
## userIAM_userAuth.getAuthInstance<sup>(deprecated)</sup> ## userIAM_userAuth.getAuthInstance<sup>9+</sup>
getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance
Obtains an **AuthInstance** instance for user authentication. Obtains an **AuthInstance** instance for user authentication.
> **NOTE**<br> > **NOTE**<br>
> This API is supported since API version 9 and deprecated since API version 10. Use [getUserAuthInstance](#useriam_userauthgetuserauthinstance10) instead. > This API is supported since API version 9.
> **NOTE**<br> > **NOTE**<br>
> An **AuthInstance** instance can be used for an authentication only once. > An **AuthInstance** instance can be used for an authentication only once.
...@@ -1055,7 +390,7 @@ Obtains an **AuthInstance** instance for user authentication. ...@@ -1055,7 +390,7 @@ Obtains an **AuthInstance** instance for user authentication.
| Type | Description | | Type | Description |
| --------------------------------------- | ------------ | | --------------------------------------- | ------------ |
| [AuthInstance](#authinstancedeprecated) | **AuthInstance** instance obtained.| | [AuthInstance](#authinstance9) | **AuthInstance** instance obtained.|
**Error codes** **Error codes**
...@@ -1146,7 +481,6 @@ Enumerates the authentication result codes. ...@@ -1146,7 +481,6 @@ Enumerates the authentication result codes.
| BUSY | 12500007 | Indicates the busy state. | | BUSY | 12500007 | Indicates the busy state. |
| LOCKED | 12500009 | The authentication executor is locked. | | LOCKED | 12500009 | The authentication executor is locked. |
| NOT_ENROLLED | 12500010 | The user has not entered the authentication information.| | NOT_ENROLLED | 12500010 | The user has not entered the authentication information.|
| CANCELED_FROM_WIDGET | 12500011 | The authentication is canceled by the user from the user authentication widget. If this error code is returned, the authentication is customized by the application.|
## UserAuth<sup>(deprecated)</sup> ## UserAuth<sup>(deprecated)</sup>
...@@ -1159,7 +493,7 @@ constructor() ...@@ -1159,7 +493,7 @@ constructor()
A constructor used to create a **UserAuth** instance. A constructor used to create a **UserAuth** instance.
> **NOTE**<br> > **NOTE**<br>
> This API is supported since API version 8 and deprecated since API version 9. Use [getAuthInstance](#useriam_userauthgetauthinstancedeprecated) instead. > This API is supported since API version 8 and deprecated since API version 9. Use [getAuthInstance](#useriam_userauthgetauthinstance9) instead.
**System capability**: SystemCapability.UserIAM.UserAuth.Core **System capability**: SystemCapability.UserIAM.UserAuth.Core
...@@ -1253,7 +587,7 @@ auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLev ...@@ -1253,7 +587,7 @@ auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLev
Performs user authentication. This API uses a callback to return the result. Performs user authentication. This API uses a callback to return the result.
> **NOTE**<br> > **NOTE**<br>
> This API is supported since API version 8 and deprecated since API version 9. Use [start](#startdeprecated) instead. > This API is supported since API version 8 and deprecated since API version 9. Use [start](#start9) instead.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC **Required permissions**: ohos.permission.ACCESS_BIOMETRIC
...@@ -1304,7 +638,7 @@ cancelAuth(contextID : Uint8Array) : number ...@@ -1304,7 +638,7 @@ cancelAuth(contextID : Uint8Array) : number
Cancels an authentication based on the context ID. Cancels an authentication based on the context ID.
> **NOTE**<br> > **NOTE**<br>
> This API is supported since API version 8 and deprecated since API version 9. Use [cancel](#canceldeprecated) instead. > This API is supported since API version 8 and deprecated since API version 9. Use [cancel](#cancel9) instead.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC **Required permissions**: ohos.permission.ACCESS_BIOMETRIC
...@@ -1507,7 +841,6 @@ Enumerates the identity authentication types. ...@@ -1507,7 +841,6 @@ Enumerates the identity authentication types.
| Name | Value | Description | | Name | Value | Description |
| ----------- | ---- | ---------- | | ----------- | ---- | ---------- |
| PIN<sup>10+</sup> | 1 | PIN authentication.|
| FACE | 2 | Facial authentication.| | FACE | 2 | Facial authentication.|
| FINGERPRINT | 4 | Fingerprint authentication.| | FINGERPRINT | 4 | Fingerprint authentication.|
......
zh-cn/application-dev/reference/apis/js-apis-useriam-userauth.md
浏览文件 @ 0a00363b
...@@ -12,626 +12,6 @@ ...@@ -12,626 +12,6 @@
import userIAM_userAuth from '@ohos.userIAM.userAuth'; import userIAM_userAuth from '@ohos.userIAM.userAuth';
``` ```
## WindowModeType<sup>10+</sup>
用户认证界面的显示类型。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**系统接口**: 此接口为系统接口。
| 名称 | 值 | 说明 |
| ---------- | ---- | ---------- |
| DIALOG_BOX | 1 | 弹框类型。 |
| FULLSCREEN | 2 | 全屏类型。 |
## AuthParam<sup>10+</sup>
用户认证相关参数。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 类型 | 必填 | 说明 |
| -------------- | ---------------------------------- | ---- | ------------------------------------------------------ |
| challenge | Uint8Array | 是 | 挑战值，用来防重放攻击。最大长度为32字节，可以填null。 |
| authType | [UserAuthType](#userauthtype8)[] | 是 | 认证类型列表，用来指定用户认证界面提供的认证方法。 |
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 |
## WidgetParam<sup>10+</sup>
用户认证界面配置相关参数。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 类型 | 必填 | 说明 |
| -------------------- | ----------------------------------- | ---- | ------------------------------------------------------------ |
| title | string | 是 | 用户认证界面的标题，最大长度为500字符。 |
| navigationButtonText | string | 否 | 导航按键的说明文本，最大长度为60字符。 |
| windowMode | [WindowModeType](#windowmodetype10) | 否 | 代表用户认证界面的显示类型，默认值为WindowModeType.DIALOG_BOX。<br>**系统接口**: 此接口为系统接口。 |
## UserAuthResult<sup>10+</sup>
用户认证结果。当认证结果为成功时，返回认证类型和认证通过的令牌信息。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
| 名称 | 类型 | 必填 | 说明 |
| -------- | ------------------------------ | ---- | ------------------------------------------------------------ |
| result | number | 是 | 用户认证结果。若结果为成功返回0，若失败返回相应错误码，错误码详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 |
| token | Uint8Array | 否 | 当认证结果为成功时，返回认证通过的令牌信息。 |
| authType | [UserAuthType](#userauthtype8) | 否 | 当认证结果为成功时，返回认证类型。 |
## IAuthCallback<sup>10+</sup>
返回认证结果的回调对象。
### onResult<sup>10+</sup>
onResult(result: UserAuthResult): void
回调函数，返回认证结果。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ----------------------------------- | ---- | ---------- |
| result | [UserAuthResult](#userauthresult10) | 是 | 认证结果。 |
**示例：**
```js
import userAuth from '@ohos.userIAM.userAuth';
const authParam = {
challenge: new Uint8Array([49, 49, 49, 49, 49, 49]),
authType: [userAuth.UserAuthType.PIN],
authTrustLevel: 10000,
};
const widgetParam = {
title: '请输入密码',
navigationButtonText: '返回',
windowMode: userAuth.WindowModeType.DIALOG_BOX,
};
try {
let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
console.log('get userAuth instance success');
userAuthInstance.on('result', {
onResult (result) {
console.log('userAuthInstance callback result = ' + JSON.stringify(result));
}
});
console.log('auth on success');
} catch (error) {
console.log('auth catch error: ' + JSON.stringify(error));
}
```
## UserAuthInstance<sup>10+</sup>
用于执行用户身份认证，并支持使用统一用户身份认证组件。
使用以下接口前，都需要先通过[getUserAuthInstance](#getuserauthinstance10)方法获取UserAuthInstance对象。
### on<sup>10+</sup>
on(type: 'result', callback: IAuthCallback): void
订阅用户身份认证结果。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------- | ---- | ------------------------------------------ |
| type | 'result' | 是 | 订阅事件类型，表明该事件用来返回认证结果。 |
| callback | [IAuthCallback](#iauthcallback10) | 是 | 认证接口的回调函数，用于返回认证结果。 |
**错误码：**
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。
| 错误码ID | 错误信息 |
| -------- | ------------------------ |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**示例：**
```js
import userAuth from '@ohos.userIAM.userAuth';
const authParam = {
challenge: new Uint8Array([49, 49, 49, 49, 49, 49]),
authType: [userAuth.UserAuthType.PIN],
authTrustLevel: 10000,
};
const widgetParam = {
title: '请输入密码',
navigationButtonText: '返回',
windowMode: userAuth.WindowModeType.DIALOG_BOX,
};
try {
let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
console.log('get userAuth instance success');
userAuthInstance.on('result', {
onResult (result) {
console.log('userAuthInstance callback result = ' + JSON.stringify(result));
}
});
console.log('auth on success');
} catch (error) {
console.log('auth catch error: ' + JSON.stringify(error));
}
```
### off<sup>10+</sup>
off(type: 'result', callback?: IAuthCallback): void
取消订阅用户身份认证结果。
> **说明**：需要使用已经成功订阅事件的[UserAuthInstance](#userauthinstance10)对象调用该接口进行取消订阅。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------- | ---- | ------------------------------------------ |
| type | 'result' | 是 | 订阅事件类型，表明该事件用来返回认证结果。 |
| callback | [IAuthCallback](#iauthcallback10) | 否 | 认证接口的回调函数，用于返回认证结果。 |
**错误码：**
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。
| 错误码ID | 错误信息 |
| -------- | ------------------------ |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**示例：**
```js
import userAuth from '@ohos.userIAM.userAuth';
const authParam = {
challenge: new Uint8Array([49, 49, 49, 49, 49, 49]),
authType: [userAuth.UserAuthType.PIN],
authTrustLevel: 10000,
};
const widgetParam = {
title: '请输入密码',
navigationButtonText: '返回',
windowMode: userAuth.WindowModeType.DIALOG_BOX,
};
try {
let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
console.log('get userAuth instance success');
userAuthInstance.off('result', {
onResult (result) {
console.log('auth off result: ' + JSON.stringify(result));
}
});
console.log('auth off success');
} catch (error) {
console.log('auth catch error: ' + JSON.stringify(error));
}
```
### start<sup>10+</sup>
start(): void
开始认证。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**错误码：**
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。
| 错误码ID | 错误信息 |
| -------- | ------------------------------------------------ |
| 201 | Permission verification failed. |
| 401 | Incorrect parameters. |
| 12500001 | Authentication failed. |
| 12500002 | General operation error. |
| 12500003 | The operation is canceled. |
| 12500004 | The operation is time-out. |
| 12500005 | The authentication type is not supported. |
| 12500006 | The authentication trust level is not supported. |
| 12500007 | The authentication task is busy. |
| 12500009 | The authenticator is locked. |
| 12500010 | The type of credential has not been enrolled. |
| 12500011 | The authentication is canceled from widget's navigation button. |
**示例：**
```js
import userAuth from '@ohos.userIAM.userAuth';
const authParam = {
challenge: new Uint8Array([49, 49, 49, 49, 49, 49]),
authType: [userAuth.UserAuthType.PIN],
authTrustLevel: 10000,
};
const widgetParam = {
title: '请输入密码',
navigationButtonText: '返回',
windowMode: userAuth.WindowModeType.DIALOG_BOX,
};
try {
let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
console.log('get userAuth instance success');
userAuthInstance.start();
console.log('auth start success');
} catch (error) {
console.log('auth catch error: ' + JSON.stringify(error));
}
```
### cancel<sup>10+</sup>
cancel(): void
取消认证。
> **说明**：此时UserAuthInstance需要是正在进行认证的对象。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**错误码：**
| 错误码ID | 错误信息 |
| -------- | ------------------------------- |
| 201 | Permission verification failed. |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**示例：**
```js
import userAuth from '@ohos.userIAM.userAuth';
const authParam = {
challenge: new Uint8Array([49, 49, 49, 49, 49, 49]),
authType: [userAuth.UserAuthType.PIN],
authTrustLevel: 10000,
};
const widgetParam = {
title: '请输入密码',
navigationButtonText: '返回',
windowMode: userAuth.WindowModeType.DIALOG_BOX,
};
try {
let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
console.log('get userAuth instance success');
userAuthInstance.cancel();
console.log('auth cancel success');
} catch (error) {
console.log('auth catch error: ' + JSON.stringify(error));
}
```
## getUserAuthInstance<sup>10+</sup>
getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance
获取[UserAuthInstance](#userauthinstance10)对象，用于执行用户身份认证，并支持使用统一用户身份认证组件。
> **说明：**
> 每个UserAuthInstance只能进行一次认证，若需要再次进行认证则需重新获取UserAuthInstance。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------- | ----------------------------- | ---- | -------------------------- |
| authParam | [AuthParam](#authparam10) | 是 | 用户认证相关参数。 |
| widgetParam | [WidgetParam](#widgetparam10) | 是 | 用户认证界面配置相关参数。 |
**返回值：**
| 类型 | 说明 |
| --------------------------------------- | -------------------------- |
| [UserAuthInstance](#userauthinstance10) | 支持用户界面的认证器对象。 |
**错误码：**
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。
| 错误码ID | 错误信息 |
| -------- | ------------------------------------------------ |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
| 12500005 | The authentication type is not supported. |
| 12500006 | The authentication trust level is not supported. |
**示例：**
```js
import userAuth from '@ohos.userIAM.userAuth';
const authParam = {
challenge: new Uint8Array([49, 49, 49, 49, 49, 49]),
authType: [userAuth.UserAuthType.PIN],
authTrustLevel: 10000,
};
const widgetParam = {
title: '请输入密码',
navigationButtonText: '返回',
windowMode: userAuth.WindowModeType.DIALOG_BOX,
};
try {
let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
console.log('get userAuth instance success');
} catch (error) {
console.log('auth catch error: ' + JSON.stringify(error));
}
```
## NoticeType<sup>10+</sup>
用户身份认证的通知类型。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**系统接口**: 此接口为系统接口。
| 名称 | 值 | 说明 |
| ------------- | ---- | -------------------- |
| WIDGET_NOTICE | 1 | 表示来自组件的通知。 |
## sendNotice<sup>10+</sup>
sendNotice(noticeType: NoticeType, eventData: string): void
在使用统一身份认证组件进行用户身份认证时，用于接收来自统一身份认证组件的通知。
**需要权限**：ohos.permission.SUPPORT_USER_AUTH
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**系统接口**: 此接口为系统接口。
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | --------------------------- | ---- | ---------- |
| noticeType | [NoticeType](#noticetype10) | 是 | 通知类型。 |
| eventData | string | 是 | 事件数据。 |
**错误码：**
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。
| 错误码ID | 错误信息 |
| -------- | --------------------------------------- |
| 201 | Permission verification failed. |
| 202 | The caller is not a system application. |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**示例：**
```js
import userAuth from '@ohos.userIAM.userAuth';
try {
const eventData = {
widgetContextId: 123456,
event: 'EVENT_AUTH_TYPE_READY',
version: '1',
payload: {
type: ['pin']
},
};
const jsonEventData = JSON.stringify(eventData);
let noticeType = userAuth.NoticeType.WIDGET_NOTICE;
userAuth.sendNotice(noticeType, jsonEventData);
console.log('sendNotice success');
} catch (error) {
console.log('sendNotice catch error: ' + JSON.stringify(error));
}
```
## UserAuthWidgetMgr<sup>10+</sup>
组件管理接口，可将用身份认证组件注册到UserAuthWidgetMgr中，由UserAuthWidgetMgr进行管理、调度。
### on<sup>10+</sup>
on(type: 'command', callback: IAuthWidgetCallback): void
身份认证组件订阅来自用户认证框架的命令。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**系统接口**: 此接口为系统接口。
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | 'command' | 是 | 订阅事件类型，表明该事件用于用户认证框架向身份认证组件发送命令。 |
| callback | [IAuthWidgetCallback](#iauthwidgetcallback10) | 是 | 组件管理接口的回调函数，用于用户认证框架向身份认证组件发送命令。 |
**错误码：**
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。
| 错误码ID | 错误信息 |
| -------- | ------------------------ |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**示例：**
```js
import userAuth from '@ohos.userIAM.userAuth';
const userAuthWidgetMgrVersion = 1;
try {
let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
console.log('get userAuthWidgetMgr instance success');
userAuthWidgetMgr.on('command', {
sendCommand(cmdData) {
console.log('The cmdData is ' + cmdData);
}
})
console.log('subscribe authentication event success');
} catch (error) {
console.log('userAuth widgetMgr catch error: ' + JSON.stringify(error));
}
```
### off<sup>10+</sup>
off(type: 'command', callback?: IAuthWidgetCallback): void
身份认证组件取消订阅来自用户认证框架的命令。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**系统接口**: 此接口为系统接口。
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | 'command' | 是 | 订阅事件类型，表明该事件用于用户认证框架向身份认证组件发送命令。 |
| callback | [IAuthWidgetCallback](#iauthwidgetcallback10) | 否 | 组件管理接口的回调函数，用于用户认证框架向身份认证组件发送命令。 |
**错误码：**
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。
| 错误码ID | 错误信息 |
| -------- | ------------------------ |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**示例：**
```js
import userAuth from '@ohos.userIAM.userAuth';
const userAuthWidgetMgrVersion = 1;
try {
let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
console.log('get userAuthWidgetMgr instance success');
userAuthWidgetMgr.off('command', {
sendCommand(cmdData) {
console.log('The cmdData is ' + cmdData);
}
})
console.log('cancel subscribe authentication event success');
} catch (error) {
console.log('userAuth widgetMgr catch error: ' + JSON.stringify(error));
}
```
## getUserAuthWidgetMgr<sup>10+</sup>
getUserAuthWidgetMgr(version: number): UserAuthWidgetMgr
获取UserAuthWidgetMgr对象，用于执行用户身份认证。
> **说明：**
> 每个UserAuthInstance只能进行一次认证，若需要再次进行认证则需重新获取UserAuthInstance。
**需要权限**：ohos.permission.SUPPORT_USER_AUTH
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**系统接口**: 此接口为系统接口。
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------ | ---- | -------------------- |
| version | number | 是 | 表示认证组件的版本。 |
**返回值：**
| 类型 | 说明 |
| ----------------------------------------- | ------------ |
| [UserAuthWidgetMgr](#userauthwidgetmgr10) | 认证器对象。 |
**错误码：**
以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。
| 错误码ID | 错误信息 |
| -------- | --------------------------------------- |
| 201 | Permission verification failed. |
| 202 | The caller is not a system application. |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**示例：**
```js
import userAuth from '@ohos.userIAM.userAuth';
let userAuthWidgetMgrVersion = 1;
try {
let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
console.log('get userAuthWidgetMgr instance success');
} catch (error) {
console.log('userAuth widgetMgr catch error: ' + JSON.stringify(error));
}
```
## IAuthWidgetCallback<sup>10+</sup>
认证组件通过该回调获取用户认证框架发送的命令。
### sendCommand<sup>10+</sup>
sendCommand(cmdData: string): void
回调函数，用于用户认证框架向组件发送命令。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core
**系统接口**: 此接口为系统接口。
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------ | ---- | ---------------------------------- |
| cmdData | string | 是 | 用户身份认证框架向组件发送的命令。 |
**示例：**
```js
import userAuth from '@ohos.userIAM.userAuth';
const userAuthWidgetMgrVersion = 1;
try {
let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
console.log('get userAuthWidgetMgr instance success');
userAuthWidgetMgr.on('command', {
sendCommand(cmdData) {
console.log('The cmdData is ' + cmdData);
}
})
console.log('subscribe authentication event success');
} catch (error) {
console.log('userAuth widgetMgr catch error: ' + JSON.stringify(error));
}
```
## AuthResultInfo<sup>9+</sup> ## AuthResultInfo<sup>9+</sup>
表示认证结果信息。 表示认证结果信息。
...@@ -669,14 +49,14 @@ try { ...@@ -669,14 +49,14 @@ try {
## AuthEventKey<sup>9+</sup> ## AuthEventKey<sup>9+</sup>
表示认证事件类型的关键字，作为[on](#ondeprecated)接口的的参数。 表示认证事件类型的关键字，作为[on](#on9)接口的的参数。
**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。 **系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。
| 取值类型 | 说明 | | 取值类型 | 说明 |
| ---------- | ----------------------- | | ---------- | ----------------------- |
| "result" | [on](#ondeprecated)接口第一个参数为"result"时，[callback](#callback9)回调返回认证的结果信息。 | | "result" | [on](#on9)接口第一个参数为"result"时，[callback](#callback9)回调返回认证的结果信息。 |
| "tip" | [on](#ondeprecated)接口第一个参数为"tip"时，[callback](#callback9)回调返回认证操作中的提示信息。 | | "tip" | [on](#on9)接口第一个参数为"tip"时，[callback](#callback9)回调返回认证操作中的提示信息。 |
## AuthEvent<sup>9+</sup> ## AuthEvent<sup>9+</sup>
...@@ -744,24 +124,24 @@ try { ...@@ -744,24 +124,24 @@ try {
} }
``` ```
## AuthInstance<sup>(deprecated)</sup> ## AuthInstance<sup>9+</sup>
执行用户认证的对象。 执行用户认证的对象。
> **说明：** > **说明：**
> 从 API version 9 开始支持，从 API version 10 开始废弃，请使用[UserAuthInstance](#userauthinstance10)替代。 > 从 API version 9 开始支持。
### on<sup>(deprecated)</sup> ### on<sup>9+</sup>
on : (name : AuthEventKey, callback : AuthEvent) => void on : (name : AuthEventKey, callback : AuthEvent) => void
订阅指定类型的用户认证事件。 订阅指定类型的用户认证事件。
> **说明：** > **说明：**
> 从 API version 9 开始支持，从 API version 10 开始废弃。 > 从 API version 9 开始支持。
> **说明：** > **说明：**
> 使用获取到的[AuthInstance](#authinstancedeprecated)对象调用该接口进行订阅。 > 使用获取到的[AuthInstance](#authinstance9)对象调用该接口进行订阅。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
...@@ -821,17 +201,17 @@ try { ...@@ -821,17 +201,17 @@ try {
} }
``` ```
### off<sup>(deprecated)</sup> ### off<sup>9+</sup>
off : (name : AuthEventKey) => void off : (name : AuthEventKey) => void
取消订阅特定类型的认证事件。 取消订阅特定类型的认证事件。
>**说明：** >**说明：**
>从 API version 9 开始支持，从 API version 10 开始废弃。 >从 API version 9 开始支持。
> **说明：** > **说明：**
> 需要使用已经成功订阅事件的[AuthInstance](#authinstancedeprecated)对象调用该接口进行取消订阅。 > 需要使用已经成功订阅事件的[AuthInstance](#authinstance9)对象调用该接口进行取消订阅。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
...@@ -887,17 +267,17 @@ try { ...@@ -887,17 +267,17 @@ try {
} }
``` ```
### start<sup>(deprecated)</sup> ### start<sup>9+</sup>
start : () => void start : () => void
开始认证。 开始认证。
> **说明：** > **说明：**
> 从 API version 9 开始支持，从 API version 10 开始废弃。 > 从 API version 9 开始支持。
> **说明：** > **说明：**
> 使用获取到的[AuthInstance](#authinstancedeprecated)对象调用该接口进行认证。 > 使用获取到的[AuthInstance](#authinstance9)对象调用该接口进行认证。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC **需要权限**：ohos.permission.ACCESS_BIOMETRIC
...@@ -939,17 +319,17 @@ try { ...@@ -939,17 +319,17 @@ try {
} }
``` ```
### cancel<sup>(deprecated)</sup> ### cancel<sup>9+</sup>
cancel : () => void cancel : () => void
取消认证。 取消认证。
> **说明：** > **说明：**
> 从 API version 9 开始支持，从 API version 10 开始废弃。 > 从 API version 9 开始支持。
> **说明：** > **说明：**
> 使用获取到的[AuthInstance](#authinstancedeprecated)对象调用该接口进行取消认证，此[AuthInstance](#authinstancedeprecated)需要是正在进行认证的对象。 > 使用获取到的[AuthInstance](#authinstance9)对象调用该接口进行取消认证，此[AuthInstance](#authinstance9)需要是正在进行认证的对象。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC **需要权限**：ohos.permission.ACCESS_BIOMETRIC
...@@ -983,14 +363,14 @@ try { ...@@ -983,14 +363,14 @@ try {
} }
``` ```
## userIAM_userAuth.getAuthInstance<sup>(deprecated)</sup> ## userIAM_userAuth.getAuthInstance<sup>9+</sup>
getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance
获取AuthInstance对象，用于执行用户身份认证。 获取AuthInstance对象，用于执行用户身份认证。
> **说明：** > **说明：**
> 从 API version 9 开始支持，从 API version 10 开始废弃，请使用[getUserAuthInstance](#getuserauthinstance10)替代。 > 从 API version 9 开始支持。
> **说明：** > **说明：**
> 每个AuthInstance只能进行一次认证，若需要再次进行认证则需重新获取AuthInstance。 > 每个AuthInstance只能进行一次认证，若需要再次进行认证则需重新获取AuthInstance。
...@@ -1009,7 +389,7 @@ getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel ...@@ -1009,7 +389,7 @@ getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel
| 类型 | 说明 | | 类型 | 说明 |
| --------------------------------------- | ------------ | | --------------------------------------- | ------------ |
| [AuthInstance](#authinstancedeprecated) | 认证器对象。 | | [AuthInstance](#authinstance9) | 认证器对象。 |
**错误码：** **错误码：**
...@@ -1100,7 +480,6 @@ try { ...@@ -1100,7 +480,6 @@ try {
| BUSY | 12500007 | 忙碌状态。 | | BUSY | 12500007 | 忙碌状态。 |
| LOCKED | 12500009 | 认证器已锁定。 | | LOCKED | 12500009 | 认证器已锁定。 |
| NOT_ENROLLED | 12500010 | 用户未录入认证信息。 | | NOT_ENROLLED | 12500010 | 用户未录入认证信息。 |
| CANCELED_FROM_WIDGET<sup>10+</sup> | 12500011 | 当前的认证操作被用户从组件取消。返回这个错误码，表示使用应用自定义认证。 |
## UserAuth<sup>(deprecated)</sup> ## UserAuth<sup>(deprecated)</sup>
...@@ -1113,7 +492,7 @@ constructor() ...@@ -1113,7 +492,7 @@ constructor()
创建认证器对象。 创建认证器对象。
> **说明：** > **说明：**
> 从 API version 8 开始支持，从 API version 9 开始废弃，请使用[getAuthInstance](#useriam_userauthgetauthinstancedeprecated)替代。 > 从 API version 8 开始支持，从 API version 9 开始废弃，请使用[getAuthInstance](#useriam_userauthgetauthinstance9)替代。
**系统能力**：SystemCapability.UserIAM.UserAuth.Core **系统能力**：SystemCapability.UserIAM.UserAuth.Core
...@@ -1207,7 +586,7 @@ auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLev ...@@ -1207,7 +586,7 @@ auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLev
执行用户认证，使用回调函数返回结果。 执行用户认证，使用回调函数返回结果。
> **说明：** > **说明：**
> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[start](#startdeprecated)代替。 > 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[start](#start9)代替。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC **需要权限**：ohos.permission.ACCESS_BIOMETRIC
...@@ -1258,7 +637,7 @@ cancelAuth(contextID : Uint8Array) : number ...@@ -1258,7 +637,7 @@ cancelAuth(contextID : Uint8Array) : number
表示通过contextID取消本次认证操作。 表示通过contextID取消本次认证操作。
> **说明：** > **说明：**
> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[cancel](#canceldeprecated)代替。 > 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[cancel](#cancel9)代替。
**需要权限**：ohos.permission.ACCESS_BIOMETRIC **需要权限**：ohos.permission.ACCESS_BIOMETRIC
...@@ -1461,7 +840,6 @@ auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLe ...@@ -1461,7 +840,6 @@ auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLe
| 名称 | 值 | 说明 | | 名称 | 值 | 说明 |
| ----------- | ---- | ---------- | | ----------- | ---- | ---------- |
| PIN<sup>10+</sup> | 1 | 口令认证。 |
| FACE | 2 | 人脸认证。 | | FACE | 2 | 人脸认证。 |
| FINGERPRINT | 4 | 指纹认证。 | | FINGERPRINT | 4 | 指纹认证。 |
......
zh-cn/application-dev/reference/errorcodes/errorcode-useriam.md
浏览文件 @ 0a00363b
...@@ -137,19 +137,6 @@ The type of credential has not been enrolled. ...@@ -137,19 +137,6 @@ The type of credential has not been enrolled.
检查是否录入该类型的凭据，如果没有录入，则需要成功录入该类型凭据后再调用相关接口。 检查是否录入该类型的凭据，如果没有录入，则需要成功录入该类型凭据后再调用相关接口。
## 12500011 认证被控件取消
**错误信息**
Indicates that this operation is canceled from widget's navigation button.
**可能原因**
当前的认证操作被用户从控件取消，返回这个错误码，标识使用应用自定义认证。例如用户点击使用自定义认证，返回到应用自定义认证流程。
**处理步骤**
重新调用认证接口，发起认证。
## 12700001 人脸录入过程中的操作失败 ## 12700001 人脸录入过程中的操作失败
**错误信息** **错误信息**
......
zh-cn/application-dev/security/permission-list.md
浏览文件 @ 0a00363b
...@@ -2590,18 +2590,6 @@ ...@@ -2590,18 +2590,6 @@
**起始版本**：10 **起始版本**：10
## ohos.permission.SUPPORT_USER_AUTH
允许应用与用户认证框架交互和注册扩展能力。
**权限级别**: system_basic
**授权方式**：system_grant
**ACL使能**：FALSE
**起始版本**：10
## ohos.permission.ACCESS_BUNDLE_DIR ## ohos.permission.ACCESS_BUNDLE_DIR
允许应用访问其他应用安装目录。 允许应用访问其他应用安装目录。
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或