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 при опит за компилиране с изтекъл профил издава грешка при подписване на кода с код -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 рамката на macOS позволява декодиране на .mobileprovision в четим XML plist. Вътре в профила се съдържат: 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 — тези услуги изискват явен 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 plist от профила и го записва в четим формат:

# Декодиране на .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 за проверка дали профилът не е изтекъл преди компилирането на release билда.

Типични грешки с Provisioning Profile

Най-честата грешка е „No matching provisioning profiles found" при компилиране в Xcode. Появява се, когато Xcode не може да намери профил, съответстващ на конфигурацията за компилиране: Bundle Identifier не съвпада с App ID в профила, сертификатът не е инсталиран в ключодържателя или профилът е изтекъл. Решение — проверете настройките Signing & Capabilities в target и при необходимост преминете на 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 в target на Xcode и се уверете, че всички активирани услуги имат съответните entitlements в профила. Fastlane включва командата produce, която синхронизира App ID и профилите с актуалните entitlements.