Provisioning Profile: What It Is, Types, and How It Works

What Is a Provisioning Profile

Provisioning Profile is a digital configuration file in .mobileprovision (for iOS) or .provisionprofile (for macOS) format that Apple uses to control app installation and launch on devices. The profile contains code signing metadata, without which an app cannot be run on a physical iPhone, iPad, or Apple Watch — the simulator does not require a profile because the code is not signed for execution on a real processor.

The profile is issued through the Apple Developer Portal and has an expiration date — typically one year for Development and Distribution profiles. According to Apple policy, the profile is automatically linked to the Apple Developer Program certificate under which it was signed: if the certificate is revoked or expires, the profile stops working.

Each profile contains a unique UUID that Xcode uses to identify the profile in the keychain. Xcode automatically selects the appropriate profile during building, but the developer can override the choice in Signing & Capabilities settings. An unlimited number of profiles can be installed on a single device — Apple's Mobile Device Management (MDM) system uses this for enterprise app distribution.

Why a Provisioning Profile Is Needed

Code signing is the main reason profiles exist. Apple requires every app run on an iOS device to be signed with a certificate issued by Apple. The Provisioning Profile acts as a link: it confirms that the developer has the right to run the app on that device. According to Apple Security Guide (2025), the profile mechanism prevents malware installation on user devices even if a developer certificate is compromised.

The profile also determines which system services are available to the app. If the app uses Push Notifications, Apple Push Notification service (APNs) requires correct entitlements inside the profile. Without this, server notifications will not be delivered to the device. The same rule applies to iCloud, App Groups, Wallet, HealthKit, and other Apple frameworks.

Difference from a Certificate

Developers often confuse Provisioning Profile and Apple Certificate. A certificate is a digital document that confirms identity (who signs), while a profile is a configuration (which app, on which devices, with which permissions). One certificate can be used in multiple profiles, and one profile is tied to exactly one certificate. Apple recommends creating a separate profile for each app and each scenario — Development, Ad Hoc, App Store.

How a Provisioning Profile Works

The app signing process consists of several sequential steps. Xcode takes the app binary (App Bundle), signs it with the developer's private key, embeds the Provisioning Profile into it, and sends it to the device. The device verifies the signature with Apple's public key, checks the profile UUID against the list of trusted profiles in the system, and launches the app only if all checks pass.

When a user downloads an app from the App Store, the mechanism differs. App Store Connect re-signs the app with Apple's own Distribution certificate, replacing the developer's profile with a Store profile. This means that an app published through the App Store is technically signed by Apple, not the developer — although the original developer signature is verified during the build upload to App Store Connect.

For Ad Hoc distribution, the profile registers specific device UDIDs on which the app is allowed to run. A free Apple Developer Program account limits testing to 100 devices per year. Enterprise profiles (for internal distribution within an organization) have no device limit but require an active Apple Developer Enterprise Program subscription costing $299 per year.

Profile Lifecycle

The validity period of a Provisioning Profile is one year from creation. 30 days before expiration, Apple starts sending push notifications to the developer through Xcode and the Developer Portal. If the profile expires, an already installed app continues to work, but a new build cannot be installed with that profile. Xcode throws a code signing error with code -402620394 when trying to build with an expired profile. Apple recommends setting up automatic profile renewal through Xcode Accounts Preferences — Xcode then renews the profile 24 hours before expiration.

Types of Provisioning Profiles

Apple provides four main types of Provisioning Profiles, each designed for a specific stage of the app lifecycle. The Development profile allows running the app on physical devices added to the Apple Developer Portal and is used during development and QA testing. A free Apple developer account is sufficient to create a Development profile.

The Ad Hoc profile is designed for distributing an app to a limited group of testers without using the App Store. The profile registers up to 100 devices by UDID, and the app can be installed directly via iTunes, Apple Configurator, or MDM solutions. Ad Hoc builds have a 12-month validity period and do not require Apple review.

The App Store profile is used exclusively for publishing the app to the App Store and does not contain a device list — Apple itself manages distribution after build approval. When uploading an archive to App Store Connect, Xcode automatically uses the App Store profile if it is installed on the system. The Enterprise profile is for organizations with an Apple Developer Enterprise Program and allows internal app distribution without device limit or Apple review.

