Entitlements в разработке под iOS: что это, какие бывают и как настраиваются

Что такое Entitlements?

Entitlements (в переводе с английского — «права») — это пара ключ-значение, которая включается в код-подпись приложения на этапе сборки и определяет, к каким системным возможностям и данным приложение имеет доступ. Entitlements встроены в модель безопасности Apple с момента появления iOS SDK и являются обязательными для всех приложений, распространяемых через App Store.

Концепция Entitlements отличается от традиционных разрешений (permissions) на Android. Если Android-разрешения запрашиваются у пользователя в момент первого использования функции, то Entitlements в iOS проверяются системой при запуске приложения на основе цифровой подписи. Пользователь не может отозвать или изменить entitlement — это право предоставляется разработчику через App Store Connect и закрепляется в профиле подписи.

Каждый entitlement имеет строго определённое назначение и формат. Например, com.apple.security.application-groups разрешает доступ к общему контейнеру для набора приложений одного разработчика, а aps-environment включает поддержку Push-уведомлений. Apple ревьюит запросы на entitlements вручную в процессе App Review, что предотвращает злоупотребление правами.

Типы Entitlements в iOS

Entitlements классифицируются по функциональному назначению на несколько категорий. Системные сервисы — iCloud, Push Notifications, Siri. Безопасность и данные — Keychain Access Groups, App Groups, Data Protection. Сеть и связь — Multipath TCP, VPN, Hotspot Configuration. Аппаратные возможности — Camera, Microphone, Bluetooth (через связанные capabilities).

Capabilities и сервисные Entitlements

Xcode группирует связанные entitlements в Capabilities — высокоуровневые переключатели на вкладке Signing & Capabilities. Включение Capability автоматически добавляет необходимые entitlements в файл .entitlements. Например, включение Capability Push Notifications добавляет entitlement aps-environment со значением development или production, а включение iCloud добавляет набор entitlements для CloudKit и Key-Value storage.

Некоторые capabilities требуют дополнительной настройки на портале Apple Developer. Например, для App Groups необходимо зарегистрировать идентификатор группы на портале, после чего он становится доступным для выбора в Xcode. Для Push Notifications требуется сгенерировать APNs-ключ или сертификат. Без этих предварительных шагов entitlement не будет работать даже при корректном файле .entitlements.

App Groups и Keychain Access

Entitlement com.apple.security.application-groups позволяет нескольким приложениям одного разработчика иметь общий контейнер на файловой системе. Это используется для шаринга данных между основным приложением и расширениями (Widget, Watch App, Share Extension). Все приложения из одной группы могут читать и записывать файлы в общую директорию /Library/Group Containers/.

Keychain Access Groups (ключ keychain-access-groups) — ещё один важный entitlement, позволяющий приложениям из одной группы иметь общий доступ к элементам Keychain. Это критически важно для реализации единой аутентификации: пользователь входит в одном приложении и автоматически получает доступ к тому же аккаунту в другом приложении без повторного ввода пароля.

Как настраивать Entitlements

Настройка Entitlements выполняется в Xcode на вкладке Signing & Capabilities в настройках таргета. Разработчик выбирает нужные Capabilities из списка, и Xcode автоматически создаёт или обновляет файл .entitlements. Этот файл хранится в проекте в формате XML со структурой plist и содержит все ключи entitlements для данного таргета.

<?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>

При создании entitlement-файла вручную важно соблюдать формат ключей и префиксы. Entitlements Apple используют обратный доменный стиль (com.apple.*). Кастомные entitlements для собственных целей также возможны, но должны быть зарегистрированы на портале разработчика. Xcode предоставляет автодополнение для всех стандартных ключей entitlements.

Для отладки Entitlements используйте команду codesign в терминале macOS. Команда codesign -d --entitlements :- <путь_к_приложению> выводит все entitlements, которыми подписано приложение. Это полезно для диагностики проблем: если entitlement отсутствует в выводе, приложение не получит доступ к соответствующей функции независимо от настроек в Xcode.

Создание entitlement файла вручную

Хотя Xcode генерирует entitlement файл автоматически при включении Capabilities, опытные разработчики часто создают или редактируют его вручную для тонкой настройки. Файл имеет расширение .entitlements и формат plist (XML). В нём можно добавлять кастомные entitlement-ключи, которые не представлены в интерфейсе Xcode, или комбинировать entitlements из разных capabilities в одном файле.

При ручном редактировании важно следить за синтаксической корректностью XML. Ошибка в структуре plist приведёт к тому, что entitlements не будут применены при подписании. Xcode проверяет файл .entitlements на этапе компиляции и выводит ошибку при неверном формате. Для сложных проектов с множеством таргетов и расширений рекомендуется хранить общие entitlement-ключи в отдельных файлах и импортировать их через Build Settings.

// cli: проверка entitlements у установленного приложения
codesign -d --entitlements :- /Applications/Safari.app

// Пример вывода содержит список активных entitlements
<dict>
    <key>com.apple.security.ts.apple-wifi</key>
    <true/>
    <key>com.apple.security.network.client</key>
    <true/>
</dict>

Entitlements и безопасность приложения

Entitlements играют ключевую роль в модели безопасности Apple. Поскольку entitlements являются частью цифровой подписи приложения, их подделка невозможна без переподписания кода. Apple проверяет entitlements на нескольких уровнях: при сборке Xcode подписывает entitlements вместе с исполняемым файлом, при установке система проверяет целостность подписи, при запуске — верифицирует entitlements заново.

Одно из важных требований безопасности — принцип минимального entitlement. Разработчик должен включать только те entitlements, которые реально используются в приложении. Лишние entitlements увеличивают поверхность атаки и могут стать причиной отклонения приложения на App Review. Apple явно проверяет соответствие entitlements функциональности приложения.

Некоторые entitlements считаются чувствительными (sensitive) и требуют дополнительного одобрения Apple. К ним относятся: com.apple.developer.healthkit (HealthKit), com.apple.developer.passkit (Wallet), com.apple.developer.authentication-services.authentication (Sign in with Apple) и com.apple.developer.nfc.readersession.formats (NFC). Для получения этих entitlements необходимо обосновать их необходимость в процессе App Review.

При работе с entitlements важно учитывать различия между iOS и macOS. Desctop-приложения macOS (Sandboxed) имеют более широкий набор entitlements по сравнению с iOS. Например, entitlement com.apple.security.temporary-exception.* позволяет временно обходить песочницу для определённых операций — на iOS такие entitlements отсутствуют полностью.

Entitlements и Provisioning Profile

Entitlements тесно связаны с профилями подписи (Provisioning Profiles). Профиль подписи — это файл, который связывает сертификат разработчика, список разрешённых устройств и набор entitlements для конкретного приложения. При установке приложения система сверяет entitlements в коде с entitlements в профиле подписи. Если entitlement присутствует в коде, но отсутствует в профиле, приложение не получит доступ к соответствующей функции.

Для диагностики проблем с entitlements в первую очередь проверяйте профиль подписи. Xcode автоматически генерирует профили на основе выбранных capability на портале Apple Developer. Если capability добавлена в Xcode, но не активна на портале, приложение будет падать с ошибкой подписи при попытке использовать защищённую функцию.