1# Access Control (Permission) Overview 2 3OpenHarmony AccessTokenManager (ATM) implements unified management of application permissions based on access tokens. 4 5By default, applications can access limited system resources. However, to provide extended features, an application may need to access excess data (including personal data) and functions of the system or another application. The system or applications must also explicitly share their data or functions through APIs. OpenHarmony uses application permissions to prevent unauthorized access to and improper or malicious use of these data or functions. 6 7Application permissions are used to protect the following objects: 8 9- Data: includes personal data (such as photos, contacts, calendar, and location), device data (such as device ID, camera, and microphone), and application data. 10- Functions: includes device functions (such as making calls, sending SMS messages, and connecting to the Internet) and application functions (such as displaying windows and creating shortcuts). 11 12Without the required permissions, an application cannot access or perform operations on the target object. Permissions must be clearly defined for applications. With well-defined application permissions, the system can standardize application behavior and protect user privacy. Before an application accesses an object, the object verifies the application's permissions and denies the access if the application does not have required permissions. 13 14Currently, ATM verifies application permissions based on the token identity (token ID). A token ID identifies an application. ATM manages application permissions based on the application's token ID. 15 16## Basic Principles for Permission Management 17 18Observe the following permission management principles: 19 20- Provide clear description about the usage and scenario for each permission required by the application so that user can clearly know why and when these permissions are needed. Do not induce or mislead users' authorization. The permissions on an application must comply with the description provided in the application. 21- Use the principle of least authority for application permissions. Allow only necessary permissions for service functions. 22- When an application is started for the first time, avoid frequently displaying dialog boxes to request multiple permissions. Allow the application to apply for the permission only when it needs to use the corresponding service function. 23- If a user rejects to grant a permission, the user can still use functions irrelevant to this permission and can register and access the application. 24- 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. 25 26- All the permissions for applications must come from the [Application Permission List](permission-list.md). Custom permissions are not allowed currently. 27 28## Permission Workflows 29 30### Applying for and Using a Permission 31 32Determine the permissions required by an application, and declare the required permissions in the application installation package. 33 34Determine whether the required permissions need user authorization. If yes, display a dialog box dynamically to request user authorization. 35 36After the user grants the permissions, the application can access the data or perform the operation. 37 38The figure below illustrates the process. 39 40 41 421. Refer to the figure below to determine whether an application can apply for a permission. 43 44 45 461. See [Permission Levels](#permission-levels) for details about the mapping between the application Ability Privilege Level (APL) and the permission level. 47 482. The permission authorization modes include user_grant (permission granted by the user) and system_grant (permission granted by the system). For details, see [Permission Types](#permission-types). 49 503. A low-APL application can have a high-level permission by using the Access Control List (ACL). For details, see [ACL](#acl). 51 52### Verifying a Permission 53To protect sensitive data and eliminate security threats on core abilities, you can use the permissions in the [Application Permission List](permission-list.md) to protect an API from unauthorized calling. Each time before the API is called, a verification is performed to check whether the caller has the required permission. 54 55The API can be called only after the permission verification is successful. 56 57The figure below shows the permission verification process. 58 59 60 611: An application permission can be used to control the access to an API that has sensitive data involved or security threats on core abilities. 62 632: 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 application, you can use a contact-related permission to protect the API. 64 653: Use **checkAccessToken()** to check whether the caller has the required permission. For details, see [API Access Permission Verification](permission-verify-guidelines.md). 66 67## Permission Levels 68 69ATM defines different permission levels based on the sensitivity of the data involved or the security threat of the ability to protect user privacy. 70 71### Application APLs 72 73The APL defines the priority for an application to apply for permissions. Applications of different APLs can apply for permissions of different levels. 74 75The following table describes the APLs. 76 77| APL | Description | 78| ---------------- | -------------------------------------- | 79| system_core | Application that provides core abilities of the operating system (OS). | 80| system_basic| Application that provides basic system services. | 81| normal | Normal application. | 82 83The default APL of applications is **normal**. 84 85To set an application's APL to **system_basic** or **system_core**, set the **apl** field under **bundle-info** in the application's profile when developing the application's installation package. 86 87Then, use the [hapsigner](hapsigntool-overview.md) tool to generate a certificate or use DevEco Studio to [have your application automatically signed](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-auto-configuring-signature-information-0000001271659465#section161281722111). 88 89> **CAUTION**<br>The method of changing the application's APL in its profile applies only to the application or service in debug mode. For a commercial application, apply for a release certificate and profile in the corresponding application market. 90 91Example: 92 93This 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). 94 95```json 96{ 97 "bundle-info" : { 98 "developer-id": "OpenHarmony", 99 "development-certificate": "Base64 string", 100 "distribution-certificate": "Base64 string", 101 "bundle-name": "com.OpenHarmony.app.test", 102 "apl": "system_basic", 103 "app-feature": "hos_normal_app" 104 }, 105} 106``` 107 108### Levels of Permissions 109 110The permissions available to applications vary with the APL. The permission levels include the following in ascending order of seniority. 111 112- **normal** 113 114 The **normal** permission allows access to common system resources beyond the default rules. Access to these resources (including data and functions) has minor risks on user privacy and other applications. 115 116 The permissions of this level are available to applications of the **normal** or higher APL. 117 118- **system_basic** 119 120 The **system_basic** permission allows access to resources related to basic OS services. The basic services are basic functions provided or preconfigured by the system, such as system settings and identity authentication. Access to these resources may have considerable risks to user privacy and other applications. 121 122 The permissions of this level are available only to applications of the **system_basic** or **system_core** APL. 123 124- **system_core** 125 126 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. 127 128 The **system_core** permissions are not available to third-party applications. 129 130## Permission Types 131 132Permissions can be classified into the following types based on the authorization mode: 133 134- **system_grant** 135 136 A system_grant permission is authorized by the system. The application with this type of permission cannot access user or device sensitive information, and the operations allowed have minor impact on the system or other applications. 137 138 For an application with a system_grant permission, the system automatically grants the permission to the application when the application is installed. The system_grant permission list must be presented to users on the details page of the application in the application market. 139 140- **user_grant** 141 142 A user_grant permission must be authorized by the user. An application with this type of permission may access user or device sensitive information, and the operations allowed may have a critical impact on the system or other applications. 143 144 This type of permissions must be declared in the application installation package and authorized by users dynamically during the running of the application. The application has the permission only after user authorization. 145 146 For example, the permissions for microphones and cameras in the [Application Permission List](permission-list.md) are user_grant. The list provides information about when to use the permissions. 147 148 The user_grant permission list must also be presented on the details page of each application in the application market. 149 150### Authorization Processes 151 152As described in [Permission Workflows](permission-workflows), you need to first apply for the required permissions for your application. 153 154- Applying for a permission 155 156 You need to [declare the required permissions](accesstoken-guidelines.md#declaring-permissions-in-the-configuration-file) in the configuration file. 157 158- Authorizing a permission 159 160 - The system_grant permission is pre-granted when the application is installed. 161 - For a user_grant permission, you need to trigger user authorization through a dialog box during the running of the application. For details, see [Requesting User Authorization](#requesting-user-authorization). 162 163### Requesting User Authorization 164 165The procedure is as follows: 166 1671. In the configuration file, declare the permissions required by your application. For details, see [Permission Application Guide](accesstoken-guidelines.md). 168 1692. Associate the target object in the application with the required permission. This allows the users to know the operations that need user authorization. 170 1713. Use an API to dynamically trigger a dialog box for requesting user authorization when the target object is accessed. This API first checks whether the user has granted the permission required. If no, a dialog box will be displayed to request authorization from the user. 172 1734. Check the user authorization result. Allow the subsequent operations only after the user has granted the permission to the application successfully. 174 175**Caution** 176 177- Each time before the operation that requires the target permission is performed, the application must check whether the permission is available. 178- To check whether a user has granted a permission to your application, use [checkAccessToken()](../reference/apis/js-apis-abilityAccessCtrl.md#checkaccesstoken9). 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 [Permission Application Guide](accesstoken-guidelines.md). 179- Users must be able to understand and control the authorization of user_grant permissions. For a user_grant permission, the application must proactively call an API to dynamically request user authorization. Then, the system displays a dialog box asking the user to grant the permission. The user then determines whether to grant the permission. 180- The user may revoke the permission authorization at any time. Therefore, each time before an API associated with a user_grant permission is called, the application must check whether the permission is available. 181 182## ACL 183 184Permission levels and application APLs are in one-to-one correspondence. In principle, an application with a lower APL cannot apply for higher-level permissions by default. 185 186The ACL makes low-APL applications have high-level permissions. 187 188**Example:** 189 190The APL of application A is **normal**. Application A needs to have permission B (system_basic level) and permission C (normal level). 191 192In this case, you can use the ACL to grant permission B to application A. 193 194For details, see [Using the ACL](#using-the-acl). 195For details about whether a permission can be enabled via the ACL, see [Application Permission List](permission-list.md). 196 197### Using the ACL 198 199If the permission required by an application has a higher level than the application's APL, you can use the ACL to grant the permission required. 200 201In addition to the preceding [authorization processes](#authorization-processes), you must declare the ACL. 202 203That is, you need to declare the required permissions in the application's configuration file, and [declare the ACL](accesstoken-guidelines.md#declaring-the-acl) in the application's profile. The subsequent authorization steps are the same. 204 205**NOTICE** 206 207When developing an application installation package, you must declare the ACL in the **acls** field in the application's profile. Then, use the [hapsigner](hapsigntool-overview.md) tool to generate a certificate. 208 209> **CAUTION**<br>The method of changing the application's APL in its profile applies only to the application or service in debug mode. For a commercial application, apply for a release certificate and profile in the corresponding application market. 210 211```json 212{ 213 "acls": { 214 "allowed-acls": [ 215 "ohos.permission.PERMISSION" 216 ] 217 }, 218} 219``` 220 221For details about the fields in the profile, see [HarmonyAppProvision Configuration File](app-provision-structure.md). 222
