Runtime permissions

In Android 6.0 and higher, the Android app permissions model is designed to make permissions more understandable, useful, and secure for users. The model moved Android apps that require dangerous permissions (see Affected permissions) from an install-time permission model to a runtime permission model:

  • Install-time permissions

    (Android 5.1 and lower) Users grant dangerous permissions to an app when they install or update the app. Device manufacturers and carriers can preinstall apps with pregranted permissions without notifying the user.

  • Runtime permissions

    (Android 6.0 to 9) Users grant dangerous permissions to an app when the app is running. When permissions are requested (such as when the app launches or when the user accesses a specific feature) depends on the app, but the user grants/denies app access to specific permission groups. OEMs/carriers can preinstall apps, but can't pregrant permissions unless they go through the exception process. (See Creating exceptions.)

    (Android 10) Users see increased transparency and have control over which apps have activity recognition (AR) runtime permissions. Users are prompted by the runtime permissions dialog to either always allow, allow while in use, or deny permissions. On an OS upgrade to Android 10, permissions given to apps are retained, but users can go into Settings and change them.

Runtime permissions prevent apps from gaining access to private data without a user's consent, and provide them with additional context and visibility into the types of permissions that apps are either seeking, or have been granted. The runtime model encourages developers to help users understand why apps require the requested permissions, and provides greater transparency so users can make better decisions about granting or denying them.

Affected permissions

Android 6.0 and higher requires dangerous permissions to use a runtime permissions model. Dangerous permissions are higher-risk permissions (such as READ_CALENDAR) that grant requesting apps access to private user data, or control over a device, which can negatively impact the user. To view a list of dangerous permissions, run the command:

adb shell pm list permissions -g -d

Android 6.0 and higher doesn't change the behavior of normal permissions. These are all non-dangerous permissions including normal, system, and signature permissions. Normal permissions are lower-risk permissions (such as SET_WALLPAPER) that grant requesting apps access to isolated app-level features with minimal risk to other apps, the system, or the user. As in Android 5.1 and lower releases, the system automatically grants normal permissions to a requesting app at installation and doesn't prompt the user for approval. For details on permissions, see the <permission> element documentation.

Hard and soft restrictions in Android 10

In addition to being dangerous, a permission can be either hard-restricted or soft-restricted. In either case, the restricted permission must also be allowlisted. Non-allowlisted hard restrictions behave differently than non-allowlisted soft restrictions:

  • (Hard restrictions) Apps can't be granted permissions that aren't allowlisted.
  • (Soft restrictions) Apps without allowlisting behave according to the specific permission they request. The behavior is described in the public documentation for the requested permission.

When installing an app, the installer (such as Google Play Store) may select to not allowlist the restricted permissions for the app. Permissions are restricted by the platform and are grantable only if an app meets special criteria per platform policy. Examples of hard-restricted permission types include SMS and Call Log permissions.

Allowlisting happens during installation, and when

  • an app is already installed during an Android 9-to-10 upgrade.
  • a permission is pregranted or an app is preinstalled.
  • a permission is required for a role that's already defined to allowlist the permission.
  • the installer (such as Google Play Store) marks the permission as allowlisted.

Users can't manually allowlist permissions.

Requirements

