Runtime Permissions

In Android 6.0 and higher, the Android application permissions model is designed to make permissions more understandable, useful, and secure for users. The model moved Android applications 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 – 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 application, but the user grants/denies application 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 applications are either seeking, or have been granted. The runtime model encourages developers to help users understand why applications 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 applications 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 applications access to isolated application-level features with minimal risk to other applications, the system, or the user. As in Android 5.1 and lower releases, the system automatically grants normal permissions to a requesting application 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 whitelisted. Non-whitelisted hard restrictions behave differently than non-whitelisted soft restrictions:

  • (Hard restrictions) Apps can’t be granted permissions that aren’t whitelisted.
  • (Soft restrictions) Apps without whitelisting 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 whitelist 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.

Whitelisting 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 whitelist the permission.
  • the installer (such as Google Play Store) marks the permission as white-listed.

Users can’t manually whitelist permissions.

Requirements

The runtime permission model applies to all applications, including pre-installed apps and apps delivered to the device as part of the setup process. Application 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 application permissions at runtime. For details, see Updating applications. Limited exceptions may be granted to default applications 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 applications must use an activity to request permissions or to share a UID with another application that has the necessary permissions. For details, see Headless applications.

Permissions migration

Permissions granted to applications 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 whitelisted. For details on implementing the foreground/background split permissions, see Android 10 privacy change, beginning with Request background location.

Integration

When integrating the application runtime permissions model for Android 6.0 and higher, you must update preinstalled applications 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.

Updating applications

Applications on the system image and preinstalled applications 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 applications are modified to avoid crashes and other issues when users revoke permissions.

Pre-loaded applications

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 applications

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

  • In Android 5.1 and earlier, headless applications can request permissions when installed, or if they were pre-installed without the use of an activity.
  • In Android 6.0 and higher, headless applications 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 application that has the necessary permissions. Use this method only when you need the platform to handle multiple APKs as a single application.

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

Customizing 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.

Creating exceptions

You can pre-grant permissions to applications 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

Defining 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 applications installed on the device, but you can't add new permissions groups in the platform manifest.

Testing 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.