Provisioning Profile: co to jest, jakie są rodzaje i jak działa

Czym jest Provisioning Profile

Provisioning Profile to cyfrowy plik konfiguracyjny w formacie .mobileprovision (dla iOS) lub .provisionprofile (dla macOS), którego Apple używa do kontroli instalowania i uruchamiania aplikacji na urządzeniach. Profil zawiera metadane podpisywania kodu, bez których nie można uruchomić aplikacji na fizycznym iPhone, iPad lub Apple Watch — symulator nie wymaga profilu, ponieważ kod nie jest podpisywany do działania na prawdziwym procesorze.

Profil jest wydawany przez Apple Developer Portal i ma okres ważności — zwykle jeden rok dla profili Development i Distribution. Zgodnie z polityką Apple profil jest automatycznie powiązany z certyfikatem Apple Developer Program, pod którym został podpisany: jeśli certyfikat zostanie odwołany lub wygaśnie, profil przestaje działać.

Każdy profil zawiera unikalny UUID, którego Xcode używa do identyfikacji profilu w pęku kluczy. Xcode automatycznie wybiera odpowiedni profil podczas budowania, ale deweloper może zmienić wybór w ustawieniach Signing & Capabilities. Na jednym urządzeniu można zainstalować nieograniczoną liczbę profili — system zarządzania urządzeniami Apple (MDM) wykorzystuje to do korporacyjnej dystrybucji aplikacji.

Po co jest Provisioning Profile

Podpisywanie kodu to główny powód istnienia profili. Apple wymaga, aby każda aplikacja uruchamiana na urządzeniu z iOS była podpisana certyfikatem wydanym przez Apple. Provisioning Profile jest ogniwem łączącym: potwierdza, że deweloper ma prawo uruchamiać aplikację na danym urządzeniu. Według Apple Security Guide (2025) mechanizm profili zapobiega instalowaniu złośliwego oprogramowania na urządzeniach użytkowników nawet w przypadku kompromitacji certyfikatu dewelopera.

Profil określa również, które usługi systemowe są dostępne dla aplikacji. Jeśli aplikacja korzysta z powiadomień Push, Apple Push Notification service (APNs) wymaga poprawnych entitlements w profilu. Bez tego powiadomienia serwerowe nie zostaną dostarczone na urządzenie. Podobna zasada obowiązuje dla iCloud, App Groups, Wallet, HealthKit i innych frameworków Apple.

Różnica od certyfikatu

Deweloperzy często mylą Provisioning Profile z Apple Certificate. Certyfikat to dokument cyfrowy potwierdzający tożsamość (kto podpisuje), a profil to konfiguracja (jaka aplikacja, na jakich urządzeniach, z jakimi uprawnieniami). Jeden certyfikat może być używany w kilku profilach, a jeden profil jest powiązany z dokładnie jednym certyfikatem. Apple zaleca tworzenie osobnego profilu dla każdej aplikacji i każdego scenariusza — Development, Ad Hoc, App Store.

Jak działa Provisioning Profile

Proces podpisywania aplikacji składa się z kilku kroków wykonywanych sekwencyjnie. Xcode pobiera plik binarny aplikacji (App Bundle), podpisuje go prywatnym kluczem dewelopera, osadza w nim Provisioning Profile i wysyła na urządzenie. Urządzenie sprawdza podpis publicznym kluczem Apple, porównuje UUID profilu z listą zaufanych profili w systemie i uruchamia aplikację tylko wtedy, gdy wszystkie kontrole zakończą się sukcesem.

Kiedy użytkownik pobiera aplikację z App Store, mechanizm jest inny. App Store Connect ponownie podpisuje aplikację własnym certyfikatem Distribution firmy Apple, zastępując profil dewelopera profilem Store. Oznacza to, że aplikacja opublikowana przez App Store jest technicznie podpisana przez Apple, a nie przez dewelopera — chociaż pierwotny podpis dewelopera jest sprawdzany na etapie przesyłania buildu do App Store Connect.

