Perfil de Provisionamento: o que é, quais os tipos e como funciona

O que é um Perfil de Provisionamento

Um Perfil de Provisionamento é um arquivo de configuração digital no formato .mobileprovision (para iOS) ou .provisionprofile (para macOS) que a Apple usa para controlar a instalação e execução de aplicativos em dispositivos. O perfil contém metadados de assinatura de código, sem os quais o aplicativo não pode ser executado em um iPhone, iPad ou Apple Watch físicos — o simulador não requer perfil porque o código não é assinado para execução em um processador real.

O perfil é emitido através do Apple Developer Portal e tem uma data de expiração — geralmente um ano para perfis Development e Distribution. De acordo com a política da Apple, o perfil é automaticamente vinculado ao certificado do Apple Developer Program sob o qual foi assinado: se o certificado for revogado ou expirar, o perfil para de funcionar.

Cada perfil contém um UUID único que o Xcode usa para identificar o perfil no chaveiro. Xcode seleciona automaticamente o perfil adequado durante a compilação, mas o desenvolvedor pode substituir a escolha nas configurações de Signing & Capabilities. Um número ilimitado de perfis pode ser instalado em um único dispositivo — o sistema de gerenciamento de dispositivos móveis (MDM) da Apple usa isso para distribuição corporativa de aplicativos.

Por que um Perfil de Provisionamento é necessário

A assinatura de código é a principal razão para a existência dos perfis. Apple exige que todo aplicativo executado em um dispositivo iOS seja assinado com um certificado emitido pela Apple. O Perfil de Provisionamento atua como um elo: confirma que o desenvolvedor tem o direito de executar o aplicativo naquele dispositivo. De acordo com o Apple Security Guide (2025), o mecanismo de perfis impede a instalação de malware nos dispositivos dos usuários mesmo em caso de comprometimento do certificado do desenvolvedor.

O perfil também determina quais serviços do sistema estão disponíveis para o aplicativo. Se o aplicativo usa Notificações Push, o Apple Push Notification service (APNs) requer entitlements corretos dentro do perfil. Sem isso, as notificações do servidor não serão entregues ao dispositivo. A mesma regra se aplica a iCloud, App Groups, Wallet, HealthKit e outros frameworks da Apple.

Diferença de um certificado

Os desenvolvedores frequentemente confundem Perfil de Provisionamento e Certificado Apple. Um certificado é um documento digital que confirma a identidade (quem assina), enquanto um perfil é uma configuração (qual aplicativo, em quais dispositivos, com quais permissões). Um certificado pode ser usado em vários perfis, e um perfil está vinculado exatamente a um certificado. A Apple recomenda criar um perfil separado para cada aplicativo e cada cenário — Development, Ad Hoc, App Store.

Como funciona um Perfil de Provisionamento

O processo de assinatura do aplicativo consiste em várias etapas sequenciais. Xcode pega o binário do aplicativo (App Bundle), assina com a chave privada do desenvolvedor, incorpora o Perfil de Provisionamento e o envia ao dispositivo. O dispositivo verifica a assinatura com a chave pública da Apple, compara o UUID do perfil com a lista de perfis confiáveis no sistema e executa o aplicativo somente se todas as verificações forem bem-sucedidas.

Quando um usuário baixa um aplicativo da App Store, o mecanismo é diferente. App Store Connect re-assina o aplicativo com seu próprio certificado Distribution da Apple, substituindo o perfil do desenvolvedor por um perfil da Store. Isso significa que um aplicativo publicado através da App Store é tecnicamente assinado pela Apple, não pelo desenvolvedor — embora a assinatura original do desenvolvedor seja verificada durante o upload da compilação no App Store Connect.

Para distribuição Ad Hoc, o perfil registra UDIDs de dispositivos específicos nos quais o aplicativo pode ser executado. Uma conta gratuita do Apple Developer Program limita os testes a 100 dispositivos por ano. Perfis Enterprise (para distribuição interna em uma organização) não têm limite de dispositivos, mas exigem uma assinatura ativa do Apple Developer Enterprise Program com custo de $299 por ano.

Ciclo de vida do perfil

O período de validade de um Perfil de Provisionamento é de um ano a partir da criação. 30 dias antes do vencimento, a Apple começa a enviar notificações push ao desenvolvedor através do Xcode e do Developer Portal. Se o perfil expirar, um aplicativo já instalado continua funcionando, mas uma nova compilação não pode ser instalada com esse perfil. Xcode exibe um erro de assinatura de código com código -402620394 ao tentar compilar com um perfil expirado. A Apple recomenda configurar a renovação automática de perfis através do Xcode Accounts Preferences — então o Xcode renova o perfil 24 horas antes do vencimento.

Tipos de Perfis de Provisionamento

A Apple oferece quatro tipos principais de Perfis de Provisionamento, cada um projetado para uma etapa específica do ciclo de vida do aplicativo. O perfil Development permite executar o aplicativo em dispositivos físicos adicionados ao Apple Developer Portal e é usado durante o desenvolvimento e testes de QA. Uma conta gratuita de desenvolvedor Apple é suficiente para criar um perfil Development.

O perfil Ad Hoc é projetado para distribuir o aplicativo a um grupo limitado de testadores sem usar a App Store. O perfil registra até 100 dispositivos por UDID, e o aplicativo pode ser instalado diretamente via iTunes, Apple Configurator ou soluções MDM. As compilações Ad Hoc têm período de validade de 12 meses e não exigem revisão da Apple.

