Provisioning Profile: що це, які бувають типи та як працює

Що таке Provisioning Profile

Provisioning Profile — це цифровий конфігураційний файл формату .mobileprovision (для iOS) або .provisionprofile (для macOS), який Apple використовує для контролю встановлення та запуску застосунків на пристроях. Профіль містить метадані підпису коду, без яких застосунок неможливо запустити на фізичному iPhone, iPad або Apple Watch — симулятор не потребує профілю, оскільки код не підписується для виконання на реальному процесорі.

Профіль випускається через Apple Developer Portal і має термін дії — зазвичай один рік для Development і Distribution профілів. Згідно з політикою Apple, профіль автоматично пов'язується із сертифікатом Apple Developer Program, під яким він підписаний: якщо сертифікат відкликано або термін його дії закінчився, профіль перестає працювати.

Кожен профіль містить унікальний UUID, який Xcode використовує для ідентифікації профілю у зв'язці ключів. Xcode автоматично обирає відповідний профіль під час збірки, але розробник може перевизначити вибір у налаштуваннях Signing & Capabilities. На одному пристрої може бути встановлено необмежену кількість профілів — система керування пристроями Apple (MDM) використовує це для корпоративного розповсюдження застосунків.

Навіщо потрібен Provisioning Profile

Підпис коду — основна причина існування профілів. Apple вимагає, щоб кожен застосунок, який запускається на пристрої з iOS, був підписаний сертифікатом, випущеним Apple. Provisioning Profile виступає сполучною ланкою: він підтверджує, що розробник має право запускати застосунок на цьому пристрої. За даними Apple Security Guide (2025), механізм профілів запобігає встановленню шкідливого ПЗ на пристрої користувачів навіть у разі компрометації сертифіката розробника.

Профіль також визначає, які системні сервіси доступні застосунку. Якщо застосунок використовує Push-сповіщення, Apple Push Notification service (APNs) вимагає коректних entitlements усередині профілю. Без цього серверні сповіщення не будуть доставлені на пристрій. Аналогічне правило діє для iCloud, App Groups, Wallet, HealthKit та інших фреймворків Apple.

Відмінність від сертифіката

Розробники часто плутають Provisioning Profile і Apple Certificate. Сертифікат — це цифровий документ, що підтверджує особу (хто підписує), а профіль — це конфігурація (який застосунок, на яких пристроях, з якими правами). Один сертифікат може використовуватися в кількох профілях, а один профіль прив'язаний рівно до одного сертифіката. Apple рекомендує створювати окремий профіль для кожного застосунку та кожного сценарію — Development, Ad Hoc, App Store.

Як працює Provisioning Profile

Процес підпису застосунку складається з кількох кроків, які виконуються послідовно. Xcode бере бінарний файл застосунку (App Bundle), підписує його закритим ключем розробника, вбудовує в нього Provisioning Profile і надсилає на пристрій. Пристрій перевіряє підпис публічним ключем Apple, звіряє UUID профілю зі списком довірених профілів у системі та запускає застосунок лише у разі успіху всіх перевірок.

Коли користувач завантажує застосунок із App Store, механізм відрізняється. App Store Connect перепідписує застосунок власним Distribution сертифікатом Apple, замінюючи профіль розробника на Store-профіль. Це означає, що застосунок, опублікований через App Store, технічно підписаний Apple, а не розробником — хоча початковий підпис розробника перевіряється на етапі завантаження збірки в App Store Connect.

Для Ad Hoc розповсюдження профіль реєструє конкретні UDID пристроїв, на яких дозволено запуск. Apple Developer Program безкоштовного акаунта обмежує 100 пристроїв на рік для тестування. Enterprise профілі (для внутрішнього розповсюдження в організації) не мають обмежень за кількістю пристроїв, але вимагають активної підписки Apple Developer Enterprise Program вартістю $299 на рік.

Життєвий цикл профілю

Термін дії Provisioning Profile становить один рік із моменту створення. За 30 днів до завершення Apple починає надсилати push-сповіщення розробнику через Xcode і Developer Portal. Якщо термін дії профілю закінчився, застосунок на пристрої продовжує працювати (якщо вже встановлений), але нову збірку з цим профілем встановити не вдасться. Xcode під час спроби збірки з профілем, термін дії якого закінчився, видає помилку code signing з кодом -402620394. Apple рекомендує налаштувати автоматичне продовження профілів через Xcode Accounts Preferences — тоді Xcode оновлює профіль за 24 години до завершення терміну дії.

Типи Provisioning Profile

Apple надає чотири основні типи Provisioning Profile, кожен із яких призначений для конкретного етапу життєвого циклу застосунку. Development профіль дозволяє запускати застосунок на фізичних пристроях, доданих в Apple Developer Portal, і використовується на етапі розробки та QA-тестування. Для створення Development профілю достатньо безкоштовного акаунта розробника Apple.

Ad Hoc профіль призначений для розповсюдження застосунку серед обмеженого кола тестувальників без використання App Store. Профіль реєструє до 100 пристроїв за UDID, і застосунок може бути встановлений безпосередньо через iTunes, Apple Configurator або MDM-рішення. Ad Hoc збірки мають термін дії 12 місяців і не вимагають проходження рев'ю Apple.

