@@ -8,7 +8,7 @@ In this example, the app requires the **ohos.permission.PERMISSION1** and **ohos
...
@@ -8,7 +8,7 @@ In this example, the app requires the **ohos.permission.PERMISSION1** and **ohos
- The level of **ohos.permission.PERMISSION1** is **normal**, and the authorization mode is **system_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**.
- The level of **ohos.permission.PERMISSION2** is **system_basic**, and the authorization mode is **user_grant**.
> **NOTICE**
> **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.
> In this scenario, the required permissions include a **user_grant** permission. You can check whether the caller has the required permission through permission verification.
>
>
...
@@ -24,87 +24,88 @@ The table below lists only the API used in this guide. For more information, see
...
@@ -24,87 +24,88 @@ The table below lists only the API used in this guide. For more information, see
## Declaring Permissions
## Declaring Permissions
Declare the permissions required by the app one by one in the project configuration file. The app cannot obtain the permissions that are not declared in the configuration file. The ability framework provides two models: Feature Ability (FA) model and Stage model. For more information, see [Ability Framework Overview](../ability/ability-brief.md).
Declare the permissions required by the app one by one in the project configuration file. The app cannot obtain the permissions that are not declared in the configuration file. The ability framework provides two models: Feature Ability (FA) model and stage model. For more information, see [Ability Framework Overview](../ability/ability-brief.md).
Note that the app bundle structure and configuration file vary with the ability framework model.
Note that the app bundle structure and configuration file vary with the ability framework model.
### FA Model
The following table describes the tags in the configuration file.
For the apps based on the FA model, declare the permissions in the **config.json** file.
| reason | Reason for requesting the permission. This field is mandatory for a user_grant 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.|
| 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.<br>**Applicable model**: FA |
| abilities | Abilities that use the permission. The value is an array.<br>**Applicable model**: stage |
| 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).|
| 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).|
### FA Model
For the apps based on the FA model, declare the required permissions in the **config.json** file.
**Example**
**Example**
```json
```json
{
{
"module":{
"module":{
"reqPermissions":[
"reqPermissions":[
{
{
"name":"ohos.permission.PERMISSION1",
"name":"ohos.permission.PERMISSION1",
"reason":"$string:reason",
"reason":"$string:reason",
"usedScene":{
"usedScene":{
"abilities":[
"ability":[
"FormAbility"
"FormAbility"
],
],
"when":"inuse"
"when":"inuse"
}
}
},
},
{
{
"name":"ohos.permission.PERMISSION2",
"name":"ohos.permission.PERMISSION2",
"reason":"$string:reason",
"reason":"$string:reason",
"usedScene":{
"usedScene":{
"abilities":[
"ability":[
"FormAbility"
"FormAbility"
],
],
"when":"always"
"when":"always"
}
}
}
}
],
]
}
}
}
}
```
```
### Stage Model
### Stage Model
For the apps based on the stage model, declare the permissions in the **module.json5** file.
For the apps based on the stage model, declare the required permissions in the **module.json5** file.
**Example**
**Example**
```json
```json
{
{
"module":{
"module":{
"requestPermissions":[
"requestPermissions":[
{
{
"name":"ohos.permission.PERMISSION1",
"name":"ohos.permission.PERMISSION1",
"reason":"$string:reason",
"reason":"$string:reason",
"usedScene":{
"usedScene":{
"abilities":[
"abilities":[
"FormAbility"
"FormAbility"
],
],
"when":"inuse"
"when":"inuse"
}
}
},
},
{
{
"name":"ohos.permission.PERMISSION2",
"name":"ohos.permission.PERMISSION2",
"reason":"$string:reason",
"reason":"$string:reason",
"usedScene":{
"usedScene":{
"abilities":[
"abilities":[
"FormAbility"
"FormAbility"
],
],
"when":"always"
"when":"always"
}
}
}
}
],
],
}
}
}
}
```
```
...
@@ -112,34 +113,17 @@ For the apps based on the stage model, declare the permissions in the **module.j
...
@@ -112,34 +113,17 @@ For the apps based on the stage model, declare the permissions in the **module.j
The permission level of **ohos.permission.PERMISSION2** is **system_basic**, which is higher than the app's APL. In this case, use the ACL.
The permission level of **ohos.permission.PERMISSION2** is **system_basic**, which is higher than the app's APL. In this case, use the ACL.
In addition to declaring all the permissions in the configuration file, you must declare the permissions whose levels are higher than the app's APL in the app's [profile](../quick-start/app-provision-structure.md). In this example, declare the permission under the **acls** field:
In addition to declaring all the permissions in the configuration file, you must declare the permissions whose levels are higher that the app's APL in the app's profile. For details about the fields in the profile, see [HarmonyAppProvision Configuration File](../quick-start/app-provision-structure.md).
In this example, declare the permission under the **acls** field:
@@ -151,7 +135,7 @@ Therefore, before allowing the app to call the API protected by the **ohos.permi
...
@@ -151,7 +135,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).
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.
> 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.
...
@@ -170,12 +154,12 @@ The procedure is as follows:
...
@@ -170,12 +154,12 @@ The procedure is as follows:
AccessTokenManager (ATM) implements unified app permission management based on access tokens on OpenHarmony.
AccessTokenManager (ATM) implements unified app permission management based on access tokens on OpenHarmony.
...
@@ -13,6 +13,18 @@ Without the required permissions, an app cannot access or perform operations on
...
@@ -13,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.
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 [Permission List](permission-list.md). Custom permissions are not allowed for apps currently.
## Permission Workflow
## 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.
Determine the permissions required for an app to access data or perform an operation. Declare the required permissions in the app installation package.
...
@@ -25,7 +37,7 @@ The figure below shows the permission workflow.
...
@@ -25,7 +37,7 @@ The figure below shows the permission workflow.


