• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Access Control (Permission) Development
2
3## When to Use
4
5In this example, the app requires the **ohos.permission.PERMISSION1** and **ohos.permission.PERMISSION2** permissions to implement core functions.
6
7- The ability privilege level (APL) of the app is normal.
8- The level of **ohos.permission.PERMISSION1** is **normal**, and the authorization mode is **system_grant**.
9- The level of **ohos.permission.PERMISSION2** is **system_basic**, and the authorization mode is **user_grant**.
10
11> **Caution**
12>
13> In this scenario, the required permissions include a user_grant permission. You can check whether the caller has the required permission through permission verification.
14>
15> If the permission verification result indicates that the app has not obtained that permission, dynamic user authorization is required.
16>
17## Available APIs
18
19The table below lists only the API used in this guide. For more information, see the [API Reference](../reference/apis/js-apis-abilityAccessCtrl.md).
20
21| API                                                      | Description                                            |
22| ------------------------------------------------------------ | --------------------------------------------------- |
23| verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus> | Verifies whether an app has the specified permission. This API uses a promise to return the result.|
24
25## Declaring Permissions
26
27### config.json
28
29Declare the permissions required by the app one by one in the **config.json** file. The app can obtain permissions that have been declared in the **config.json** file.
30
31**Description of config.json**
32
33| Field     | Description                                                        |
34| --------- | ------------------------------------------------------------ |
35| name      | Name of the permission.                                                  |
36| reason    | Reason for requesting the permission. This field is mandatory for a user_grant permission.|
37| usedScene | Scenario of the permission. This field is mandatory for a user_grant permission.|
38| ability | Abilities that use the permission. The value is an array.              |
39| 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).|
40
41**Example**
42
43```json
44{
45    "module" : {
46        "reqPermissions":[
47           {
48                "name" : "ohos.permission.PERMISSION1",
49                "reason": "$string:reason",
50                "usedScene": {
51                     "ability": [
52                         "FormAbility"
53                     ],
54                     "when":"inuse"
55                }
56            },
57           {
58                "name" : "ohos.permission.PERMISSION2",
59                "reason": "$string:reason",
60                "usedScene": {
61                     "ability": [
62                         "FormAbility"
63                     ],
64                     "when":"always"
65                }
66            }
67        ],
68    }
69}
70```
71## Declaring the ACL
72
73The permission level of **ohos.permission.PERMISSION2** is system_basic, which is higher than the app's APL. In this case, use the ACL.
74
75In addition to declaring all the permissions in the **config.json** file, you must declare the permissions whose levels are higher than the app's APL in the app's profile. In this example, declare the permission under the **acls** field:
76```json
77{
78    "version-name": "1.0.0",
79    "version-code": 1,
80    "app-distribution-type": "os_integration",
81    "uuid": "5027b99e-5f9e-465d-9508-a9e0134ffe18",
82    "validity": {
83        "not-before": 1594865258,
84        "not-after": 1689473258
85    },
86    "type": "release",
87    "bundle-info": {
88        "developer-id": "OpenHarmony",
89        "distribution-certificate": "-----BEGIN CERTIFICATE-----\nMIICMzCCAbegAwIBAgIEaOC/zDAMBggqhkjOPQQDAwUAMGMxCzAJBgNVBAYTAkNO\nMRQwEgYDVQQKEwtPcGVuSGFybW9ueTEZMBcGA1UECxMQT3Blbkhhcm1vbnkgVGVh\nbTEjMCEGA1UEAxMaT3Blbkhhcm1vbnkgQXBwbGljYXRpb24gQ0EwHhcNMjEwMjAy\nMTIxOTMxWhcNNDkxMjMxMTIxOTMxWjBoMQswCQYDVQQGEwJDTjEUMBIGA1UEChML\nT3Blbkhhcm1vbnkxGTAXBgNVBAsTEE9wZW5IYXJtb255IFRlYW0xKDAmBgNVBAMT\nH09wZW5IYXJtb255IEFwcGxpY2F0aW9uIFJlbGVhc2UwWTATBgcqhkjOPQIBBggq\nhkjOPQMBBwNCAATbYOCQQpW5fdkYHN45v0X3AHax12jPBdEDosFRIZ1eXmxOYzSG\nJwMfsHhUU90E8lI0TXYZnNmgM1sovubeQqATo1IwUDAfBgNVHSMEGDAWgBTbhrci\nFtULoUu33SV7ufEFfaItRzAOBgNVHQ8BAf8EBAMCB4AwHQYDVR0OBBYEFPtxruhl\ncRBQsJdwcZqLu9oNUVgaMAwGCCqGSM49BAMDBQADaAAwZQIxAJta0PQ2p4DIu/ps\nLMdLCDgQ5UH1l0B4PGhBlMgdi2zf8nk9spazEQI/0XNwpft8QAIwHSuA2WelVi/o\nzAlF08DnbJrOOtOnQq5wHOPlDYB4OtUzOYJk9scotrEnJxJzGsh/\n-----END CERTIFICATE-----\n",
90        "bundle-name": "com.ohos.permissionmanager",
91		"apl": "system_core",
92        "app-feature": "hos_system_app"
93    },
94    "acls": {
95        "allowed-acls": [
96            "ohos.permission.PERMISSION2"
97        ]
98    },
99    "permissions": {
100        "restricted-permissions": []
101    },
102    "issuer": "pki_internal"
103}
104```
105
106## Applying for the user_grant Permission
107
108After 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.
109
110Therefore, 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.
111
112If 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).
113
114> **Caution**
115>
116> 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.
117
118## Example
119
120The procedure is as follows:
121
1221. Obtain the ability context.
1232. Call **requestPermissionsFromUser** to verify whether the app has required permissions.
1243. Proceed based on the permission verification result.
125
126```js
127import featureAbility from '@ohos.ability.featureAbility';
128
129onStart() {
130    var context = featureAbility.getContext()
131    let array:Array<string> = ["ohos.permission.PERMISSION2"];
132    // requestPermissionsFromUser determines whether to invoke a pop-up window based on the permission authorization status.
133    context.requestPermissionsFromUser(array, 1, (err, data)=>{
134        console.info("====>requestdata====>" + JSON.stringify(data));
135        console.info("====>requesterrcode====>" + JSON.stringify(err.code));
136  })
137}
138```
139> **NOTE**<br>
140> For details about how to use **requestPermissionsFromUser**, see [API Reference](../reference/apis/js-apis-ability-context.md).
141