Entitlements in iOS development: what they are, types and how to configure them

What are Entitlements?

Entitlements (translated from English as “rights”) are key-value pairs included in the application's code signature at build time that determine which system capabilities and data the application can access. Entitlements have been built into Apple's security model since the introduction of the iOS SDK and are mandatory for all applications distributed through the App Store.

The concept of Entitlements differs from traditional permissions on Android. While Android permissions are requested from the user at the moment of first feature usage, Entitlements in iOS are verified by the system at application launch based on the digital signature. The user cannot revoke or change an entitlement — this right is granted to the developer through App Store Connect and is embedded in the provisioning profile.

Each entitlement has a strictly defined purpose and format. For example, com.apple.security.application-groups allows access to a shared container for a set of applications from the same developer, while aps-environment enables Push Notification support. Apple reviews entitlement requests manually during the App Review process, which prevents abuse of rights.

Types of Entitlements in iOS

Entitlements are classified by functional purpose into several categories. System Services — iCloud, Push Notifications, Siri. Security and Data — Keychain Access Groups, App Groups, Data Protection. Network and Communication — Multipath TCP, VPN, Hotspot Configuration. Hardware Capabilities — Camera, Microphone, Bluetooth (through related capabilities).

Capabilities and Service Entitlements

Xcode groups related entitlements into Capabilities — high-level toggles on the Signing & Capabilities tab. Enabling a Capability automatically adds the necessary entitlements to the .entitlements file. For example, enabling the Push Notifications capability adds the aps-environment entitlement with a value of development or production, while enabling iCloud adds a set of entitlements for CloudKit and Key-Value storage.

Some capabilities require additional configuration on the Apple Developer portal. For example, App Groups requires registering a group identifier on the portal, after which it becomes available for selection in Xcode. For Push Notifications, an APNs key or certificate must be generated. Without these preliminary steps, the entitlement will not work even with a correct .entitlements file.

App Groups and Keychain Access

The com.apple.security.application-groups entitlement allows multiple applications from the same developer to share a common container on the file system. This is used for data sharing between the main application and extensions (Widget, Watch App, Share Extension). All applications in the same group can read and write files to the shared /Library/Group Containers/ directory.

Keychain Access Groups (keychain-access-groups key) is another important entitlement that allows applications from the same group to share access to Keychain items. This is critical for implementing single sign-on: the user logs in to one application and automatically gains access to the same account in another application without re-entering the password.

How to Configure Entitlements

Entitlements are configured in Xcode on the Signing & Capabilities tab in the target settings. The developer selects the required Capabilities from the list, and Xcode automatically creates or updates the .entitlements file. This file is stored in the project in XML format with a plist structure and contains all entitlement keys for the given target.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.application-groups</key>
    <array>
        <string>group.com.example.shared</string>
    </array>
    <key>aps-environment</key>
    <string>development</string>
    <key>keychain-access-groups</key>
    <array>
        <string>$(AppIdentifierPrefix)com.example.keychain</string>
    </array>
</dict>
</plist>

When creating an entitlement file manually, it is important to follow the key format and prefixes. Apple entitlements use a reverse domain style (com.apple.*). Custom entitlements for your own purposes are also possible but must be registered on the developer portal. Xcode provides autocompletion for all standard entitlement keys.

For debugging Entitlements, use the codesign command in the macOS terminal. The command codesign -d --entitlements :- <path_to_application> outputs all entitlements with which the application is signed. This is useful for diagnosing problems: if an entitlement is missing from the output, the application will not get access to the corresponding function regardless of Xcode settings.

Creating an Entitlement File Manually

Although Xcode generates the entitlement file automatically when Capabilities are enabled, experienced developers often create or edit it manually for fine-tuning. The file has the .entitlements extension and plist format (XML). You can add custom entitlement keys that are not presented in the Xcode interface, or combine entitlements from different capabilities in one file.

When editing manually, it is important to ensure syntactic correctness of the XML. An error in the plist structure will cause the entitlements not to be applied during signing. Xcode checks the .entitlements file at compile time and outputs an error if the format is incorrect. For complex projects with multiple targets and extensions, it is recommended to store common entitlement keys in separate files and import them through Build Settings.

// cli: checking entitlements of an installed application
codesign -d --entitlements :- /Applications/Safari.app

// Example output contains a list of active entitlements
<dict>
    <key>com.apple.security.ts.apple-wifi</key>
    <true/>
    <key>com.apple.security.network.client</key>
    <true/>
</dict>

Entitlements and Application Security

Entitlements play a key role in Apple's security model. Since entitlements are part of the application's digital signature, tampering with them is impossible without re-signing the code. Apple checks entitlements at multiple levels: during build, Xcode signs entitlements together with the executable file; during installation, the system checks the signature integrity; at launch, it re-verifies the entitlements.

One important security requirement is the principle of least entitlement. The developer should only include entitlements that are actually used in the application. Unnecessary entitlements increase the attack surface and may cause the application to be rejected during App Review. Apple explicitly checks whether entitlements match the application's functionality.

Some entitlements are considered sensitive and require additional Apple approval. These include: com.apple.developer.healthkit (HealthKit), com.apple.developer.passkit (Wallet), com.apple.developer.authentication-services.authentication (Sign in with Apple) and com.apple.developer.nfc.readersession.formats (NFC). To obtain these entitlements, you must justify their necessity during the App Review process.

When working with entitlements, it is important to consider the differences between iOS and macOS. Desktop macOS applications (Sandboxed) have a broader set of entitlements compared to iOS. For example, the com.apple.security.temporary-exception.* entitlement allows temporarily bypassing the sandbox for certain operations — such entitlements are completely absent on iOS.

Entitlements and Provisioning Profiles

Entitlements are closely tied to Provisioning Profiles. A provisioning profile is a file that links the developer certificate, a list of allowed devices, and a set of entitlements for a specific application. When installing an application, the system compares the entitlements in the code with the entitlements in the provisioning profile. If an entitlement is present in the code but absent from the profile, the application will not get access to the corresponding function.

To diagnose problems with entitlements, first check the provisioning profile. Xcode automatically generates profiles based on selected capabilities on the Apple Developer portal. If a capability is added in Xcode but not active on the portal, the application will crash with a signing error when trying to use a protected function.