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- All the permissions for applications must come from the [Application Permission List](permission-list.md). Custom permissions are not allowed currently. 26 27## Permission Workflows 28 29### Applying for and Using a Permission 30 31Determine the permissions required by an application, and declare the required permissions in the application installation package. 32 33Determine whether the required permissions need user authorization. If yes, display a dialog box dynamically to request user authorization. 34 35After the user grants the permissions, the application can access the data or perform the operation. 36 37The figure below illustrates the process. 38 39 40 41**NOTE** 42 431. Refer to the figure below to determine whether an application can apply for a permission. 44 45 46 47**NOTE** 48 491. See [Permission Levels](#permission-levels) for details about the mapping between the application Ability Privilege Level (APL) and the permission level. 50 512. 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). 52 533. A low-APL application can have a high-level permission by using the Access Control List (ACL). For details, see [ACL](#acl). 54 55### Verifying a Permission 56 57To 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. 58 59The API can be called only after the permission verification is successful. 60 61The figure below shows the permission verification process. 62 63 64 65**NOTE** 66 671: An application permission can be used to control the access to an API that has sensitive data involved or security threats on core abilities. 68 692: 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. 70 713: Use **checkAccessToken()** to check whether the caller has the required permission. For details, see [API Access Permission Verification](permission-verify-guidelines.md). 72 73## Permission Levels 74 75ATM defines different permission levels based on the sensitivity of the data involved or the security threat of the ability to protect user privacy. 76 77### Application APLs 78 79The APL defines the priority for an application to apply for permissions. Applications of different APLs can apply for permissions of different levels. 80 81The following table describes the APLs. 82 83| APL | Description | 84| ---------------- | -------------------------------------- | 85| system_core | Application that provides core abilities of the operating system (OS). | 86| system_basic| Application that provides basic system services. | 87| normal | Normal application. | 88 89The default APL of applications is **normal**. 90 91To 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. 92 93Then, 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). 94 95> **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. 96 97Example: 98 99This 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). 100 101```json 102{ 103 "bundle-info" : { 104 "developer-id": "OpenHarmony", 105 "development-certificate": "Base64 string", 106 "distribution-certificate": "Base64 string", 107 "bundle-name": "com.OpenHarmony.app.test", 108 "apl": "system_basic", 109 "app-feature": "hos_normal_app" 110 }, 111} 112``` 113 114### Levels of Permissions 115 116The permissions available to applications vary with the APL. The permission levels include the following in ascending order of seniority. 117 118- **normal** 119 120 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. 121 122 The permissions of this level are available to applications of the **normal** or higher APL. 123 124- **system_basic** 125 126 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. 127 128 The permissions of this level are available only to applications of the **system_basic** or **system_core** APL. 129 130- **system_core** 131 132 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. 133 134 The **system_core** permissions are not available to third-party applications. 135 136## Permission Types 137 138Permissions can be classified into the following types based on the authorization mode: 139 140- **system_grant** 141 142 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. 143 144 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. 145 146- **user_grant** 147 148 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. 149 150 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. 151 152 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. 153 154 The user_grant permission list must also be presented on the details page of each application in the application market. 155 156### Permission Groups and Permissions 157 158To minimize the number of pop-up permission windows and optimize interaction experience, the logically related user_grant permissions are combined to form multiple permission groups. 159 160The permissions of the same permission group are displayed in the same dialog box for user authorization. A permission in a permission group is called a sub-permission of the group. 161 162The relationship between a permission group and its permissions is not fixed. The permission group to which a permission belongs may change. For details about the permission groups supported by the system, see [Application Permission Group List](permission-group-list.md). 163 164### Authorization Processes 165 166As described in [Permission Workflows](permission-workflows), you need to first apply for the required permissions for your application. 167 168- Applying for a permission 169 170 You need to [declare the required permissions](accesstoken-guidelines.md#declaring-permissions-in-the-configuration-file) in the configuration file. 171 172- Authorizing a permission 173 174 - The system_grant permission is pre-granted when the application is installed. 175 - 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). 176 177### Requesting User Authorization 178 179The procedure is as follows: 180 1811. In the configuration file, declare the permissions required by your application. For details, see [Declaring Permissions in the Configuration File](accesstoken-guidelines.md#declaring-permissions-in-the configuration-file). 182 1832. Associate the target object in the application with the required permission. This allows the users to know the operations that need user authorization. 184 1853. 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. 186 1874. Check the user authorization result. Allow the subsequent operations only after the user has granted the permission to the application successfully. 188 189**CAUTION** 190 191- Each time before the operation that requires the target permission is performed, the application must check whether the permission is available. 192- 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#grantstatus) or [PERMISSION_DENIED](../reference/apis/js-apis-abilityAccessCtrl.md#grantstatus). For details about the sample code, see [Requesting User Authorization] (accesstoken-guidelines.md#requesting-user-authorization). 193- 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. 194- 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. 195 196## ACL 197 198Permission 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. 199 200The ACL makes low-APL applications have high-level permissions. 201 202**Example:** 203 204The APL of application A is **normal**. Application A needs to have permission B (system_basic level) and permission C (normal level). 205 206In this case, you can use the ACL to grant permission B to application A. 207 208For details, see [Using the ACL](#using-the-acl). 209For details about whether a permission can be enabled via the ACL, see [Application Permission List](permission-list.md). 210 211### Using the ACL 212 213If 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. 214 215In addition to the preceding [authorization processes](#authorization-processes), you must declare the ACL. 216 217That 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. 218 219**NOTICE** 220 221When 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. 222 223> **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. 224 225```json 226{ 227 "acls": { 228 "allowed-acls": [ 229 "ohos.permission.PERMISSION" 230 ] 231 }, 232} 233``` 234 235For details about the fields in the profile, see [HarmonyAppProvision Configuration File](app-provision-structure.md). 236
