Entitlements w programowaniu dla iOS: co to jest, jakie są rodzaje i jak je skonfigurować

Czym są Entitlements?

Entitlements (w tłumaczeniu z angielskiego — „uprawnienia") to para klucz-wartość, która jest dołączana do podpisu kodu aplikacji na etapie budowania i określa, do jakich funkcji systemowych i danych aplikacja ma dostęp. Entitlements są wbudowane w model bezpieczeństwa Apple od czasu pojawienia się iOS SDK i są obowiązkowe dla wszystkich aplikacji dystrybuowanych przez App Store.

Koncepcja Entitlements różni się od tradycyjnych uprawnień (permissions) w Androidzie. O ile uprawnienia Androida są pytane od użytkownika w momencie pierwszego użycia funkcji, Entitlements w iOS są sprawdzane przez system przy uruchomieniu aplikacji na podstawie podpisu cyfrowego. Użytkownik nie może cofnąć ani zmienić entitlement — to uprawnienie jest przyznawane developerowi przez App Store Connect i przypisywane w profilu podpisu.

Każdy entitlement ma ściśle określone przeznaczenie i format. Na przykład com.apple.security.application-groups pozwala na dostęp do wspólnego kontenera dla zestawu aplikacji jednego developera, a aps-environment włącza obsługę powiadomień Push. Apple ręcznie recenzuje wnioski o entitlements w procesie App Review, co zapobiega nadużywaniu uprawnień.

Rodzaje Entitlements w iOS

Entitlements są klasyfikowane według przeznaczenia funkcjonalnego na kilka kategorii. Usługi systemowe — iCloud, Push Notifications, Siri. Bezpieczeństwo i dane — Keychain Access Groups, App Groups, Data Protection. Sieć i łączność — Multipath TCP, VPN, Hotspot Configuration. Możliwości sprzętowe — Camera, Microphone, Bluetooth (poprzez powiązane capabilities).

Capabilities i serwisowe Entitlements

Xcode grupuje powiązane entitlements w Capabilities — wysokopoziomowe przełączniki na zakładce Signing & Capabilities. Włączenie Capability automatycznie dodaje niezbędne entitlements do pliku .entitlements. Na przykład włączenie Capability Push Notifications dodaje entitlement aps-environment z wartością development lub production, a włączenie iCloud dodaje zestaw entitlements dla CloudKit i Key-Value storage.

Niektóre capabilities wymagają dodatkowej konfiguracji na portalu Apple Developer. Na przykład dla App Groups należy zarejestrować identyfikator grupy na portalu, po czym staje się on dostępny do wyboru w Xcode. Dla Push Notifications wymagane jest wygenerowanie klucza APNs lub certyfikatu. Bez tych wstępnych kroków entitlement nie będzie działać nawet przy poprawnym pliku .entitlements.

App Groups i Keychain Access

Entitlement com.apple.security.application-groups pozwala kilku aplikacjom jednego developera na wspólny kontener w systemie plików. Jest to używane do współdzielenia danych między główną aplikacją a rozszerzeniami (Widget, Watch App, Share Extension). Wszystkie aplikacje z jednej grupy mogą odczytywać i zapisywać pliki w wspólnym katalogu /Library/Group Containers/.

Keychain Access Groups (klucz keychain-access-groups) — kolejny ważny entitlement, pozwalający aplikacjom z jednej grupy na wspólny dostęp do elementów Keychain. Jest to kluczowe dla implementacji jednolitego uwierzytelniania: użytkownik loguje się w jednej aplikacji i automatycznie uzyskuje dostęp do tego samego konta w innej aplikacji bez ponownego wprowadzania hasła.

Jak skonfigurować Entitlements

Konfiguracja Entitlements odbywa się w Xcode na zakładce Signing & Capabilities w ustawieniach targetu. Developer wybiera potrzebne Capabilities z listy, a Xcode automatycznie tworzy lub aktualizuje plik .entitlements. Ten plik jest przechowywany w projekcie w formacie XML o strukturze plist i zawiera wszystkie klucze entitlements dla danego targetu.

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

Przy ręcznym tworzeniu pliku entitlement ważne jest przestrzeganie formatu kluczy i prefiksów. Entitlements Apple używają odwrotnego stylu domenowego (com.apple.*). Niestandardowe entitlements do własnych celów również są możliwe, ale muszą być zarejestrowane na portalu developerskim. Xcode zapewnia autouzupełnianie dla wszystkich standardowych kluczy entitlements.

Do debugowania Entitlements użyj polecenia codesign w terminalu macOS. Polecenie codesign -d --entitlements :- <ścieżka_do_aplikacji> wyświetla wszystkie entitlements, którymi podpisano aplikację. Jest to przydatne do diagnozowania problemów: jeśli entitlement nie występuje w wynikach, aplikacja nie uzyska dostępu do odpowiedniej funkcji niezależnie od ustawień w Xcode.

Ręczne tworzenie pliku entitlement

Chociaż Xcode generuje plik entitlement automatycznie przy włączaniu Capabilities, doświadczeni developerzy często tworzą lub edytują go ręcznie w celu precyzyjnego dostrojenia. Plik ma rozszerzenie .entitlements i format plist (XML). Można w nim dodawać niestandardowe klucze entitlement, które nie są dostępne w interfejsie Xcode, lub łączyć entitlements z różnych capabilities w jednym pliku.

Przy ręcznym edytowaniu ważne jest dbanie o poprawność składniową XML. Błąd w strukturze plist spowoduje, że entitlements nie zostaną zastosowane przy podpisywaniu. Xcode sprawdza plik .entitlements na etapie kompilacji i wyświetla błąd przy nieprawidłowym formacie. Dla złożonych projektów z wieloma targetami i rozszerzeniami zaleca się przechowywanie wspólnych kluczy entitlement w osobnych plikach i importowanie ich przez Build Settings.

// cli: sprawdzanie entitlements zainstalowanej aplikacji
codesign -d --entitlements :- /Applications/Safari.app

// Przykładowe wyjście zawiera listę aktywnych entitlements
<dict>
    <key>com.apple.security.ts.apple-wifi</key>
    <true/>
    <key>com.apple.security.network.client</key>
    <true/>
</dict>

Entitlements a bezpieczeństwo aplikacji

Entitlements odgrywają kluczową rolę w modelu bezpieczeństwa Apple. Ponieważ entitlements są częścią podpisu cyfrowego aplikacji, ich fałszowanie jest niemożliwe bez ponownego podpisania kodu. Apple sprawdza entitlements na kilku poziomach: przy budowaniu Xcode podpisuje entitlements wraz z plikiem wykonywalnym, przy instalacji system sprawdza integralność podpisu, a przy uruchomieniu — ponownie weryfikuje entitlements.

Jednym z ważnych wymogów bezpieczeństwa jest zasada minimalnego entitlement. Developer powinien włączać tylko te entitlements, które są rzeczywiście używane w aplikacji. Zbędne entitlements zwiększają powierzchnię ataku i mogą spowodować odrzucenie aplikacji podczas App Review. Apple wyraźnie sprawdza zgodność entitlements z funkcjonalnością aplikacji.

Niektóre entitlements są uważane za wrażliwe (sensitive) i wymagają dodatkowej zgody Apple. Należą do nich: com.apple.developer.healthkit (HealthKit), com.apple.developer.passkit (Wallet), com.apple.developer.authentication-services.authentication (Sign in with Apple) oraz com.apple.developer.nfc.readersession.formats (NFC). Aby uzyskać te entitlements, należy uzasadnić ich potrzebę w procesie App Review.

Przy pracy z entitlements ważne jest uwzględnienie różnic między iOS a macOS. Aplikacje desktopowe macOS (Sandboxed) mają szerszy zestaw entitlements w porównaniu z iOS. Na przykład entitlement com.apple.security.temporary-exception.* pozwala tymczasowo ominąć sandbox dla określonych operacji — w iOS takie entitlements w ogóle nie występują.

Entitlements a Provisioning Profile

Entitlements są ściśle powiązane z profilami podpisu (Provisioning Profiles). Profil podpisu to plik, który łączy certyfikat developera, listę dozwolonych urządzeń i zestaw entitlements dla konkretnej aplikacji. Przy instalacji aplikacji system porównuje entitlements w kodzie z entitlements w profilu podpisu. Jeśli entitlement występuje w kodzie, ale brak go w profilu, aplikacja nie uzyska dostępu do odpowiedniej funkcji.

Do diagnozowania problemów z entitlements w pierwszej kolejności sprawdzaj profil podpisu. Xcode automatycznie generuje profile na podstawie wybranych capability na portalu Apple Developer. Jeśli capability została dodana w Xcode, ale nie jest aktywna na portalu, aplikacja będzie zawieszać się z błędem podpisu przy próbie użycia chronionej funkcji.