In this example, the app requires the **ohos.permission.PERMISSION1** and **ohos.permission.PERMISSION2** permissions to implement core functions.
- The ability privilege level (APL) of the app is normal.
- The level of **ohos.permission.PERMISSION1** is normal, and the authorization mode is system_grant.
- The level of **ohos.permission.PERMISSION2** is system_basic, and the authorization mode is user_grant.
- The level of **ohos.permission.PERMISSION1** is **normal**, and the authorization mode is **system_grant**.
- The level of **ohos.permission.PERMISSION2** is **system_basic**, and the authorization mode is **user_grant**.
> **Precautions**
> **Caution**
>
> In this scenario, the required permissions include a user_grant permission. You can check whether the caller has the required permission through permission verification.
>
...
...
@@ -35,7 +35,7 @@ Declare the permissions required by the app one by one in the **config.json** fi
| name | Name of the permission. |
| reason | Reason for requesting the permission. This field is mandatory for a user_grant permission.|
| usedScene | Scenario of the permission. This field is mandatory for a user_grant permission.|
| abilities | Abilities that use the permission. The value is an array. |
| ability | Abilities that use the permission. The value is an array. |
| when | Time when the permission is used. The value can be **inuse** (the permission can be used only in the foreground) or **always** (the permission can be used in foreground and background).|
**Example**
...
...
@@ -43,12 +43,12 @@ Declare the permissions required by the app one by one in the **config.json** fi
```json
{
"module":{
"requestPermissions":[
"reqPermissions":[
{
"name":"ohos.permission.PERMISSION1",
"reason":"$string:reason",
"usedScene":{
"abilities":[
"ability":[
"FormAbility"
],
"when":"inuse"
...
...
@@ -58,7 +58,7 @@ Declare the permissions required by the app one by one in the **config.json** fi
"name":"ohos.permission.PERMISSION2",
"reason":"$string:reason",
"usedScene":{
"abilities":[
"ability":[
"FormAbility"
],
"when":"always"
...
...
@@ -111,7 +111,7 @@ Therefore, before allowing the app to call the API protected by the **ohos.permi
If the verification result indicates that the app has the permission, the app can access the target API. Otherwise, the app needs to request user authorization and then proceeds based on the authorization result. For details, see [Access Control Overview](accesstoken-overview.md).
> **Precautions**
> **Caution**
>
> The permissions authorized by user are not permanent, because the user may revoke the authorization at any time. Therefore, even if the user has granted the requested permission to an app, the app's permission must be verified before the app calls an API protected by the permission.
...
...
@@ -124,21 +124,18 @@ The procedure is as follows:
3. Proceed based on the permission verification result.
AccessTokenManager (ATM) implements unified app permission management based on access tokens on OpenHarmony.
By default, apps can access limited system resources. However, in some cases, an app needs to access excess data (including personal data) and functions of the system or another app to implement extended functions. The system or apps must also share their data or functions through interfaces in an explicit manner. OpenHarmony uses app permissions to perform access control and prevent improper or malicious use of these data or functions.
...
...
@@ -14,6 +13,18 @@ Without the required permissions, an app cannot access or perform operations on
Currently, ATM verifies app permissions based on the token identity (Token ID). A token ID identifies an app. The ATM manages app permissions based on the app's token ID.
## Basic Principles for Permission Management
Observe the following principles for permission management:
- Provide clear description about the app functions and scenarios for each permission required by the app so that users can clearly know why and when these permissions are required. Do not induce or mislead users' authorization. The permissions on an app must comply with the description provided in the app.
- Use the principle of least authority for user permissions. Allow only necessary permissions for service functions.
- When an app is started for the first time, avoid frequently displaying dialog boxes to request permissions. Allow the app to apply for permissions only when it needs to use the corresponding service functions.
- If a user rejects to authorize a permission, the user can still use functions irrelevant to this permission and can register and access the app.
- Provide no more message if a user rejects the authorization required by a function. Provide onscreen instructions to direct the user to grant the permission in **Settings** if the user triggers this function again or needs to use this function.
- All the permissions granted to apps must come from the [Application Permission List](permission-list.md). Custom permissions are not allowed for apps currently.
## Permission Workflow
Determine the permissions required for an app to access data or perform an operation. Declare the required permissions in the app installation package.
...
...
@@ -26,37 +37,15 @@ The figure below shows the permission workflow.
## When to Use
1. You can refer to the following figure to determine whether an app can apply for a permission.
### Example Scenarios
The following describes two common scenarios.
1. See [Permission Levels](#permission-levels) for details about the mapping between the application Ability Privilege Level (APL) and permission level.
-**Video playback apps**
2. The permission authorization modes include user_grant (permission granted by the user) and system_grant (permission granted by the system). For details, see [Permission Authorization Modes](#permission-authorization-mode).
Video playback apps need to use multimedia functions and read and write media files stored on storage devices. Therefore, the apps must have at least the following permissions:
* ohos.permission.READ_MEDIA (allowing the apps to read external media files)
* ohos.permission.WRITE_MEDIA (allowing the apps to read and write external media files)
-**Photography apps**
Photography apps need to use the camera function. Before accessing the camera service, the apps must have the following permission:
ohos.permission.CAMERA (allowing the apps to use the camera to take photos and record videos)
### Basic Principles
Observe the following principles for permission management:
- Provide clear description about the app functions and scenarios for each permission required by the app so that users can clearly know why and when these permissions are required. Do not induce or mislead users' authorization. The permissions on an app must comply with the description provided in the app.
- Use the principle of least authority for user permissions. Allow only necessary permissions for service functions.
- When an app is started for the first time, avoid frequently displaying dialog boxes to request permissions. Allow the app to apply for permissions only when it needs to use the corresponding service functions.
- If a user rejects to authorize a permission, the user can still use functions irrelevant to this permission and can register and access the app.
- Provide no more message if a user rejects the authorization required by a function. Provide onscreen instructions to direct the user to grant the permission in **Settings** if the user triggers this function again or needs to use this function.
- All the permissions granted to apps must come from the Permission List. Custom permissions are not allowed for apps currently.
3. A low-level app can have a high-level permission by using the Access Control List (ACL). For details, see [ACL](#acl).
## Permission Levels
...
...
@@ -64,7 +53,7 @@ To protect user privacy, ATM defines different permission levels based on the se
### App APLs
The ability privilege level (APL) defines the priority of the app permission requested. Apps of different APLs can apply for permissions of different levels.
The APL defines the priority of the app permission requested. Apps of different APLs can apply for permissions of different levels.
The table below describes the APLs.
...
...
@@ -76,7 +65,28 @@ The table below describes the APLs.
By default, apps are of the normal APL.
For the app of the system_basic or system_core APL, declare the app APL in the **apl** field in the app's profile, and use the profile signing tool to generate a certificate when developing the app installation package. For details about the signing process, see [Hapsigner Guide](hapsigntool-guidelines.md).
For the app of the system_basic or system_core APL, declare the APL in the **apl** field of **bundle-info** in the app's profile when developing the application installation package.
Then, use the [hapsigner](hapsigntool-guidelines.md) tool to generate a certificate or use DevEco Studio to [have your app automatically signed](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-auto-configuring-signature-information-0000001271659465#section161281722111).
> **CAUTION**<br>The method of declaring the app's APL in its profile applies only to the application or service in debug phase. For a commercial app, apply for a release certificate and profile in the corresponding app market.
Example:
This example shows only the modification of the **apl** field. Set other fields based on service requirements.
```json
{
"bundle-info":{
"developer-id":"OpenHarmony",
"development-certificate":"Base64 string",
"distribution-certificate":"Base64 string",
"bundle-name":"com.OpenHarmony.app.test",
"apl":"system_basic",
"app-feature":"hos_normal_app"
},
}
```
### Levels of Permissions
...
...
@@ -92,7 +102,7 @@ The permissions open to apps vary with the permission level. The permission leve
The system_basic permission allows access to resources related to basic operating system services. The basic services are basic functions provided or preconfigured by the system, such as system setting and identity authentication. Access to these resources may have considerable risks to user privacy and other apps.
The permissions of this level are available only to the apps of the system_basic APL.
The permissions of this level are available only to apps of the system_basic or system_core APL.
-**system_core**
...
...
@@ -100,33 +110,6 @@ The permissions open to apps vary with the permission level. The permission leve
The permissions of this type are not open to any app currently.
### ACL
As described above, permission levels and app APLs are in one-to-one correspondence. In principle, **an app with a lower APL cannot apply for higher permissions by default**.
The Access Control List (ACL) makes low-level apps have high-level permissions.
**Example**
The APL of app A is normal. App A needs to have permission B (system_basic level) and permission C (normal level).
In this case, you can use the ACL to grant permission B to app A.
For details, see [Using the ACL](#using-the-acl).
For details about whether the ACL is enabled for a permission, see [Permission List](permission-list.md).
### Using the ACL
If the permission required by an app has higher level than the app's APL, you can use the ACL to grant the permissions required.
In addition to the preceding [authorization processes](#authorization-processes), you must declare the ACL.
In other words, in addition to declaring the required permissions in the **config.json** file, you must [declare the ACL](accesstoken-guidelines.md#declaring-the-acl) in the app's profile. The subsequent steps of authorization are the same.
**NOTICE**
Declare the target ACL in the **acls** field of the app's profile in the app installation package, and generate a certificate using the profile signing tool. For details about the signing process, see [Hapsigner Guide](hapsigntool-guidelines.md).
## Permission Authorization Modes
Permissions can be classified into the following types based on the authorization mode:
...
...
@@ -143,7 +126,7 @@ Permissions can be classified into the following types based on the authorizatio
This type of permissions must be declared in the app installation package and authorized by users dynamically during the running of the app. The app has the permission only after user authorization.
For example, in the [Permission List](permission-list.md), the permissions for the microphone and camera are user_grant. The list provides reasons for using the permissions.
For example, in the [Application Permission List](permission-list.md), the permissions for the microphone and camera are user_grant. The list provides reasons for using the permissions.
The user_grant permission list must also be presented on the details page of the app in the app store.
...
...
@@ -151,15 +134,15 @@ Permissions can be classified into the following types based on the authorizatio
The process for an app obtaining the required permissions varies depending on the permission authorization mode.
- For a system_grant permission, you need to [declare the permission](accesstoken-guidelines.md) in the **config.json** file. The permission will be pre-granted when the app is installed.
- For a system_grant permission, you need to [declare the permission](accesstoken-guidelines.md#declaring-permissions) in the configuration file. The permission will be pre-granted when the app is installed.
- For a user_grant permission, you need to [declare the permission](accesstoken-guidelines.md) in the **config.json** file, and a dialog box needs to be displayed to request user authorization during the running of the app.
- For a user_grant permission, you need to [declare the permission](accesstoken-guidelines.md#declaring-permissions) in the configuration file and trigger user authorization through a dialog box during the running of the app.
### Permission Authorization Process (user_grant)
The procedure is as follows:
1. In the **config.json** file, declare the permissions required by the app. For details, see [Access Control Development](accesstoken-guidelines.md).
1. In the configuration file, declare the permissions required by the app. For details, see [Access Control Development](accesstoken-guidelines.md).
2. Associate the object that requires the permissions in the app with the target permissions. In this way, the user knows the operations to be granted with the specified permissions.
...
...
@@ -170,7 +153,45 @@ The procedure is as follows:
**Precautions**
- Check the app's permission each time before the operation requiring the permission is performed.
- To check whether a user has granted specific permissions to your app, use the [verifyAccessToken](../reference/apis/js-apis-abilityAccessCtrl.md) method. This method returns [PERMISSION_GRANTED](../reference/apis/js-apis-abilityAccessCtrl.md) or [PERMISSION_DENIED](../reference/apis/js-apis-abilityAccessCtrl.md). For details about the sample code, see [Access Control Development](accesstoken-guidelines.md).
- Users must be able to understand and control the authorization of user_grant permissions. During the running process, the app requiring user authorization must proactively call the API to dynamically request the authorization. Then, the system displays a dialog box asking the user to grant the requested permission. The user will determine whether to grant the permission based on the running context of the app.
- The permission authorized is not permanent, because the user may revoke the authorization at any time. Therefore, even if the user has granted the requested permission to the app, the app must check for the permission before calling the API controlled by this permission.
## ACL
As described above, permission levels and app APLs are in one-to-one correspondence. In principle, **an app with a lower APL cannot apply for higher permissions by default**.
The ACL makes low-level apps have high-level permissions.
**Example**
The APL of app A is normal. App A needs to have permission B (system_basic level) and permission C (normal level).
In this case, you can use the ACL to grant permission B to app A.
For details, see [Using the ACL](#using-the-acl).
For details about whether a permission can be enabled through the ACL, see the [Application Permission List](permission-list.md).
### Using the ACL
If the permission required by an app has higher level than the app's APL, you can use the ACL to grant the permissions required.
In addition to the preceding [authorization processes](#authorization-processes), you must declare the ACL.
In other words, in addition to declaring the required permissions in the app's configuration file, you must declare the permissions higher than the app's APL [using the ACL](accesstoken-guidelines.md#declaring-the-acl) in the app's profile. The subsequent steps of authorization are the same.
**NOTICE**
When developing an app installation package, you must declare the allowed ACLs in the **acls** field in the app's profile. Then, use the [hapsigner](hapsigntool-guidelines.md) tool to generate a certificate.
> **CAUTION**<br>The method of declaring the app's APL in its profile applies only to the application or service in debug phase. For a commercial app, apply for a release certificate and profile in the corresponding app market.
On the basis of the [principles for app permission management](accesstoken-overview.md#basic-principles), apply for permissions for an app by following the procedure illustrated in the figure below.
Before applying for required permissions, read and understand the [permission workflow](accesstoken-overview.md#permission-workflow). Then, determine whether the app can apply for the target permissions based on the table below.
1. For details about the mapping between the app's ability privilege level (APL) and permission level, see [Permission Levels](accesstoken-overview.md#permission-levels).
2. Permissions can be authorized by the user (user_grant) or the system (system_grant). For details, see [Permission Authorization Modes](accesstoken-overview.md#permission-authorization-modes).
3. In principle, an app with a lower APL cannot apply for higher permissions by default. The Access Control List (ACL) makes low-level apps have high-level permissions. For details, see [ACL](accesstoken-overview.md#acl).
The following lists the permissions defined by the system. For details about permission usage examples, see [Access Control Development](accesstoken-guidelines.md).
For details about permission usage examples, see [Access Control (Permission) Development](accesstoken-guidelines.md).
@@ -83,7 +77,6 @@ The following lists the permissions defined by the system. For details about per
| ohos.permission.SET_ABILITY_CONTROLLER | system_basic | system_grant | TRUE | Allows an app to set the start and stop of an ability. |
| ohos.permission.USE_USER_IDM | system_basic | system_grant | FALSE | Allows an app to access the system identity credential information. |
| ohos.permission.MANAGE_USER_IDM | system_basic | system_grant | FALSE | Allows an app to use the system identity credential management capability to enroll, modify, and delete PINs, face images, and fingerprints.|
| ohos.permission.ACCESS_BIOMETRIC | normal | system_grant | TRUE | Allows an app to use biometric recognition for identity authentication. |
| ohos.permission.ACCESS_USER_AUTH_INTERNAL | system_basic | system_grant | FALSE | Allows an app to use the system identity authentication capability to authenticate or identify users. |
| ohos.permission.ACCESS_PIN_AUTH | system_basic | system_grant | FALSE | Allows a system app to call the PIN input APIs to present a password input dialog box for users.|
| ohos.permission.GET_RUNNING_INFO | system_basic | system_grant | TRUE | Allows an app to obtain running status information. |