W przypadku dystrybucji Ad Hoc profil rejestruje konkretne UDID urządzeń, na których dozwolone jest uruchamianie. Bezpłatne konto Apple Developer Program ogranicza 100 urządzeń rocznie do testowania. Profile Enterprise (do dystrybucji wewnętrznej w organizacji) nie mają ograniczenia liczby urządzeń, ale wymagają aktywnej subskrypcji Apple Developer Enterprise Program kosztującej $299 rocznie.

Cykl życia profilu

Okres ważności Provisioning Profile wynosi jeden rok od momentu utworzenia. Na 30 dni przed wygaśnięciem Apple zaczyna wysyłać deweloperowi powiadomienia push przez Xcode i Developer Portal. Jeśli profil wygaśnie, aplikacja na urządzeniu nadal działa (jeśli została już zainstalowana), ale nowego buildu z tym profilem nie da się zainstalować. Xcode podczas próby budowania z wygasłym profilem zwraca błąd podpisywania kodu o kodzie -402620394. Apple zaleca skonfigurowanie automatycznego odnawiania profili przez Xcode Accounts Preferences — wtedy Xcode aktualizuje profil 24 godziny przed wygaśnięciem.

Rodzaje Provisioning Profile

Apple udostępnia cztery główne typy Provisioning Profile, z których każdy jest przeznaczony do konkretnego etapu cyklu życia aplikacji. Development profil pozwala uruchamiać aplikację na fizycznych urządzeniach dodanych do Apple Developer Portal i jest używany na etapie rozwoju i testów QA. Do utworzenia profilu Development wystarczy bezpłatne konto deweloperskie Apple.

Ad Hoc profil jest przeznaczony do dystrybucji aplikacji wśród ograniczonego grona testerów bez korzystania z App Store. Profil rejestruje do 100 urządzeń według UDID, a aplikację można zainstalować bezpośrednio przez iTunes, Apple Configurator lub rozwiązania MDM. Ad Hoc buildy mają okres ważności 12 miesięcy i nie wymagają przejścia review Apple.

App Store profil jest używany wyłącznie do publikowania aplikacji w App Store i nie zawiera listy urządzeń — Apple sama zarządza dystrybucją po zatwierdzeniu buildu. Podczas przesyłania archiwum do App Store Connect Xcode automatycznie używa profilu App Store, jeśli jest zainstalowany w systemie. Enterprise profil jest przeznaczony dla organizacji z Apple Developer Enterprise Program i umożliwia dystrybucję aplikacji w firmie bez ograniczenia liczby urządzeń i bez review Apple.

Struktura Provisioning Profile

Provisioning Profile to plik w formacie DER podpisany przez Apple, którego zawartość można przeglądać za pomocą wiersza poleceń. Security framework systemu macOS umożliwia zdekodowanie .mobileprovision do czytelnego pliku XML plist. Wewnątrz profilu znajdują się: UUID profilu, App ID (prefiks zespołu + Bundle Identifier), lista certyfikatów, lista dozwolonych urządzeń (tylko dla Development i Ad Hoc), entitlements i okres ważności.

App ID to unikalny identyfikator aplikacji składający się z Team ID (10 znaków, nadawany przez Apple) i Bundle Identifier (na przykład com.example.myapp). App ID może być explicit (dokładne dopasowanie do Bundle Identifier) lub wildcard (wzorzec *.example.com dla wielu aplikacji). Apple nie zaleca używania wildcard dla aplikacji korzystających z powiadomień Push lub iCloud — te usługi wymagają jawnego App ID.

Entitlements to blok XML w profilu, który określa prawa dostępu aplikacji do zasobów systemowych. Typowe entitlements obejmują: aps-environment (powiadomienia Push), com.apple.developer.icloud-services (iCloud), com.apple.security.application-groups (App Groups dla Widget i Share Extension). Apple automatycznie dodaje entitlements do profilu na podstawie włączonych Capabilities w Xcode. Wszelka niezgodność między entitlements w profilu a wymaganymi w kodzie prowadzi do błędu podpisywania.

Tworzenie Provisioning Profile w Apple Developer