1. You can refer to the following figure to determine whether an app can apply for a permission.
1. You can refer to the figure below to determine whether an app can apply for a permission.


...
@@ -35,38 +47,6 @@ The figure below shows the permission workflow.
...
@@ -35,38 +47,6 @@ The figure below shows the permission workflow.
3. A low-level app can have a high-level permission by using the Access Control List (ACL). For details, see [ACL](#acl).
3. A low-level app can have a high-level permission by using the Access Control List (ACL). For details, see [ACL](#acl).
## When to Use
### 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](permission-list.md). Custom permissions are not allowed for apps currently.
### Example Scenarios
The following describes two common scenarios.
-**Video playback apps**
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)
## Permission Levels
## Permission Levels
To protect user privacy, ATM defines different permission levels based on the sensitivity of the data involved or the security threat of the ability.
To protect user privacy, ATM defines different permission levels based on the sensitivity of the data involved or the security threat of the ability.
...
@@ -85,7 +65,28 @@ The table below describes the APLs.
...
@@ -85,7 +65,28 @@ The table below describes the APLs.
By default, apps are of the normal APL.
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-overview.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.
The following is an example.
This example shows only the modification of the **apl** field. Set other fields based on service requirements. For details about the fields in the profile, see [HarmonyAppProvision Configuration File](../quick-start/app-provision-structure.md).
```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
### Levels of Permissions
...
@@ -101,13 +102,13 @@ The permissions open to apps vary with the permission level. The permission leve
...
@@ -101,13 +102,13 @@ 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 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**
-**system_core**
The system_core permission allows access to core resources of the operating system. These resources are the underlying core services of the system. If these resources are corrupted, the OS cannot run properly.
The system_core permission allows access to core resources of the operating system. These resources are the underlying core services of the system. If these resources are corrupted, the OS cannot run properly.
The permissions of this type are not open to any app currently.
The permissions of this type are not open to third-party apps currently.
## Permission Authorization Modes
## Permission Authorization Modes
...
@@ -177,8 +178,22 @@ If the permission required by an app has higher level than the app's APL, you ca
...
@@ -177,8 +178,22 @@ If the permission required by an app has higher level than the app's APL, you ca
In addition to the preceding [authorization processes](#authorization-processes), you must declare the ACL.
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.
In other words, in addition to declaring the required permissions in the app's configuration 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**
**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).
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-overview.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.
```json
{
"acls":{
"allowed-acls":[
"ohos.permission.PERMISSION"
]
},
}
```
For details about the fields in the profile, see [HarmonyAppProvision Configuration File](../quick-start/app-provision-structure.md).
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.
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.
...
@@ -20,7 +20,6 @@ For details about permission usage examples, see [Access Control Development](ac
...
@@ -20,7 +20,6 @@ For details about permission usage examples, see [Access Control Development](ac
| ohos.permission.REMOVE_CACHE_FILES | system_basic | system_grant | TRUE | Allows the cache of the specified app to be cleared. |
| ohos.permission.REMOVE_CACHE_FILES | system_basic | system_grant | TRUE | Allows the cache of the specified app to be cleared. |
| ohos.permission.REBOOT | system_basic | system_grant | TRUE | Allows an app to restart the device. |
| ohos.permission.REBOOT | system_basic | system_grant | TRUE | Allows an app to restart the device. |
| ohos.permission.RUNNING_LOCK | normal | system_grant | TRUE | Allows an app to obtain a running lock. |
| ohos.permission.RUNNING_LOCK | normal | system_grant | TRUE | Allows an app to obtain a running lock. |
| ohos.permission.ACCESS_BIOMETRIC | normal | system_grant | FALSE | Allows an app to use biometric recognition for identity authentication. |
| ohos.permission.SET_TIME | system_basic | system_grant | TRUE | Allows an app to set the system time. |
| ohos.permission.SET_TIME | system_basic | system_grant | TRUE | Allows an app to set the system time. |
| ohos.permission.SET_TIME_ZONE | system_basic | system_grant | TRUE | Allows an app to set the system time zone. |
| ohos.permission.SET_TIME_ZONE | system_basic | system_grant | TRUE | Allows an app to set the system time zone. |
| ohos.permission.DOWNLOAD_SESSION_MANAGER | system_core | system_grant | TRUE | Allows an app to manage the download sessions. |
| ohos.permission.DOWNLOAD_SESSION_MANAGER | system_core | system_grant | TRUE | Allows an app to manage the download sessions. |
...
@@ -97,7 +96,7 @@ For details about permission usage examples, see [Access Control Development](ac
...
@@ -97,7 +96,7 @@ For details about permission usage examples, see [Access Control Development](ac
| ohos.permission.EDM_MANAGE_DATETIME | normal | system_grant | FALSE | Allows the device administrator app to set the system time. |
| ohos.permission.EDM_MANAGE_DATETIME | normal | system_grant | FALSE | Allows the device administrator app to set the system time. |
| ohos.permission.NFC_TAG | normal | system_grant | FALSE | Allows an app to read NFC tag information. |
| ohos.permission.NFC_TAG | normal | system_grant | FALSE | Allows an app to read NFC tag information. |
| ohos.permission.NFC_CARD_EMULATION | normal | system_grant | FALSE | Allows an app to implement card emulation. |
| ohos.permission.NFC_CARD_EMULATION | normal | system_grant | FALSE | Allows an app to implement card emulation. |
| ohos.permission.PERMISSION_USED_STATS | system_core | system_grant | TRUE | Allows a system application to access the permission usage records. |
| ohos.permission.PERMISSION_USED_STATS | system_basic | system_grant | TRUE | Allows a system application to access the permission usage records. |
| ohos.permission.NOTIFICATION_AGENT_CONTROLLER | system_core | system_grant | TRUE | Allows an app to send agent-powered notifications. |
| ohos.permission.NOTIFICATION_AGENT_CONTROLLER | system_core | system_grant | TRUE | Allows an app to send agent-powered notifications. |
| ohos.permission.ANSWER_CALL | system_basic | user_grant | TRUE | Allows an app to answer incoming calls. |
| ohos.permission.ANSWER_CALL | system_basic | user_grant | TRUE | Allows an app to answer incoming calls. |
| ohos.permission.READ_CALENDAR | normal | user_grant | TRUE | Allows an app to read calendar data. |
| ohos.permission.READ_CALENDAR | normal | user_grant | TRUE | Allows an app to read calendar data. |
...
@@ -129,3 +128,4 @@ For details about permission usage examples, see [Access Control Development](ac
...
@@ -129,3 +128,4 @@ For details about permission usage examples, see [Access Control Development](ac
| ohos.permission.ACCESS_IDS | system_core | system_grant | TRUE | Allows an app to query the unique identifier of a device. |
| ohos.permission.ACCESS_IDS | system_core | system_grant | TRUE | Allows an app to query the unique identifier of a device. |
| ohos.permission.DUMP | system_core | system_grant | TRUE | Allows the basic system information and SA service information to be exported. |
| ohos.permission.DUMP | system_core | system_grant | TRUE | Allows the basic system information and SA service information to be exported. |
| ohos.permission.DISTRIBUTED_SOFTBUS_CENTER | system_basic | system_grant | FALSE | Allows networking between different devices. |
| ohos.permission.DISTRIBUTED_SOFTBUS_CENTER | system_basic | system_grant | FALSE | Allows networking between different devices. |
| ohos.permission.ACCESS_DLP_FILE | system_core | system_grant | TRUE | Allows configuration and management of the permissions on .dlp files. |