O perfil App Store é usado exclusivamente para publicar o aplicativo na App Store e não contém uma lista de dispositivos — a Apple mesma gerencia a distribuição após a aprovação da compilação. Ao enviar um arquivo para o App Store Connect, o Xcode usa automaticamente o perfil App Store se estiver instalado no sistema. O perfil Enterprise é para organizações com Apple Developer Enterprise Program e permite distribuição interna de aplicativos sem limite de dispositivos ou revisão da Apple.

Estrutura de um Perfil de Provisionamento

Um Perfil de Provisionamento é um arquivo em formato DER assinado pela Apple, cujo conteúdo pode ser visualizado através da linha de comando. Security framework do macOS permite decodificar .mobileprovision em um plist XML legível. Dentro do perfil estão: UUID do perfil, App ID (prefixo da equipe + Bundle Identifier), lista de certificados, lista de dispositivos permitidos (apenas para Development e Ad Hoc), entitlements e data de expiração.

App ID é um identificador único do aplicativo que consiste em um Team ID (10 caracteres atribuídos pela Apple) e um Bundle Identifier (por exemplo, com.example.myapp). Um App ID pode ser explícito (correspondência exata com Bundle Identifier) ou wildcard (padrão *.example.com para vários aplicativos). A Apple não recomenda usar wildcard para aplicativos que usam Notificações Push ou iCloud — esses serviços exigem um App ID explícito.

Entitlements é um bloco XML dentro do perfil que define os direitos de acesso do aplicativo a recursos do sistema. Entitlements típicos incluem: aps-environment (Notificações Push), com.apple.developer.icloud-services (iCloud), com.apple.security.application-groups (App Groups para Widget e Share Extension). A Apple adiciona automaticamente entitlements ao perfil com base nas Capabilities ativadas no Xcode. Qualquer incompatibilidade entre os entitlements no perfil e aqueles solicitados no código resulta em erro de assinatura.

Criação de um Perfil de Provisionamento no Apple Developer

A criação de um perfil é possível de duas maneiras: através da interface web do Apple Developer Portal ou automaticamente pelo Xcode. Para um projeto típico, o Xcode gerencia os perfis automaticamente com a opção Automatically manage signing ativada. O Xcode cria um certificado, perfil e App ID em segundos, sincronizando com o Apple Developer Portal. No entanto, pipelines CI/CD exigem gerenciamento manual.

Para criar um perfil manualmente no Apple Developer Portal: vá para Certificates, Identifiers & Profiles, selecione Profiles e pressione "+". Então selecione o tipo de perfil (Development, Ad Hoc, App Store ou Enterprise), selecione um App ID da lista registrada, selecione um certificado de desenvolvedor e (para Development e Ad Hoc) selecione dispositivos. Após a criação, o perfil é baixado no formato .mobileprovision e instalado com um duplo clique no Xcode.

Os servidores CI/CD requerem uma abordagem especial: o perfil e o certificado devem ser armazenados em um repositório seguro (por exemplo, em segredos do GitHub Actions). Durante a compilação, o perfil é carregado no agente, colocado na pasta ~/Library/MobileDevice/Provisioning Profiles, e o certificado é importado para o chaveiro. Fastlane — uma ferramenta popular para automação de assinatura — fornece o comando match, que sincroniza perfis e certificados entre desenvolvedores através de um repositório git criptografado.

Exemplo: verificação de um perfil via linha de comando

Para diagnosticar problemas de assinatura de código, você pode decodificar o .mobileprovision e verificar seu conteúdo. O comando abaixo extrai o plist XML do perfil e o salva em formato legível:

# Decodificação de .mobileprovision para XML
security cms -D -i "path/to/embedded.mobileprovision" \
  -o "profile.plist"

# Verificação da data de expiração do perfil
plist -convert xml1 profile.plist -o -
grep -A 1 "ExpirationDate" profile.plist

Security utilitário do macOS Command Line Tools decodifica o arquivo de perfil assinado com CMS. A flag -D significa decodificação, -i especifica o arquivo de entrada. Após a decodificação, o utilitário plist converte o plist binário para XML, e o grep extrai a data de expiração. Este método é útil em CI/CD para verificar se o perfil não expirou antes de compilar uma versão.

Erros comuns com Perfis de Provisionamento

O erro mais comum é "No matching provisioning profiles found" ao compilar no Xcode. Ocorre quando o Xcode não encontra um perfil correspondente à configuração de compilação: o Bundle Identifier não corresponde ao App ID no perfil, o certificado não está instalado no chaveiro ou o perfil expirou. A solução é verificar as configurações de Signing & Capabilities no target e, se necessário, mudar para Automatically manage signing.

O erro "Provisioning profile doesn't include the selected device" aparece ao tentar executar uma compilação Development ou Ad Hoc em um dispositivo cujo UDID não foi adicionado ao perfil. O Apple Developer Portal permite adicionar um dispositivo a um perfil existente — após isso, o perfil deve ser baixado e instalado novamente. Xcode com gerenciamento automático de assinatura adiciona o dispositivo conectado ao perfil automaticamente.

Um problema com entitlements se manifesta como erro "The executable was signed with invalid entitlements" ao enviar para o App Store Connect. A causa é uma incompatibilidade entre os entitlements no perfil e aqueles no arquivo .entitlements do projeto. A Apple exige que o conjunto de direitos no perfil seja um superconjunto dos direitos solicitados pelo aplicativo. A solução é verificar as Capabilities no target do Xcode e garantir que todos os serviços habilitados tenham entitlements correspondentes no perfil. Fastlane inclui o comando produce, que sincroniza os App IDs e perfis com os entitlements atuais.