1 <html devsite> 2 <head> 3 <title>Runtime Permissions</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 26 <p>The Android application permission model in Android 6.0 and later is designed to make 27 permissions more understandable, useful, and secure for users. The model moved Android 28 applications that require dangerous permissions (see 29 <a href="#affected-permissions">Affected permissions</a>) from an 30 <em>install</em> time permission model to <em>runtime</em> permission model:</p> 31 32 <ul> 33 <li><strong>Install Time Permissions</strong> (<em>Android 5.1 and earlier</em>). 34 Users grant dangerous permissions to an app when installing or updating the app. 35 OEMs/carriers can pre-install apps with pre-granted permissions without 36 notifying the user.</li> 37 <li><strong>Runtime Permissions</strong> (Android <em>6.0 and later</em>). Users 38 grant dangerous permissions to an app when the app is running. Applications 39 decide when to request permissions (such as when the app launches or the user 40 accesses a specific feature), but must allow the user to grant/deny application 41 access to specific permission groups. OEMs/carriers can pre-install apps but 42 cannot pre-grant permissions (see <a href="#creating-exceptions">Creating 43 exceptions</a>).</li> 44 </ul> 45 46 <p>Runtime permissions provide users additional context and visibility into the 47 permissions applications are seeking or have been granted. The runtime model 48 also encourages developers to help users understand why applications require the 49 requested permissions and to provide greater transparency about the benefits and 50 hazards of granting or denying permissions.</p> 51 <p>Users can revoke application permissions using the Apps menu in Settings.</p> 52 53 <h2 id="affected-permissions">Affected permissions</h2> 54 55 <p>Android 6.0 and later requires dangerous permissions to use a runtime permissions 56 model. Dangerous permissions are higher-risk permissions (such as 57 <code>READ_CALENDAR</code>) that grant requesting applications access to private 58 user data or control over the device that can negatively impact the user. To 59 view a list of dangerous permissions, run the command:</p> 60 61 <pre class="devsite-terminal devsite-click-to-copy"> 62 adb shell pm list permissions -g -d 63 </pre> 64 65 <p>Android 6.0 and later does not change the behavior of normal permissions (all 66 non-dangerous permissions including normal, system, and signature permissions). 67 Normal permissions are lower-risk permissions (such as 68 <code>SET_WALLPAPER</code>) that grant requesting applications access to 69 isolated application-level features with minimal risk to other applications, the 70 system, or the user. As in Android 5.1 and earlier releases, the system 71 automatically grants normal permissions to a requesting application at 72 installation and does not prompt the user for approval. For details on 73 permissions, refer to 74 <a href="http://developer.android.com/guide/topics/manifest/permission-element.html"><permission> 75 element documentation</a>.</p> 76 77 <h2 id="requirements">Requirements</h2> 78 79 <p>The runtime permission model applies to all applications, including 80 pre-installed apps and apps delivered to the device as part of the setup 81 process. Application software requirements include:</p> 82 <ul> 83 <li>Runtime permission model must be consistent across all devices running 84 Android 6.0 and later. Enforced by Android Compatibility Test Suite (CTS) tests.</li> 85 <li>Apps must prompt users to grant application permissions at runtime. For 86 details, see <a href="#updating-apps">Updating applications</a>. Limited 87 exceptions may be granted to default applications and handlers that provide 88 basic device functionality fundamental to the expected operation of the device 89 (i.e. the device's default Dialer app for handling <code>ACTION_CALL</code> may 90 have Phone permission access). For details, see 91 <a href="#creating-exceptions">Creating exceptions</a>.</li> 92 <li>Pre-loaded apps with "dangerous permission" must target API level 23 and 93 maintain the runtime permission model (i.e. the UI flow during app installation 94 should not deviate from the AOSP implementation of PackageInstaller, users can 95 revoke dangerous permissions of pre-installed apps, etc.).</li> 96 <li>Headless applications must use an activity to request permissions or share a 97 UID with another application that has the necessary permissions. For details, 98 see <a href="#headless-apps">Headless applications</a>.</li> 99 </ul> 100 101 <h2 id="permissions-migration">Permissions migration</h2> 102 103 <p>Permissions granted to applications on Android 5.x remain granted after 104 updating to Android 6.0 or later, but users can revoke those permissions at any time.</p> 105 106 <h2 id="integration">Integration</h2> 107 108 <p>When integrating the application runtime permissions model for Android 6.0 and later, you 109 must update pre-installed applications to work with the new model. You can also 110 define exceptions for apps that are the default handlers/providers for core 111 functionality, define custom permissions, and customize the theme used in the 112 PackageInstaller.</p> 113 114 <h3 id="updating-apps">Updating applications</h3> 115 116 <p>Applications on the system image and pre-installed applications are not 117 automatically pre-granted permissions. We encourage you to work with 118 pre-installed app developers (OEM, Carrier, and third party) to make the 119 required app modifications using 120 <a href="https://developer.android.com/training/permissions/index.html">developer 121 guidelines</a>. Specifically, you must ensure that pre-installed applications 122 are modified to avoid crashes and other issues when users revoke permissions.</p> 123 124 <h4 id="preloaded-apps">Pre-loaded applications</h4> 125 <p>Pre-loaded apps that use dangerous permissions must target API level 23 or higher and 126 maintain the Android 6.0 and later AOSP permission model (i.e. the UI flow during an app 127 installation should not deviate from the AOSP implementation of 128 PackageInstaller, users can even revoke the dangerous permissions of 129 pre-installed apps, etc.).</p> 130 131 <h4 id="headless-apps">Headless applications</h4> 132 <p>Only activities can request permissions; services cannot directly request 133 permissions.</p> 134 <ul> 135 <li>In Android 5.1 and earlier releases, headless applications can request 136 permissions when installed or pre-installed without the use of an activity.</li> 137 <li>In Android 6.0 and later, headless applications must use one of the following methods 138 to request permissions:<ul> 139 <li>Add an activity to request permissions (preferred method).</li> 140 <li>Share a UID with another application that has the necessary permissions. Use 141 this method only when you need the platform to handle multiple APKs as a single 142 application.</li> 143 </ul></li> 144 </ul> 145 <p>The goal is to avoid confusing users with permission requests that appear out 146 of context.</p> 147 148 <h3 id="customizing-package-install">Customizing PackageInstaller</h3> 149 <p>If desired, you can customize the Permissions UI <strong>theme</strong> by 150 updating the default device themes (<code>Theme.DeviceDefault.Settings</code> 151 and <code>Theme.DeviceDefault.Light.Dialog.NoActionBar</code>) used by 152 PackageInstaller. However, because consistency is critical for app developers, 153 you cannot customize the placement, position, and rules of when the Permissions 154 UI appears.</p> 155 <p>To include <strong>strings</strong> for additional languages, contribute the 156 strings to AOSP.</p> 157 158 <h3 id="creating-exceptions">Creating exceptions</h3> 159 <p>You can pre-grant permissions to applications that are default handlers or 160 providers for core OS functionality using the 161 <code>DefaultPermissionGrantPolicy.java</code> in PackageManager. Examples:</p> 162 163 <pre class="devsite-click-to-copy"> 164 ACTION_CALL (Dialer) Default 165 Phone, Contacts, SMS, Microphone 166 </pre> 167 <pre class="devsite-click-to-copy"> 168 SMS_DELIVER_ACTION (SMS/MMS) Default 169 Phone, Contacts, SMS 170 </pre> 171 172 <h3 id="defining-custom-perms">Defining custom permissions</h3> 173 <p>You can define custom permissions and groups as <em>normal</em> or 174 <em>dangerous</em> and add OEM/Carrier-specific permissions to existing 175 permissions groups, just as you could in Android 5.x and earlier releases.</p> 176 177 <p>In Android 6.0 and later, if you add a new dangerous permission, it must be handled in 178 the same way as other dangerous permissions (requested during app runtime and 179 revocable by users). Specifically:</p> 180 181 <ul> 182 <li>You can add new permissions to a current group, but you cannot modify the 183 AOSP mapping of dangerous permissions and dangerous permissions group (e.g. you 184 cannot remove a permission from a group and assign to other group).</li> 185 <li>You can add new permission groups in applications installed on the device, 186 but you cannot add new permissions groups in the platform manifest.</li> 187 </ul> 188 189 <h2 id="testing-perms">Testing permissions</h2> 190 <p>Android includes Compatibility Test Suite (CTS) tests that verify 191 individual permissions are mapped to the correct Groups. Passing these tests is 192 a requirement for Android 6.0 and later CTS compatibility.</p> 193 194 </body> 195 </html> 196
