Entitlements no desenvolvimento iOS: o que são, tipos e como configurar

O que são Entitlements?

Entitlements (traduzido do inglês como “direitos”) são pares chave-valor incluídos na assinatura de código do aplicativo durante a compilação que determinam a quais capacidades e dados do sistema o aplicativo pode acessar. Os Entitlements fazem parte do modelo de segurança da Apple desde a introdução do iOS SDK e são obrigatórios para todos os aplicativos distribuídos através da App Store.

O conceito de Entitlements difere das permissões tradicionais no Android. Enquanto as permissões do Android são solicitadas ao usuário no momento do primeiro uso de um recurso, os Entitlements no iOS são verificados pelo sistema na inicialização do aplicativo com base na assinatura digital. O usuário não pode revogar ou alterar um entitlement — este direito é concedido ao desenvolvedor através do App Store Connect e incorporado no perfil de provisionamento.

Cada entitlement tem um propósito e formato estritamente definidos. Por exemplo, com.apple.security.application-groups permite o acesso a um contêiner compartilhado para um conjunto de aplicativos do mesmo desenvolvedor, enquanto aps-environment habilita o suporte a Notificações Push. A Apple revisa manualmente as solicitações de entitlements durante o processo de App Review, o que impede o abuso de direitos.

Tipos de Entitlements no iOS

Os Entitlements são classificados por propósito funcional em várias categorias. Serviços do Sistema — iCloud, Push Notifications, Siri. Segurança e Dados — Keychain Access Groups, App Groups, Data Protection. Rede e Comunicação — Multipath TCP, VPN, Hotspot Configuration. Capacidades de Hardware — Câmera, Microfone, Bluetooth (através de capabilities relacionadas).

Capabilities e Entitlements de Serviço

O Xcode agrupa entitlements relacionados em Capabilities — interruptores de alto nível na guia Signing & Capabilities. Habilitar uma Capability adiciona automaticamente os entitlements necessários ao arquivo .entitlements. Por exemplo, habilitar a capability Push Notifications adiciona o entitlement aps-environment com valor development ou production, enquanto habilitar iCloud adiciona um conjunto de entitlements para CloudKit e armazenamento Key-Value.

Algumas capabilities exigem configuração adicional no portal Apple Developer. Por exemplo, App Groups requer o registro de um identificador de grupo no portal, após o que ele se torna disponível para seleção no Xcode. Para Push Notifications, é necessário gerar uma chave ou certificado APNs. Sem essas etapas prévias, o entitlement não funcionará mesmo com um arquivo .entitlements correto.

App Groups e Acesso ao Keychain

O entitlement com.apple.security.application-groups permite que vários aplicativos do mesmo desenvolvedor compartilhem um contêiner comum no sistema de arquivos. É usado para compartilhar dados entre o aplicativo principal e as extensões (Widget, Watch App, Share Extension). Todos os aplicativos do mesmo grupo podem ler e gravar arquivos no diretório compartilhado /Library/Group Containers/.

Keychain Access Groups (chave keychain-access-groups) é outro entitlement importante que permite que aplicativos do mesmo grupo compartilhem acesso a itens do Keychain. Isso é crítico para implementar logon único: o usuário faz login em um aplicativo e obtém acesso automaticamente à mesma conta em outro aplicativo sem redigitar a senha.

Como Configurar Entitlements

A configuração de Entitlements é feita no Xcode na guia Signing & Capabilities nas configurações do target. O desenvolvedor seleciona as Capabilities necessárias da lista, e o Xcode cria ou atualiza automaticamente o arquivo .entitlements. Este arquivo é armazenado no projeto em formato XML com estrutura plist e contém todas as chaves de entitlement para esse target.

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

Ao criar um arquivo entitlement manualmente, é importante seguir o formato de chaves e os prefixos. Os entitlements da Apple usam um estilo de domínio reverso (com.apple.*). Entitlements personalizados para seus próprios fins também são possíveis, mas devem ser registrados no portal do desenvolvedor. O Xcode fornece autocompletar para todas as chaves de entitlement padrão.

