Define a Custom App Permission in Android

This article describes how app developers can use the security features provided by Android to define their own permissions.

Photo by Life Of Pix from Pexels

Why

Custom permissions can be used to protect the functionality and data provided by:

• Activity
• Service
• Broadcast
• Content provider

This can be very helpful when your app is interacting with other apps.

How to define custom permissions

To enforce your own permissions, you must first declare them in your AndroidManifest.xml using one or more <permission> elements.

<manifest
  xmlns:android="http://schemas.android.com/apk/res/android"
  package="com.example.myapp" >
    
    <permission
      android:name="com.example.myapp.permission.DEADLY_ACTIVITY"
      android:label="@string/permlab_deadlyActivity"
      android:description="@string/permdesc_deadlyActivity"
      android:permissionGroup="android.permission-group.COST_MONEY"
      android:protectionLevel="dangerous" />
    ...
</manifest>

The name tag will be used by other apps using the <uses-permission> element. This name should not collide with custom permissions for other apps. To avoid naming collisions, Google recommends using reverse-domain-style naming for custom permissions, for example com.example.myapp.ENGAGE_HYPERSPACE. The exception is if the apps are signed with the same certificate.

The label specifies the name of the permissions to be displayed to users.

The description defines a summary that will be shown to the end-user. Googles convention is a two-sentence description: the first sentence describes the permission, and the second sentence warns the user of the type of things that can go wrong if an app is granted the permission.

The permisisonGroup attribute helps the system describe permissions to the user. In most cases, you will want to set this to a standard system group (listed in android.Manifest.permission_group), but you can also define your own group with <permission-group>. If not set the permission does not belong to any group.

The protectionLevel is used to describe the sensitivity of the data or functionality. It can be normal, dangerous, signature.

How to use the permissions

Activity

<activity
    android:name=".MainActivity"
    android:permission="com.some_app.CUSTOM_PERMISSIOSN"
    android:theme="@style/AppTheme.NoActionBar"
    android:launchMode="singleTask"/>

The checks are performed during startActivity and startActivityForResult.

Service

<service
    android:name=".package_name.MyService"
    android:permission="com.some_app.CUSTOM_PERMISSIOSN" />

The required permission is again defined using the android:permission attribute in the service tag in the manifest. The checks are performed by the system during the startService, bindService, and stopService calls.

Broadcast

Permissions can be used when sending or receiving permissions.

When sending broadcast

sendBroadcast(new Intent("com.example.Notifiy", Manifest.permission.SEND_SMS))

When receiving broadcast

Use registerReceiver when registering programmatically.

intentFilter = IntentFilter(Intent.ACTION_...)
registerREceiver(receiver, intentFilter, Manifest.permission.SEND_SMS, null)

Use the permission attribute in the <receiver/> tag.

<receiver android:name=".MyBroadcastReceiver"
          android:permission="android.permission.SEND_SMS">
          <intent-filter>
          ...
          </intent-filter>
</receiver>

Content Provider

To protect both the read and write, use the android:permission attribute in the <provider/> tag in the manifest. To protect the read permission use the android:readPermission attribute, lastly to protect the write permission use the android:writePermission attribute.

<provider
    android:readPermission="com.example.app.READ_CUSTOM_CONTACTS"
    android:writePermission="com.example.app.CREATE_CUSTOM_CONTACT"
    ...
/>

The read permission is checked when calling ContentResolver.query().

The write permission protects the ContentResolver.update() and ContentResolver.delete() methods.

Best practices

• Define the permission once; even if your app uses the same signature.
• If the functionality is available to apps signed with the same signature, you can avoid defining custom permissions by using signature checks.

For more details on how the permissions are implemented Click me.