App Store профіль використовується виключно для публікації застосунку в App Store і не містить списку пристроїв — Apple сама керує розповсюдженням після схвалення збірки. Під час завантаження архіву в App Store Connect Xcode автоматично використовує App Store профіль, якщо він встановлений у системі. Enterprise профіль призначений для організацій з Apple Developer Enterprise Program і дозволяє розповсюджувати застосунки всередині компанії без обмежень за кількістю пристроїв і без рев'ю Apple.

Структура Provisioning Profile

Provisioning Profile являє собою файл у DER-форматі, підписаний Apple, вміст якого можна переглянути через командний рядок. Security framework macOS дозволяє декодувати .mobileprovision у читабельний XML-пліст. Усередині профілю містяться: UUID профілю, App ID (префікс команди + Bundle Identifier), список сертифікатів, список дозволених пристроїв (тільки для Development і Ad Hoc), entitlements і термін дії.

App ID — унікальний ідентифікатор застосунку, що складається з Team ID (10 символів, присвоюється Apple) і Bundle Identifier (наприклад, com.example.myapp). App ID може бути explicit (точний збіг з Bundle Identifier) або wildcard (шаблон *.example.com для кількох застосунків). Apple не рекомендує використовувати wildcard для застосунків, які використовують Push-сповіщення або iCloud — ці сервіси вимагають explicit App ID.

Entitlements — XML-блок усередині профілю, який визначає права доступу застосунку до системних ресурсів. Типові entitlements включають: aps-environment (Push-сповіщення), com.apple.developer.icloud-services (iCloud), com.apple.security.application-groups (App Groups для Widget і Share Extension). Apple автоматично додає entitlements у профіль на основі ввімкнених Capabilities у Xcode. Будь-яка невідповідність між entitlements у профілі та тими, що запитуються в коді, призводить до помилки підпису.

Створення Provisioning Profile в Apple Developer

Створення профілю можливе двома способами: через веб-інтерфейс Apple Developer Portal або автоматично через Xcode. Для типового проєкту Xcode керує профілями автоматично, коли ввімкнено опцію Automatically manage signing. Xcode створює сертифікат, профіль і App ID за кілька секунд, синхронізуючись з Apple Developer Portal. Однак для CI/CD-пайплайнів потрібне ручне керування.

Для ручного створення профілю в Apple Developer Portal необхідно: перейти в розділ Certificates, Identifiers & Profiles, обрати Profiles і натиснути «+». Потім обрати тип профілю (Development, Ad Hoc, App Store або Enterprise), обрати App ID зі списку зареєстрованих, обрати сертифікат розробника та (для Development і Ad Hoc) обрати пристрої. Після створення профіль завантажується у форматі .mobileprovision і встановлюється подвійним кліком у Xcode.

CI/CD сервери потребують особливого підходу: профіль і сертифікат мають зберігатися в захищеному репозиторії (наприклад, у секретах GitHub Actions). Під час збірки профіль завантажується на агента, розміщується в папці ~/Library/MobileDevice/Provisioning Profiles, а сертифікат імпортується у зв'язку ключів. Fastlane — популярний інструмент для автоматизації підпису — надає команду match, яка синхронізує профілі та сертифікати між розробниками через зашифрований git-репозиторій.

Приклад: перевірка профілю через командний рядок

Для діагностики проблем із підписом коду можна декодувати .mobileprovision і перевірити його вміст. Команда нижче витягує XML-пліст із профілю та зберігає у читабельному форматі:

# Декодування .mobileprovision у XML
security cms -D -i "path/to/embedded.mobileprovision" \
  -o "profile.plist"

# Перевірка терміну дії профілю
plist -convert xml1 profile.plist -o -
grep -A 1 "ExpirationDate" profile.plist

Security утиліта зі складу macOS Command Line Tools декодує CMS-підписаний файл профілю. Прапорець -D означає декодування, -i — вхідний файл. Після декодування утиліта plist конвертує бінарний plist у XML, а grep витягує дату завершення терміну дії. Цей метод корисний у CI/CD для перевірки, що профіль не прострочений перед збіркою релізу.

Типові помилки з Provisioning Profile

Найпоширеніша помилка — «No matching provisioning profiles found» під час збірки в Xcode. Вона виникає, коли Xcode не може знайти профіль, що відповідає конфігурації збірки: Bundle Identifier не збігається з App ID у профілі, сертифікат не встановлений у зв'язці ключів або термін дії профілю закінчився. Рішення — перевірити налаштування Signing & Capabilities у таргеті та за потреби перемкнутися на Automatically manage signing.

Помилка «Provisioning profile doesn't include the selected device» з'являється під час спроби запустити Development або Ad Hoc збірку на пристрої, UDID якого не доданий у профіль. Apple Developer Portal дозволяє додати пристрій до наявного профілю — після цього профіль потрібно завантажити повторно та встановити заново. Xcode під час автоматичного керування підписом додає підключений пристрій у профіль автоматично.

Проблема з entitlements проявляється помилкою «The executable was signed with invalid entitlements» під час вивантаження в App Store Connect. Причина — невідповідність entitlements у профілі та у файлі .entitlements проєкту. Apple вимагає, щоб набір прав у профілі був надмножиною прав, які запитує застосунок. Рішення — перевірити Capabilities у таргеті Xcode і переконатися, що всі ввімкнені сервіси мають відповідні entitlements у профілі. Fastlane включає команду produce, яка синхронізує App ID і профілі з актуальними entitlements.