Tworzenie profilu jest możliwe na dwa sposoby: przez interfejs internetowy Apple Developer Portal lub automatycznie przez Xcode. W typowym projekcie Xcode zarządza profilami automatycznie, gdy włączona jest opcja Automatically manage signing. Xcode tworzy certyfikat, profil i App ID w kilka sekund, synchronizując się z Apple Developer Portal. Jednak w przypadku potoków CI/CD wymagane jest ręczne zarządzanie.

Do ręcznego utworzenia profilu w Apple Developer Portal należy: przejść do sekcji Certificates, Identifiers & Profiles, wybrać Profiles i kliknąć „+". Następnie wybrać typ profilu (Development, Ad Hoc, App Store lub Enterprise), wybrać App ID z listy zarejestrowanych, wybrać certyfikat dewelopera i (dla Development i Ad Hoc) wybrać urządzenia. Po utworzeniu profil jest pobierany w formacie .mobileprovision i instalowany dwuklikiem w Xcode.

Serwery CI/CD wymagają szczególnego podejścia: profil i certyfikat powinny być przechowywane w zabezpieczonym repozytorium (na przykład w sekretach GitHub Actions). Podczas budowania profil jest ładowany na agenta, umieszczany w folderze ~/Library/MobileDevice/Provisioning Profiles, a certyfikat jest importowany do pęku kluczy. Fastlane — popularne narzędzie do automatyzacji podpisywania — udostępnia polecenie match, które synchronizuje profile i certyfikaty między deweloperami przez zaszyfrowane repozytorium git.

Przykład: sprawdzanie profilu przez wiersz poleceń

Do diagnozowania problemów z podpisywaniem kodu można zdekodować .mobileprovision i sprawdzić jego zawartość. Poniższe polecenie wyodrębnia plik XML plist z profilu i zapisuje go w czytelnym formacie:

# Dekodowanie .mobileprovision do XML
security cms -D -i "path/to/embedded.mobileprovision" \
  -o "profile.plist"

# Sprawdzanie okresu ważności profilu
plist -convert xml1 profile.plist -o -
grep -A 1 "ExpirationDate" profile.plist

Security narzędzie z pakietu macOS Command Line Tools dekoduje podpisany plik CMS profilu. Flaga -D oznacza dekodowanie, -i — plik wejściowy. Po dekodowaniu narzędzie plist konwertuje binarny plist do XML, a grep wyodrębnia datę wygaśnięcia. Ta metoda jest przydatna w CI/CD do sprawdzania, czy profil nie jest przeterminowany przed budowaniem wersji wydawniczej.

Typowe błędy z Provisioning Profile

Najczęstszy błąd to „No matching provisioning profiles found" podczas budowania w Xcode. Pojawia się, gdy Xcode nie może znaleźć profilu pasującego do konfiguracji budowania: Bundle Identifier nie pasuje do App ID w profilu, certyfikat nie jest zainstalowany w pęku kluczy lub profil wygasł. Rozwiązanie — sprawdzić ustawienia Signing & Capabilities w target i w razie potrzeby przełączyć się na Automatically manage signing.

Błąd „Provisioning profile doesn't include the selected device" pojawia się przy próbie uruchomienia buildu Development lub Ad Hoc na urządzeniu, którego UDID nie został dodany do profilu. Apple Developer Portal umożliwia dodanie urządzenia do istniejącego profilu — po tym profil należy ponownie pobrać i zainstalować. Xcode przy automatycznym zarządzaniu podpisem dodaje podłączone urządzenie do profilu automatycznie.

Problem z entitlements objawia się błędem „The executable was signed with invalid entitlements" przy przesyłaniu do App Store Connect. Przyczyną jest niezgodność entitlements w profilu z plikiem .entitlements projektu. Apple wymaga, aby zestaw uprawnień w profilu był nadzbiorem uprawnień żądanych przez aplikację. Rozwiązanie — sprawdzić Capabilities w target Xcode i upewnić się, że wszystkie włączone usługi mają odpowiednie entitlements w profilu. Fastlane zawiera polecenie produce, które synchronizuje App ID i profile z aktualnymi entitlements.