In this example, the app requires the **ohos.permission.PERMISSION1** and **ohos.permission.PERMISSION2** permissions to implement core functions.
The [Ability Privilege Level (APL)](accesstoken-overview.md#app-apls) of an application can be **normal**, **system_basic**, or **system_core**. The default APL is **normal**. The [permission types](accesstoken-overview.md#permission-types) include **system_grant** and **user_grant**. For details about the permissions for apps, see the [App Permission List](permission-list.md).
- The ability privilege level (APL) of the app is **normal**.
This document describes the following operations:
- 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**.
> **CAUTION**
-[Declaring Permissions in the Configuration File](#declaring-permissions-in-the-configuration-file)
>
-[Declaring Permissions in the ACL](#declaring-permissions-in-the-acl)
> In this scenario, the required permissions include a **user_grant** permission. You can check whether the caller has the required permission through permission verification.
-[Requesting User Authorization](#requesting-user-authorization)
> If the permission verification result indicates that the app has not obtained that permission, dynamic user authorization is required.
## Available APIs
## Declaring Permissions in the Configuration File
The table below lists only the API used in this guide. For more information, see [Ability Access control](../reference/apis/js-apis-ability-context.md).
During the development, you need to declare the permissions required by your application one by one in the project configuration file. The application cannot obtain the permissions that are not declared in the configuration file. OpenHarmony provides two application models: FA model and stage model. For more information, see Application Models. The application bundle and configuration file vary with the application model.
| API | Description |
> **NOTE**<br>The default APL of an application is **normal**. When an application needs the **system_basic** or **system_core** APL, you must declare the permission in the configuration file and the [Access Control List (ACL)](#declaring-permissions-in-the-acl).
| requestPermissionsFromUser(permissions: Array<string>, requestCallback: AsyncCallback<PermissionRequestResult>) : void; | Requests permissions from the user by displaying a dialog box. This API uses an asynchronous callback to return the result.|
## Declaring Permissions
The following table describes the fields in the configuration file.
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).
| reason | No | Reason for requesting the permission.<br>This field is mandatory when the requested permission needs user authorization (user_grant).|
| usedScene | No | Application scenario of the permission.<br>This field is mandatory when the requested permission needs user authorization (user_grant).|
| 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 used. <br>Value:<br>- **inuse**: The permission applies only to a foreground application.<br>- **always**: The permission applies to both the foreground and background applications.|
Note that the app bundle structure and configuration file vary with the ability framework model.
### Stage Model
The following table describes the tags in the configuration file.
| 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.|
| 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).|
### FA Model
For the apps based on the FA model, declare the required permissions in the **config.json** file.
**Example**
If the application is based on the stage model, declare the permissions in [**module.json5**](../quick-start/module-configuration-file.md).
```json
```json
{
{
"module":{
"module":{
"reqPermissions":[
//...
"requestPermissions":[
{
{
"name":"ohos.permission.PERMISSION1",
"name":"ohos.permission.PERMISSION1",
"reason":"$string:reason",
"reason":"$string:reason",
"usedScene":{
"usedScene":{
"ability":[
"abilities":[
"FormAbility"
"FormAbility"
],
],
"when":"inuse"
"when":"inuse"
...
@@ -63,7 +51,7 @@ For the apps based on the FA model, declare the required permissions in the **co
...
@@ -63,7 +51,7 @@ For the apps based on the FA model, declare the required permissions in the **co
"name":"ohos.permission.PERMISSION2",
"name":"ohos.permission.PERMISSION2",
"reason":"$string:reason",
"reason":"$string:reason",
"usedScene":{
"usedScene":{
"ability":[
"abilities":[
"FormAbility"
"FormAbility"
],
],
"when":"always"
"when":"always"
...
@@ -74,21 +62,20 @@ For the apps based on the FA model, declare the required permissions in the **co
...
@@ -74,21 +62,20 @@ For the apps based on the FA model, declare the required permissions in the **co
}
}
```
```
### Stage Model
### FA Model
For the apps based on the stage model, declare the required permissions in the **module.json5** file.
**Example**
If the application is based on the FA model, declare the required permissions in **config.json**.
```json
```json
{
{
"module":{
"module":{
"requestPermissions":[
//...
"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"
...
@@ -98,7 +85,7 @@ For the apps based on the stage model, declare the required permissions in the *
...
@@ -98,7 +85,7 @@ For the apps based on the stage model, declare the required permissions in the *
"name":"ohos.permission.PERMISSION2",
"name":"ohos.permission.PERMISSION2",
"reason":"$string:reason",
"reason":"$string:reason",
"usedScene":{
"usedScene":{
"abilities":[
"ability":[
"FormAbility"
"FormAbility"
],
],
"when":"always"
"when":"always"
...
@@ -109,60 +96,152 @@ For the apps based on the stage model, declare the required permissions in the *
...
@@ -109,60 +96,152 @@ For the apps based on the stage model, declare the required permissions in the *
}
}
```
```
## Declaring the ACL
## Declaring Permissions in 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 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).
If an application of the **normal** level requires permissions corresponding to the **system_basic** or **system_core** level, you need to declare the required permissions in the ACL.
For example, declare the required permission in the **acls** field:
For example, if an application needs to access audio files 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 related permissions to the **acl** field in the [HarmonyAppProvision configuration file](app-provision-structure.md).
```json
```json
{
{
"acls":{
//...
"allowed-acls":[
"acls":{
"ohos.permission.PERMISSION2"
"allowed-acls":[
]
"ohos.permission.WRITE_AUDIO",
}
"ohos.permission.CAPTURE_SCREEN"
]
}
}
}
```
```
## Applying for the user_grant Permission
## Requesting User Authorization
After the permissions are declared, the system grants the system_grant permission during the installation of the app. The user_grant permission must be authorized by the user.
Therefore, before allowing the app to call the API protected by the **ohos.permission.PERMISSION2** permission, the system needs to verify whether the app has the permission to do so.
If an application needs to access user privacy information or use system abilities, for example, accessing location or calendar information or using the camera to take photos or record videos, it must request the permission from users. A permission verification is performed first to determine whether the current invoker has the corresponding permission. If the application has not obtained that permission, a dialog box will be displayed to request user authorization. The following figure shows an example.
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).
> **NOTE**<br>Each time before an API protected by a permission is accessed, the **requestPermissionsFromUser()** API will be called to request user authorization. After a permission is dynamically granted, the user may revoke the permission. Therefore, the previously granted authorization status cannot be persistent.
> **CAUTION**
### Stage Model
>
> The permission authorized by a user is not permanent, because the user may revoke the authorization at any time. Each time before the API protected by the permission is called, call **requestPermissionsFromUser()** to request the permission.
## Example
Example: Request the permission to read calendar information for an app.
1. Apply for the **ohos.permission.READ_CALENDAR** permission. For details, see [Declaring Permissions in the Configuration File](#declaring-permissions-in-the-configuration-file).
2. Call **requestPermissionsFromUser()** in the **onWindowStageCreate()** callback of the UIAbility to dynamically apply for the permission, or request user authorization on the UI based on service requirements. The return value of **requestPermissionsFromUser()** indicates whether the application has the target permission. If yes, the target API can be called normally.
console.error(`[requestPermissions] Failed to start request permissions. Error: ${JSON.stringify(err)}`);
})
}
// Page display.
build(){
// ...
}
}
```
The procedure for requesting user authorization is as follows:
### FA Model
1. Obtain the ability context.
Call [requestPermissionsFromUser()](../reference/apis/js-apis-inner-app-context.md#contextrequestpermissionsfromuser7) to request user authorization.
2. Call **requestPermissionsFromUser()** to request user authorization. The API determines whether to display a dialog box to request user authorization based on whether the app has the permission.
3. Check whether the app has the permission based on the return value. If the app has the permission, the API can be invoked.
console.error('Failed to start ability',err.code);
console.error('Failed to start ability',err.code);
});
});
}
}
```
## Pre-Authorizing user_grant Permissions
By default, the **user_grant** permissions must be dynamically authorized by the user through a dialog box. However, for pre-installed apps, you can pre-authroize the permissions, for example, the **ohos.permission.MICROPHONE** permission, in the [**install_list_permission.json**](https://gitee.com/openharmony/vendor_hihope/blob/master/rk3568/preinstall-config/install_list_permissions.json) file to prevent the user authorization dialog box from being displayed. The **install_list_permissions.json** file is in the **/system/etc/app/** directory on a device. When the device is started, the **install_list_permissions.json** file is loaded. When the application is installed, the **user_grant** permissions in the file are granted. 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 [Application Privilege Configuration Guide](../../device-dev/subsystems/subsys-app-privilege-config-guide.md#configuration-in-install-list-capabilityjson).
-**permissions**: **name** specifies the name of the **user_grant** permission to pre-authorize. **userCancellable** specifies whether the user can revoke the pre-authorization. The value **true** means the user can revoke the pre-authorization; the vaue **false** means the opposite.
> **NOTE**<br>This file is available only for preinstalled applications.
OpenHarmony AccessTokenManager (ATM) implements unified app permission management based on access tokens.
OpenHarmony AccessTokenManager (ATM) implements unified app permission management based on access tokens.
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 explicitly share their data or functions through APIs. OpenHarmony uses app permissions to perform access control and prevent improper or malicious use of these data or functions.
By default, apps can access limited system resources. However, to provide extended features, an app may need to access excess data (including personal data) and functions of the system or another app. The system or apps must also explicitly share their data or functions through APIs. OpenHarmony uses app permissions to perform access control and prevent improper or malicious use of these data or functions.
App permissions are used to protect the following objects:
App permissions are used to protect the following objects:
- Data: personal data (such as photos, contacts, calendar, and location), device data (such as device ID, camera, and microphone), and app data.
- Data: personal data (such as photos, contacts, calendar, and location), device data (such as device ID, camera, and microphone), and app data.
- Functions: device functions (such as making calls, sending SMS messages, and connecting to the Internet) and app functions (such as displaying windows and creating shortcuts).
- Functions: device functions (such as making calls, sending SMS messages, and connecting to the Internet) and app functions (such as displaying windows and creating shortcuts).
Without the required permissions, an app cannot access or perform operations on the target object. Permissions must be clearly defined for apps. With well-defined app permissions, the system can standardize the behavior of apps and protect user privacy. Before an app accesses the target object, the target object verifies the app's permissions and denies the access if the app does not have required permissions.
Without the required permissions, an app cannot access or perform operations on the target object. Permissions must be clearly defined for apps. With well-defined app permissions, the system can standardize app behavior and protect user privacy. Before an app accesses the target object, the target object verifies the app's permissions and denies the access if the app does not have required permissions.
Currently, ATM verifies app permissions based on the token identity (token ID). A token ID identifies an app. 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. ATM manages app permissions based on the app's token ID.
...
@@ -17,13 +17,13 @@ Currently, ATM verifies app permissions based on the token identity (token ID).
...
@@ -17,13 +17,13 @@ Currently, ATM verifies app permissions based on the token identity (token ID).
Observe the following 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.
- Provide clear description about the functions and scenarios for each permission required by the app so that users can clearly know why and when these permissions are needed. 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.
- 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 multiple permissions. Allow the app to apply for the permission only when it needs to use the corresponding service function.
- When an app is started for the first time, avoid frequently displaying dialog boxes to request multiple permissions. Allow the app to apply for the permission only when it needs to use the corresponding service function.
- If a user rejects to grant a permission, the user can still use functions irrelevant to this permission and can register and access the app.
- If a user rejects to grant 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.
- 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 [App Permission List](permission-list.md). Custom permissions are not allowed for apps currently.
- All the permissions granted to apps must come from the [App Permission List](permission-list.md). Custom permissions are not allowed currently.
## Permission Workflows
## Permission Workflows
...
@@ -50,7 +50,9 @@ The figure below illustrates the process.
...
@@ -50,7 +50,9 @@ The figure below illustrates the process.
3. A low-APL app can have a high-level permission by using the Access Control List (ACL). For details, see [ACL](#acl).
3. A low-APL app can have a high-level permission by using the Access Control List (ACL). For details, see [ACL](#acl).
### Permission Verification
### Permission Verification
To protect sensitive data and eliminate security threads on core abilities, you can use the permissions in the [App Permission List](permission-list.md) to protect the related API from unauthorized calling. Each time before the API is called, a permission verification is performed to check whether the caller has the required permission. The API can be called only after the permission verification is successful.
To protect sensitive data and eliminate security threads on core abilities, you can use the permissions in the [App Permission List](permission-list.md) to protect an API from unauthorized calling. Each time before the API is called, a permission verification is performed to check whether the caller has the required permission.
The API can be called only after the permission verification is successful.
The figure below shows the permission verification process.
The figure below shows the permission verification process.
...
@@ -58,7 +60,7 @@ The figure below shows the permission verification process.
...
@@ -58,7 +60,7 @@ The figure below shows the permission verification process.
1: An app permission can be used to control the access to an API that has sensitive data involved or security threats on the core abilities.
1: An app permission can be used to control the access to an API that has sensitive data involved or security threats on the core abilities.
2: Select the permission from the [App Permission List](permission-list.md). For example, if contact information is involved in an API provided by an app, you can use the contact-related permissions to protect the API.
2: The API can be protected by a permission in the [ACL](#acl). For example, if contact information is involved in an API provided by an app, you can use the contact-related permissions to protect the API.
3: Use **verifyAccessToken()** to check whether the caller has the required permission. For details, see [Permission Verification Guide](permission-verify-guidelines.md).
3: Use **verifyAccessToken()** to check whether the caller has the required permission. For details, see [Permission Verification Guide](permission-verify-guidelines.md).
...
@@ -88,7 +90,7 @@ Then, use the [hapsigner](hapsigntool-overview.md) tool to generate a certificat
...
@@ -88,7 +90,7 @@ Then, use the [hapsigner](hapsigntool-overview.md) tool to generate a certificat
The following is an example.
The following is an example.
This example shows only the modification of the **apl** field. Set other fields based on your requirements. For details about the fields in the profile, see [HarmonyAppProvision Configuration File](../quick-start/app-provision-structure.md).
This example shows only the modification of the **apl** field. Set other fields based on your requirements. For details about the fields in the profile, see [HarmonyAppProvision Configuration File](app-provision-structure.md).
```json
```json
{
{
...
@@ -123,7 +125,7 @@ The permissions open to apps vary with the permission level. The permission leve
...
@@ -123,7 +125,7 @@ The permissions open to apps vary with the permission level. The permission leve
The system_core permission allows access to core resources of the OS. These resources are 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 OS. These resources are underlying core services of the system. If these resources are corrupted, the OS cannot run properly.
The system_core permissions are not open to third-party apps currently.
The system_core permissions are not open to third-party apps.
## Permission Types
## Permission Types
...
@@ -131,19 +133,19 @@ Permissions can be classified into the following types based on the authorizatio
...
@@ -131,19 +133,19 @@ Permissions can be classified into the following types based on the authorizatio
-**system_grant**
-**system_grant**
The app permissions are authorized by the system. This type of apps cannot access user or device sensitive information. The allowed operations have minor impact on the system or other apps.
The app permissions are authorized by the system. Apps granted with this type of permission cannot access user or device sensitive information, and the operations allowed for them have minor impact on the system or other apps.
For a system_grant app, the system automatically grants the required permissions to the app when the app is installed. The system_grant permission list must be presented to users on the details page of the app in the app store.
For a system_grant app, the system automatically grants the required permissions to the app when the app is installed. The system_grant permission list must be presented to users on the details page of the app in the app market.
-**user_grant**
-**user_grant**
The app permissions must be authorized by users. This type of apps may access user or device sensitive information. The allowed operations may have a critical impact on the system or other apps.
The app permissions must be authorized by users. Apps granted with this type of permissions may access user or device sensitive information, and the operations allowed for them may have a critical impact on the system or other apps.
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.
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 [App Permission List](permission-list.md), the permissions for microphones and cameras are user_grant. The list provides reasons for using the permissions.
For example, as described in the [App Permission List](permission-list.md), the permissions for microphones and cameras 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.
The user_grant permission list must also be presented on the details page of the app in the app market.
### Authorization Processes
### Authorization Processes
...
@@ -173,7 +175,7 @@ The procedure is as follows:
...
@@ -173,7 +175,7 @@ The procedure is as follows:
**Precautions**
**Precautions**
- Check the app's permission each time before the operation requiring the permission is performed.
- 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 an 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).
- To check whether a user has granted specific permissions to an app, use the [verifyAccessToken](../reference/apis/js-apis-abilityAccessCtrl.md)API. This API 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 an API to dynamically request the authorization. Then, the system displays a dialog box asking the user to grant the permission. The user will determine whether to grant the permission based on the running context of the app.
- 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 an API to dynamically request the authorization. Then, the system displays a dialog box asking the user to grant the 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.
- 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.
...
@@ -190,15 +192,15 @@ The APL of app A is **normal**. App A needs to have permission B (system_basic l
...
@@ -190,15 +192,15 @@ The APL of app A is **normal**. App A needs to have permission B (system_basic l
In this case, you can use the ACL to grant permission B to app A.
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, see [Using the ACL](#using-the-acl).
For details about whether a permission can be enabled through the ACL, see the [App Permission List](permission-list.md).
For details about whether a permission can be enabled through the ACL, see [App Permission List](permission-list.md).
### Using the ACL
### 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 permission required.
If the permission required by an app has a higher level than the app's APL, you can use the ACL to grant the permission required.
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.
That is, you need to declare the required permissions in the app's configuration file, and [declare the ACL](accesstoken-guidelines.md#declaring-the-acl) in the app's profile. The subsequent steps of authorization are the same.
That is, you need to declare the required permissions in the app's configuration file, and [declare the ACL](accesstoken-guidelines.md#declaring-permissions-in-the-acl) in the app's profile. The subsequent steps of authorization are the same.
**NOTICE**
**NOTICE**
...
@@ -216,4 +218,4 @@ When developing an app installation package, you must declare the ACL in the **a
...
@@ -216,4 +218,4 @@ When developing an app installation package, you must declare the ACL in the **a
}
}
```
```
For details about the fields in the profile, see [HarmonyAppProvision Configuration File](../quick-start/app-provision-structure.md).
For details about the fields in the profile, see [HarmonyAppProvision Configuration File](app-provision-structure.md).
| version-code | Version number of the **HarmonyAppProvision** file format. The value is a positive integer containing 32 or less digits.| Number | Yes| No |
| version-code | Version number of the **HarmonyAppProvision** file format. The value is a positive integer containing 32 or less digits.| Number | Yes| No |
| version-name | Description of the version number. It is recommended that the value consist of three segments, for example, **A.B.C**. | String | Yes| No|
| version-name | Description of the version number. It is recommended that the value consist of three segments, for example, **A.B.C**. | String | Yes| No|
| uuid | Unique ID of the **HarmonyAppProvision** file. | String | Yes| No|
| uuid | Unique ID of the **HarmonyAppProvision** file. | String | Yes| No|
| type | Type of the **HarmonyAppProvision** file. The value can be **debug** (for application debugging) or **release** (for application release). The recommended value is **debug**.| String | Yes| No|
| type | Type of the **HarmonyAppProvision** file. The value can be **debug** (for application debugging) or **release** (for application release). The recommended value is **debug**.| String | Yes| No|
| issuer | Issuer of the **HarmonyAppProvision** file. | String | Yes| No|
| issuer | Issuer of the **HarmonyAppProvision** file. | String | Yes| No|
| validity | Validity period of the **HarmonyAppProvision** file. For details, see [Internal Structure of the validity Object](#internal-structure-of-the-validity-object). | Object | Yes | No |
| validity | Validity period of the **HarmonyAppProvision** file. For details, see [Internal Structure of the validity Object](#internal-structure-of-the-validity-object). | Object | Yes | No |
| bundle-info | Information about the application bundle and developer. For details, see [Internal Structure of the bundle-info Object](#internal-structure-of-the-bundle-info-object). | Object | Yes| No |
| bundle-info | Information about the application bundle and developer. For details, see [Internal Structure of the bundle-info Object](#internal-structure-of-the-bundle-info-object). | Object | Yes | No |
| acls | Information about the Access Control Lists (ACLs). For details, see [Internal Structure of the acls Object](#internal-structure-of-the-acls-object). | Object | No| No |
| acls | Information about the Access Control Lists (ACLs). For details, see [Internal Structure of the acls Object](#internal-structure-of-the-acls-object). | Object | No | Yes |
| permissions | Permissions required for your application. For details, see [Internal Structure of the permissions Object](#internal-structure-of-the-permissions-object). | Object | No| No |
| permissions | Permissions required for your application. For details, see [Internal Structure of the permissions Object](#internal-structure-of-the-permissions-object). | Object | No | Yes |
| debug-info | Additional information for application debugging. For details, see [Internal Structure of the debug-info Object](#internal-structure-of-the-debug-info-object). | Object | No| No |
| debug-info | Additional information for application debugging. For details, see [Internal Structure of the debug-info Object](#internal-structure-of-the-debug-info-object). | Object | No | Yes |
| app-privilege-capabilities | Privilege information required by the application bundle. For details, see the [Application Privilege Configuration Guide](../../device-dev/subsystems/subsys-app-privilege-config-guide.md). | String array| No | Yes |
An example of the **HarmonyAppProvision** file is as follows:
An example of the **HarmonyAppProvision** file is as follows:
```json
```json
...
@@ -47,6 +47,7 @@ An example of the **HarmonyAppProvision** file is as follows:
...
@@ -47,6 +47,7 @@ An example of the **HarmonyAppProvision** file is as follows:
| developer-id | Unique ID of the developer.| String | Yes| No |
| developer-id | Unique ID of the developer.| String | Yes| No |
| development-certificate | Information about the [debug certificate](../security/hapsigntool-guidelines.md).| Number | Yes if **type** is set to **debug** and no otherwise | No |
| development-certificate | Information about the [debug certificate](hapsigntool-guidelines.md).| Number | Yes if **type** is set to **debug** and no otherwise | No |
| distribution-certificate | Information about the [release certificate](../security/hapsigntool-guidelines.md).| Number | Yes if **type** is set to **release** and no otherwise| No |
| distribution-certificate | Information about the [release certificate](hapsigntool-guidelines.md).| Number | Yes if **type** is set to **release** and no otherwise| No |
| bundle-name | Bundle name of the application.| String | Yes| No |
| bundle-name | Bundle name of the application.| String | Yes| No |
| apl | [Ability privilege level (APL)](../security/accesstoken-overview.md) of your application. The value can be **normal**, **system_basic**, or **system_core**.| String | Yes| No |
| apl | [Ability privilege level (APL)](accesstoken-overview.md) of your application. The value can be **normal**, **system_basic**, or **system_core**.| String | Yes | No |
| app-feature | Type of your application. The value can be **hos_system_app** (system application) or **hos_normal_app** (non-system application).| String | Yes| No |
| app-feature | Type of your application. The value can be **hos_system_app** (system application) or **hos_normal_app** (normal application). Only system applications are allowed to call system APIs. If a normal application calls a system API, the call cannot be successful or the application may run abnormally.| String | Yes | No |
### Internal Structure of the acls Object
### Internal Structure of the acls Object
The **acls** object contains the [ACLs](../security/accesstoken-overview.md) configured for your application. It should be noted that you still need to fill the ACL information in the **reqPermissions** attribute in the [config.json](package-structure.md) file.
The **acls** object contains the [ACL](accesstoken-overview.md) configured for your application. It should be noted that you still need to add the ACL information to the **requestPermissions** attribute in the application configuration file.
**Table 4** Internal structure of the acls object
| Name | Description | Data Type| Mandatory| Initial Value Allowed|
| Name | Description | Data Type| Mandatory| Initial Value Allowed|
| allowed-acls | [ACLs](../security/accesstoken-overview.md) configured for your application.| String array | No| No |
| allowed-acls | [ACLs](../security/accesstoken-overview.md) configured for your application.| String array | No| No |
### Internal Structure of the permissions Object
### Internal Structure of the permissions Object
The **permissions** object contains restricted permissions required for your application. Different from the ACLs set in the **acls** object, these permissions need user authorization during the running of your application. It should be noted that you still need to fill the permission information in the **reqPermissions** attribute in the [config.json](package-structure.md) file.
The **permissions** object contains restricted permissions required for your application. Different from the ACLs set in the **acls** object, these permissions need user authorization during the running of your application. It should be noted that you still need to add the ACL information to the **requestPermissions** attribute in the application configuration file.
**Table 5** Internal structure of the permissions object
| Name | Description | Data Type| Mandatory | Initial Value Allowed|
| Name | Description | Data Type| Mandatory| Initial Value Allowed|
| device-id-type | Type of the device ID. Currently, only the udid type is supported.| String | No| No |
| device-id-type | Type of the device ID. Currently, only the udid type is supported.| String | No | No |
| device-ids | IDs of devices on which your application can be debugged.| String array | No| No |
| device-ids | IDs of devices on which your application can be debugged.| String array | Optional| No |
## Modifying the HarmonyAppProvision Configuration File
When a development project is created, the default application type is **hos_normal_app** and the default APL level is **normal**.
To enable the application to use system APIs, you need to change the **app-feature** field to **hos_system_app** (system application). To apply for high-level permissions, you need to modify fields such as **apl** and **acl**. For details, see [Access Control Overview](accesstoken-overview.md).
To modify the HarmonyAppProvision configuration file, perform the following steps:
1. Open the directory where the OpenHarmony SDK is located. (You can choose **File** > **Settings** > **OpenHarmony SDK** on the menu bar of DevEco Studio to query the directory.)
2. In the SDK directory, go to the **Toolchains** > {Version} > **lib** directory and open the **UnsgnedReleasedProfileTemplate.json** file.
3. Modify the related fields as required.
After modifying the configuration file, [sign the application](hapsigntool-guidelines.md).