Para depurar Entitlements, use o comando codesign no terminal do macOS. O comando codesign -d --entitlements :- <caminho_do_aplicativo> exibe todos os entitlements com os quais o aplicativo foi assinado. Isso é útil para diagnosticar problemas: se um entitlement estiver ausente na saída, o aplicativo não obterá acesso à função correspondente independentemente das configurações do Xcode.

Criando um Arquivo Entitlement Manualmente

Embora o Xcode gere o arquivo entitlement automaticamente ao habilitar Capabilities, desenvolvedores experientes frequentemente o criam ou editam manualmente para ajustes finos. O arquivo tem a extensão .entitlements e formato plist (XML). Nele, podem ser adicionadas chaves de entitlement personalizadas que não estão presentes na interface do Xcode, ou combinar entitlements de diferentes capabilities em um único arquivo.

Ao editar manualmente, é importante garantir a correção sintática do XML. Um erro na estrutura plist fará com que os entitlements não sejam aplicados durante a assinatura. O Xcode verifica o arquivo .entitlements em tempo de compilação e exibe um erro se o formato estiver incorreto. Para projetos complexos com múltiplos targets e extensões, é recomendável armazenar as chaves de entitlement comuns em arquivos separados e importá-las através das Build Settings.

// cli: checking entitlements of an installed application
codesign -d --entitlements :- /Applications/Safari.app

// Example output contains a list of active entitlements
<dict>
    <key>com.apple.security.ts.apple-wifi</key>
    <true/>
    <key>com.apple.security.network.client</key>
    <true/>
</dict>

Entitlements e Segurança do Aplicativo

Os Entitlements desempenham um papel fundamental no modelo de segurança da Apple. Como os entitlements fazem parte da assinatura digital do aplicativo, sua falsificação é impossível sem re-assinar o código. A Apple verifica os entitlements em vários níveis: durante a compilação, o Xcode assina os entitlements junto com o arquivo executável; durante a instalação, o sistema verifica a integridade da assinatura; na inicialização, re-verifica os entitlements.

Um requisito importante de segurança é o princípio do mínimo entitlement. O desenvolvedor deve incluir apenas os entitlements que são realmente usados no aplicativo. Entitlements desnecessários aumentam a superfície de ataque e podem causar a rejeição do aplicativo durante o App Review. A Apple verifica explicitamente se os entitlements correspondem à funcionalidade do aplicativo.

Alguns entitlements são considerados sensíveis e exigem aprovação adicional da Apple. Estes incluem: com.apple.developer.healthkit (HealthKit), com.apple.developer.passkit (Wallet), com.apple.developer.authentication-services.authentication (Sign in with Apple) e com.apple.developer.nfc.readersession.formats (NFC). Para obter esses entitlements, é necessário justificar sua necessidade durante o processo de App Review.

Ao trabalhar com entitlements, é importante considerar as diferenças entre iOS e macOS. Os aplicativos de desktop macOS (Sandboxed) têm um conjunto mais amplo de entitlements em comparação com o iOS. Por exemplo, o entitlement com.apple.security.temporary-exception.* permite contornar temporariamente a sandbox para certas operações — tais entitlements estão completamente ausentes no iOS.

Entitlements e Perfis de Provisionamento

Os Entitlements estão intimamente ligados aos Perfis de Provisionamento (Provisioning Profiles). Um perfil de provisionamento é um arquivo que vincula o certificado do desenvolvedor, uma lista de dispositivos permitidos e um conjunto de entitlements para um aplicativo específico. Ao instalar um aplicativo, o sistema compara os entitlements no código com os entitlements no perfil de provisionamento. Se um entitlement estiver presente no código mas ausente no perfil, o aplicativo não obterá acesso à função correspondente.

Para diagnosticar problemas com entitlements, primeiro verifique o perfil de provisionamento. O Xcode gera automaticamente perfis com base nas capabilities selecionadas no portal Apple Developer. Se uma capability for adicionada no Xcode mas não estiver ativa no portal, o aplicativo travará com um erro de assinatura ao tentar usar uma função protegida.