Application permissions are used to prevent unauthorized access to sensitive data or critical functions. The [Ability Privilege Level (APL)](accesstoken-overview.md#application-apls) of an application can be **normal** (default), **system_basic**, or **system_core**. The [permission types](accesstoken-overview.md#permission-types) include **system_grant** and **user_grant**. For details about the permissions for applications, see the [Application Permission List](permission-list.md).
Application permissions are used to prevent unauthorized access to sensitive data or critical functions. The [Ability Privilege Level (APL)](accesstoken-overview.md#application-apls) of an application can be normal (default), system_basic, or system_core. The [permission types](accesstoken-overview.md#permission-types) include system_grant and user_grant. For details about the application permissions, see the [Application Permission List](permission-list.md).
This document describes the following operations:
...
...
@@ -17,18 +17,18 @@ The permissions required by an application must be declared one by one in the co
> **NOTE**
>
> If an application of the **normal** APL requires a permission of the **system_basic** or **system_core** level, you must also declare the permission in the [ACL](#declaring-the-acl).
> If an application of the normal APL requires a permission of the system_basic or system_core level, you must also declare the permission in the [ACL](#declaring-the-acl).
The following table describes the fields in the configuration file.
| reason | No | Reason for requesting the permission.<br>This parameter is mandatory when a user_grant permission is required.|
| usedScene | No | Application scenario of the permission.<br>This parameter is mandatory when a user_grant permission is required.|
| reason | No | Reason for applying for the permission. For details, see [Specifications for reason](#specifications-for-reason).<br>This parameter is mandatory when a user_grant permission is required. |
| usedScene | No | Application scenario of the permission.<br>This parameter is mandatory when a user_grant permission is required.|
| abilities | No | Abilities that require the permission. The value is an array.<br>**Applicable model**: stage|
| ability | No | Abilities that require the permission. The value is an array.<br>**Applicable model**: FA|
| when | No | Time when the permission is required. <br>Value:<br>- **inuse**: The permission is required only when the application is in use.<br>- **always**: The permission is required no matter whether the application is in use.|
| when | No | Time when the permission is required. <br>Value:<br>- **inuse**: The permission is required only when the application is in use.<br>- **always**: The permission is required no matter whether the application is in use.|
### Stage Model
...
...
@@ -98,11 +98,41 @@ If your application is developed based on the FA model, declare the required per
}
```
### Specifications for reason
The **reason** field (reason for applying for the permission) is mandatory when a user_grant permission is required. You need to configure each permission required by your application in the application configuration file.
When the user_grant permissions are authorized by the user in a dialog box, the [permission group](accesstoken-overview.md#permission group and sub-permissions) is displayed. For details about the permission groups, see [Application Permission List](permission-group-list.md).
The **reason** field must comply with the following specifications:
1. The reason must be clear and concise without redundant separators.
**Recommended sentence pattern**: Used for something/Used to do something/Used for doing something.
**Example**: Used for code scanning and photographing.
2. To ensure optimal user experience, the recommended length of **reason** is fewer than 72 characters (36 Chinese characters displayed in two lines on the UI) and the maximum length is 256 characters.
3. If **reason** is not set, the default reason will be used.
The reason for using a permission is presented in the permission authorization window and **Settings**. The path for **Settings** is **Settings** > **Privacy** > **Permission manager** > Permission details of an app.
1. If permissions in the **Phone**, **Messaging**, **Calendar**, **Contacts**, and **Call logs** permission groups are required, the content and usage of the permissions must be presented to the user.
**Sentence pattern**: Permissions A and B, used to ...
**Example**: Permission A and permission B, used to obtain the call status and mobile network information and for secure operation and statistics charging services.
2. If permissions in other permission groups are required, the reason for using the first permission requested in the permission group is presented to the user. The permissions are listed in the same sequence as they are sorted in permission groups of **Permission manager**.
**Example**: If Permission group A = {permission A, permission B, permission C} and {permission C, permission B} are requested, the reason for using permission B is presented to the user.
## Declaring the ACL
If an application of the **normal** APL requires permissions of the **system_basic** or **system_core** level, you must also declare the required permissions in the ACL.
If an application of the normal APL requires permissions of the system_basic or system_core level, you must also declare the required permissions in the ACL.
For example, if an application needs to access audio clips of a user and capture screenshots, it requires the **ohos.permission.WRITE_AUDIO** permission (of the **system_basic** level) and the **ohos.permission.CAPTURE_SCREEN** permission (of the **system_core** level). In this case, you need to add the required permissions to the **acls** field in the [HarmonyAppProvision configuration file](app-provision-structure.md).
For example, if an application needs to access audio clips of a user and capture screenshots, it requires the ohos.permission.WRITE_AUDIO permission (of the system_basic level) and the ohos.permission.CAPTURE_SCREEN permission (of the system_core level). In this case, you need to add the required permissions to the **acls** field in the [HarmonyAppProvision configuration file](app-provision-structure.md).
```json
{
...
...
@@ -118,14 +148,15 @@ For example, if an application needs to access audio clips of a user and capture
## Requesting User Authorization
User authorization is required when an application needs to access user privacy information (such as Location or Calendar information) or using system abilities (such as the camera ability to take photos or record videos). In this case, the application requires a **user_grant** permission. Before the application accesses the data or using the system ability, a verification is performed to check whether the user has granted the permission to the application. If the user has not granted the permission, a dialog box will be displayed to request user authorization. The following figure shows an example.
User authorization is required when an application needs to access user privacy information (such as Location or Calendar information) or using system abilities (such as the camera ability to take photos or record videos). In this case, the application requires a user_grant permission. Before the application accesses the data or using the system ability, a verification is performed to check whether the user has granted the permission to the application. If the user has not granted the permission, a dialog box will be displayed to request user authorization. The following figure shows an example.
**Figure 1** Requesting user authorization
**Figure 1** Requesting user authorization
> **NOTE**
>
> Each time before an API protected by a **user_grant** permission is called, **[requestPermissionsFromUser()](../reference/apis/js-apis-abilityAccessCtrl.md#requestpermissionsfromuser9)** will be called to request user authorization. After the permission is granted, the user may revoke the authorization in **Settings**. Therefore, the previous authorization status cannot be persistent.
> Each time before an API protected by a user_grant permission is called, **[requestPermissionsFromUser()](../reference/apis/js-apis-abilityAccessCtrl.md#requestpermissionsfromuser9)** will be called to request user authorization. After the permission is granted, the user may revoke the authorization in **Settings**. Therefore, the previous authorization status cannot be persistent.
### Stage Model
...
...
@@ -215,13 +246,14 @@ Example: Apply for the permission for an application to access the Calendar.
// The authorization is successful.
}).catch((err)=>{
console.error(`Failed to request permissions from user. Code is ${err.code}, message is ${err.message}`);
})
// ...
}
}
```
Sample code for requesting user authorization on the UI:
By default, the **user_grant** permissions must be dynamically authorized by the user through a dialog box. However, some pre-installed applications may require **user_grant** permissions, for example, the system camera application requires the **ohos.permission.MICROPHONE** permission. In this case, you can pre-authorize **user_grant** permissions for pre-installed applications in the [**install_list_permission.json**](https://gitee.com/openharmony/vendor_hihope/blob/master/rk3568/preinstall-config/install_list_permissions.json) file. The **install_list_permissions.json** file is in the **/system/etc/app/** directory on a device, and is loaded when the device starts. When the application is installed, the **user_grant** permissions in the file are granted.
The user_grant permissions can be pre-authorized in the [**install_list_permission.json** file](https://gitee.com/openharmony/vendor_hihope/blob/master/rk3568/preinstall-config/install_list_permissions.json) in the **/system/etc/app/** directory of the device. When the device starts, it loads the **install_list_permission.json** file. When the applications are installed, the user_grant permissions are authorized.
The **install_list_permissions.json** file contains the following fields:
-**bundleName**: bundle name of the application.
-**app_signature**: fingerprint information of the application. For details, see **Configuration in install_list_capability.json** in the [Application Privilege Configuration Guide](../../device-dev/subsystems/subsys-app-privilege-config-guide.md).
-**permissions**: The **name** field specifies the name of the **user_grant** permission to pre-authorize. The **userCancellable** field specifies whether the user can revoke the pre-authorization. The value **true** means the user can revoke the pre-authorization; the value **false** means the opposite.
> **NOTE**
>
> The **install_list_permissions.json** file is available only for preinstalled applications.
-**permissions**: The **name** field specifies the name of the user_grant permission to pre-authorize. The **userCancellable** field specifies whether the user can revoke the pre-authorization. The value **true** means the user can revoke the pre-authorization; the value **false** means the opposite.
@@ -4,7 +4,7 @@ Before applying for permissions for your application, understand [permission gro
The following lists the permission groups supported currently. For details about the permissions, see the [Application Permission List](permission-list.md).
## Location Information
## Location
- ohos.permission.LOCATION_IN_BACKGROUND
- ohos.permission.LOCATION
...
...
@@ -29,7 +29,7 @@ The following lists the permission groups supported currently. For details about
- ohos.permission.ACTIVITY_MOTION
## Body Sensor
## Body Sensors
- ohos.permission.READ_HEALTH_DATA
...
...
@@ -37,7 +37,7 @@ The following lists the permission groups supported currently. For details about
## cl.accessToken.1 Change of the Media and Files Permission Group
The original Media and File permission group contains the following permissions:
The original **Media and File** permission group contains the following permissions:
- ohos.permission.MEDIA_LOCATION
- ohos.permission.READ_MEDIA
- ohos.permission.WRITE_MEDIA
Changed the permission group as follows:
- Added **ohos.permission.MEDIA_LOCATION** to the Images and Video permission group.
- Added **ohos.permission.READ_MEDIA** and **ohos.permission.WRITE_MEDIA** to the Documents permission group.
- Moved **ohos.permission.MEDIA_LOCATION** to the **Images and Videos** permission group.
- Moved **ohos.permission.READ_MEDIA** and **ohos.permission.WRITE_MEDIA** to the **Documents** permission group.
**Change Impact**
The dialog box for requesting permissions is displayed by permission group.
The permission group rather than the permission is presented in the dialog box for requesting permissions.
- Before the change, if the three permissions are applied for an application, a dialog box for requesting the media and file permissions will be displayed only once.
- After the change, if the three permissions are applied for an application, a dialog box for requesting the image and video permissions and a dialog box for requesting the document permission will be displayed.
- Before the change, if the three permissions are applied for an application, a dialog box for requesting the media and file permissions will be displayed only once.
- After the change, if the three permissions are applied for an application, a dialog box for requesting the **Images and Videos** permissions and a dialog box for requesting the **Documents** permission will be displayed.
**Key API/Component Changes**
...
...
@@ -41,8 +40,8 @@ Permission groups after the change:
N/A
## cl.accessToken.2 Change of the Permission Requesting Modes of the Telephony, Messaging, and Call Logs Permission Groups
The permissions of the Telephony, Messaging, and Call Logs permission groups are available only to system applications. The three permission groups contain the following permissions:
## cl.accessToken.2 Change of the Permission Requesting Modes of the Phone, Messaging, and Call Logs Permission Groups
The **Phone**, **Messaging**, and **Call logs** permission groups contain the following permissions:
- ohos.permission.ANSWER_CALL
- ohos.permission.MANAGE_VOICEMAIL
- ohos.permission.READ_CELL_MESSAGES
...
...
@@ -55,12 +54,12 @@ The permissions of the Telephony, Messaging, and Call Logs permission groups are
- ohos.permission.WRITE_CALL_LOG
- ohos.permission.MEDIA_LOCATION
To enable third-party application developers to apply for these permissions, the method for requesting these permissions is changed to pre-authorization mode.
These permissions can be pre-authorized only.
**Change Impact**
The system applications can obtain these permissions only in pre-authorization mode, rather than requesting these permissions through a pop-up window, .
Instead of requesting these permissions through a pop-up window, the system applications can obtain the permissions only in pre-authorization mode.
**Key API/Component Changes**
...
...
@@ -68,4 +67,4 @@ N/A
**Adaptation Guide**
Apply for the preceding permissions in pre-authorization mode for system applications.