The runtime permission model applies to all apps, including pre-installed apps and apps delivered to the device as part of the setup process. App software requirements include:

  • The runtime permission model must be consistent across all devices running Android 6.0 and higher. This is enforced by Android Compatibility Test Suite (CTS) tests.
  • Apps must prompt users to grant app permissions at runtime. For details, see Update apps. Limited exceptions may be granted to default apps and handlers that provide basic device functionality fundamental to the expected operation of the device. (For example, the device's default Dialer app for handling ACTION_CALL may have Phone permission access.) For details, see Creating exceptions.
  • Preloaded apps that have dangerous permissions must target API level 23 and maintain the runtime permission model. That is, the UI flow during app installation mustn't deviate from the AOSP implementation of PermissionController, users can revoke dangerous permissions of preinstalled apps, and so on.
  • Headless apps must use an activity to request permissions or to share a UID with another app that has the necessary permissions. For details, see Headless apps.

Permissions migration

Permissions granted to apps on Android 5.x remain granted after updating to Android 6.0 or higher, but users can revoke those permissions at any time.

In an Android 9-to-10 update, all hard-restricted permissions get allowlisted. For details on implementing the foreground/background split permissions, see Android 10 privacy change, beginning with Request background location.

Integration

When integrating the app runtime permissions model for Android 6.0 and higher, you must update preinstalled apps to work with the new model. You can also define exceptions for apps that are the default handlers/providers for core functionality, define custom permissions, and customize the theme used in the PermissionController app.

Update apps

Apps on the system image and preinstalled apps aren't automatically pregranted permissions. We encourage you to work with preinstalled app developers (OEM, carrier, and third party) to make the required app modifications using developer guidelines. Specifically, you must ensure that preinstalled apps are modified to avoid crashes and other issues when users revoke permissions.

Preloaded apps

In Android 9 and lower, preloaded apps that use dangerous permissions must target API level 23 or higher, and maintain the Android 6.0 and higher AOSP permission model. For example, the UI flow during an app installation mustn't deviate from the AOSP implementation of PermissionController. Users can even revoke the dangerous permissions of preinstalled apps.

In Android 6.0 through 9, some permissions are granted during the install flow. However, starting in 10, the install flow (performed by the Package Installer app) is a separate function from permissions granting (in the Permission Controller app).

Headless apps

Only activities can request permissions. Services can't request permissions directly.

  • In Android 5.1 and earlier, headless apps can request permissions when installed, or if they were pre-installed without the use of an activity.
  • In Android 6.0 and higher, headless apps must use one of the following methods to request permissions:
    • Add an activity to request permissions. (This is the preferred method.)
    • Share a UID with another app that has the necessary permissions. Use this method only when you need the platform to handle multiple APKs as a single app.

The goal is to avoid confusing users with permission requests that appear out of context.

Customize the PackageInstaller UI

If desired, you can customize the Permissions UI theme by updating the default device themes (Theme.DeviceDefault.Settings and Theme.DeviceDefault.Light.Dialog.NoActionBar) used by PackageInstaller. However, because consistency is critical for app developers, you can't customize the placement, position, and rules of when the Permissions UI appears.

To include strings for additional languages, contribute the strings to AOSP.

Create exceptions

You can pre-grant permissions to apps that are default handlers or providers for core OS functionality using the DefaultPermissionGrantPolicy.java class in PackageManager. Examples:

ACTION_CALL (Dialer) Default
Phone, Contacts, SMS, Microphone

SMS_DELIVER_ACTION (SMS/MMS) Default
Phone, Contacts, SMS

Define custom permissions

You can define custom permissions and groups as normal or dangerous and add OEM/Carrier-specific permissions to existing permissions groups, just as you could in Android 5.x and earlier releases.

In Android 6.0 and later, if you add a new dangerous permission, it must be handled in the same way as other dangerous permissions (requested during app runtime and revocable by users). Specifically:

  • You can add new permissions to a current group, but you can't modify the AOSP mapping of dangerous permissions and dangerous permissions groups. (In other words, you can't remove a permission from a group and assign to another group).
  • You can add new permission groups in apps installed on the device, but you can't add new permissions groups in the platform manifest.

Test permissions

Android includes Compatibility Test Suite (CTS) tests that verify individual permissions are mapped to the correct groups. Passing these tests is a requirement for Android 6.0 and later CTS compatibility.

Revoke permissions

In Android 13 and later, you are able to revoke your own granted runtime permissions using Context.revokeSelfPermissionsOnKill(). The revocation happens asynchronously and is triggered when it is safe to do so without disrupting the user. When the revocation is triggered, all processes running in the calling UID is killed.

It's important to understand that revoking a single permission may not be reflected in the settings UI, which treats permissions by group. Typically, a permission group is displayed as granted as long as at least one of the permissions in that group is granted. If ensuring that users are able to confirm the revocation in the settings is important to you, make sure to revoke every permission in the permission group. To learn which permissions belong to a certain group, you may use PackageManager.getGroupOfPlatformPermission and PackageManager.getPlatformPermissionsForGroup.

When the system revokes the permissions requested, it also revokes corresponding background permissions if none of their corresponding foreground permissions are still granted.

The revocation isn't triggered as long as the process remains in the foreground but can also be triggered right away by manually killing all processes running in the current uid, for instance using System.exit(). However it is recommended to let the system decide when to trigger it.

After a permission revocation is effective, you are able to request it again, and the user is prompted to grant or deny the request. It isn't possible to request a permission that had previously been denied by the user. While you are encouraged to revoke permissions that you currently hold but are no longer needed, you should be careful not to inform the user about the revocation until after it's in effect.