Provisioning Profile Structure

A Provisioning Profile is a file in DER format signed by Apple, whose contents can be viewed via the command line. Security framework on macOS allows decoding .mobileprovision into a readable XML plist. Inside the profile are: profile UUID, App ID (team prefix + Bundle Identifier), certificate list, list of permitted devices (for Development and Ad Hoc only), entitlements, and expiration date.

App ID is a unique app identifier consisting of a Team ID (10 characters assigned by Apple) and a Bundle Identifier (e.g., com.example.myapp). An App ID can be explicit (exact match with Bundle Identifier) or wildcard (pattern *.example.com for multiple apps). Apple does not recommend using wildcard for apps that use Push Notifications or iCloud — these services require an explicit App ID.

Entitlements is an XML block inside the profile that defines the app's access rights to system resources. Typical entitlements include: aps-environment (Push Notifications), com.apple.developer.icloud-services (iCloud), com.apple.security.application-groups (App Groups for Widget and Share Extension). Apple automatically adds entitlements to the profile based on the Capabilities enabled in Xcode. Any mismatch between the entitlements in the profile and those requested in code results in a signing error.

Creating a Provisioning Profile in Apple Developer

A profile can be created in two ways: through the Apple Developer Portal web interface or automatically through Xcode. For a typical project, Xcode manages profiles automatically with the Automatically manage signing option enabled. Xcode creates a certificate, profile, and App ID within seconds, syncing with the Apple Developer Portal. However, CI/CD pipelines require manual management.

To manually create a profile in the Apple Developer Portal, you need to: go to Certificates, Identifiers & Profiles, select Profiles and click "+". Then select the profile type (Development, Ad Hoc, App Store, or Enterprise), select an App ID from the registered list, select a developer certificate, and (for Development and Ad Hoc) select devices. After creation, the profile is downloaded in .mobileprovision format and installed by double-clicking in Xcode.

CI/CD servers require a special approach: the profile and certificate must be stored in a secure repository (e.g., in GitHub Actions secrets). During building, the profile is loaded onto the agent, placed in ~/Library/MobileDevice/Provisioning Profiles, and the certificate is imported into the keychain. Fastlane — a popular tool for signing automation — provides the match command, which synchronizes profiles and certificates between developers via an encrypted git repository.

Example: Checking a Profile via Command Line

To diagnose code signing issues, you can decode the .mobileprovision and check its contents. The command below extracts the XML plist from the profile and saves it in a readable format:

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

# Checking profile expiration date
plist -convert xml1 profile.plist -o -
grep -A 1 "ExpirationDate" profile.plist

Security utility from macOS Command Line Tools decodes the CMS-signed profile file. The -D flag means decoding, -i specifies the input file. After decoding, the plist utility converts the binary plist to XML, and grep extracts the expiration date. This method is useful in CI/CD to verify the profile is not expired before building a release.

Common Provisioning Profile Errors

The most common error is "No matching provisioning profiles found" when building in Xcode. It occurs when Xcode cannot find a profile matching the build configuration: the Bundle Identifier does not match the App ID in the profile, the certificate is not installed in the keychain, or the profile has expired. The solution is to check the Signing & Capabilities settings in the target and, if necessary, switch to Automatically manage signing.

The error "Provisioning profile doesn't include the selected device" appears when trying to run a Development or Ad Hoc build on a device whose UDID is not added to the profile. The Apple Developer Portal allows adding a device to an existing profile — after that, the profile must be downloaded and reinstalled. Xcode with automatic signing management adds the connected device to the profile automatically.

A problem with entitlements manifests as the error "The executable was signed with invalid entitlements" when uploading to App Store Connect. The cause is a mismatch between the entitlements in the profile and those in the project's .entitlements file. Apple requires the entitlement set in the profile to be a superset of the entitlements requested by the app. The solution is to check the Capabilities in the Xcode target and ensure all enabled services have corresponding entitlements in the profile. Fastlane includes the produce command, which synchronizes App IDs and profiles with current entitlements.