Provisioning
What Is an Ad Hoc Provisioning Profile?
Understand how an Ad Hoc provisioning profile connects an Apple team, app identity, distribution certificate, entitlements, expiry, and registered devices.
An Ad Hoc provisioning profile is an Apple-signed authorization document for one app identity, selected signing certificate, allowed capabilities, validity period, and a specific set of registered devices. An iOS device uses the profile embedded in the signed app to decide whether that app may run on that device.
The profile is not the app, a delivery link, or a private signing key. It is one part of the authorization chain that produces an installable Ad Hoc IPA.
The relationship in one model
Apple Developer Team
├─ App ID → App ID prefix + bundle identifier
├─ Apple Distribution certificate → public-key identity
├─ registered devices → selected UDIDs
└─ enabled capabilities → entitlement boundaries
↓
Apple-signed Ad Hoc provisioning profile
↓
private key + app code + allowed entitlements + profile
↓
signed IPA for selected devicesEach item has a different job:
- Apple Developer Team: owns the identifiers, certificates, devices, and profiles. A device registered in one team does not authorize a build signed for another team.
- App ID and bundle identifier: identify which app the profile applies to. Apple represents the app identity in the profile’s authorized entitlements using an App ID prefix plus the bundle identifier.
- Distribution certificate: identifies a public key that the profile permits for signing. Apple says an Ad Hoc profile is created with a single distribution certificate.
- Private key: performs the signing operation and must match the public key in the selected certificate. It remains in the authorized signer’s keychain or secret store; it is not stored in the provisioning profile.
- Registered devices: are Apple Developer account records for physical devices. The selected device identifiers become the profile’s device authorization set.
- Entitlements: define capabilities the app may claim. The profile provides an allowlist; the app’s code signature records the entitlements the app actually claims.
- Signed IPA: contains the app, its code signature, and the embedded profile. This final artifact—not the profile visible on a developer’s Mac—is what the tester receives.
For the end-to-end creation and delivery sequence, use Ad Hoc iOS Distribution. This page focuses on the profile itself.
What the profile authorizes
Apple’s provisioning-profile model answers five questions:
- Who may sign? The profile authorizes the certificate selected when the profile was created.
- What may be signed? The profile applies to the App ID and bundle identifier it represents.
- Where may it run? For Ad Hoc distribution, the device must be among the profile’s selected registered devices.
- When may it run? The profile has an expiration date.
- How may the app be entitled? The profile constrains the app’s permitted entitlements.
All five must still agree with the app’s code signature. A profile that includes the right UDID does not rescue a bundle-ID mismatch, an unavailable private key, an unauthorized entitlement, an expired profile, or an invalid signature.
What the profile contains conceptually
For diagnosis, Apple documents readable properties such as:
DeveloperCertificates, representing certificates allowed to sign the covered code;Entitlements, including the authorized application identifier and team context;ProvisionedDevices, listing the device identifiers selected for a device-bound profile; andExpirationDate, limiting the profile’s validity.
Apple also explains that a provisioning profile is a property list wrapped in a CMS signature. These fields are useful evidence, but they are not a stable product API. Modern profiles also include a DER-encoded representation that the operating system treats as authoritative. Use supported signing tools and Apple’s APIs for automation; use the readable property list to understand and debug an artifact.
What it does not contain
An Ad Hoc profile does not contain:
- the signing private key;
- the app’s executable code or resources;
- an install page, manifest, or delivery URL;
- a live connection that updates an IPA after portal changes;
- permission to add more devices than the Apple team allows; or
- permission to claim entitlements outside the profile’s authorization.
The certificate data in a profile is public certificate material, not the secret needed to sign. Possessing a downloaded .mobileprovision file therefore does not, by itself, let someone create a valid replacement IPA.
Registered devices and ProvisionedDevices
Registration and profile membership are separate states. First, a device is registered in the correct Apple Developer team. Second, that device is selected when the Ad Hoc profile is created or edited. The resulting profile represents the selected identifiers in ProvisionedDevices.
This distinction explains a common failure:
UDID registered in portal
≠ UDID included in profile
≠ refreshed profile embedded in delivered IPAIf a tester was added after the IPA was exported, follow Add a Device to an Existing Provisioning Profile. If the portal looks correct but installation still fails, diagnose the Device Not in Provisioning Profile chain from the physical phone through the final artifact.
Certificate, private key, and profile relationship
The profile authorizes a certificate; the signer needs that certificate’s matching private key. A certificate can be current and belong to the correct team yet still not be the certificate authorized by this profile. Conversely, a profile can name the expected certificate while the build machine lacks its private key.
Do not solve this by exporting signing identities through tickets, client intake forms, or ordinary email. Apple treats distribution certificates and related account material as sensitive team assets. For a focused mismatch investigation, use Profile and Signing Certificate Mismatch.
App ID, bundle ID, and entitlements
The App ID selected for the profile must match the app being signed. In the diagnostic property list, the authorized application-identifier combines the App ID prefix with the bundle identifier. The app’s own CFBundleIdentifier and signed application identifier must be consistent with that authorization.
The profile’s entitlements are an allowlist, not a demand that the app claim every value. The app may claim a permitted subset. It may not add capabilities the profile does not authorize. When capabilities change, the App ID and profile may need to be refreshed before the app is signed again.
How iOS Code Signing Works owns the deeper signing model; this profile page keeps the focus on Ad Hoc authorization.
Expiry is part of the authorization
Every profile has an expiration date. Renewing a certificate or membership does not rewrite the profile already embedded in an IPA. Track profile expiry with the exact artifact delivered to testers, and replace expired builds deliberately. See Expired Provisioning Profile for the repair path.
Manual profiles versus Xcode-managed profiles
With manual signing, an Account Holder or Admin creates or edits the profile, selects the App ID, distribution certificate, and devices, downloads it, and ensures the build uses it. This provides explicit control but also creates responsibility for selecting and refreshing the correct asset.
With automatic signing, Xcode manages profiles and can register connected devices. Apple notes that Xcode-managed development and distribution profiles may not appear in the developer-account profile list. If Xcode has a cached profile that still satisfies its known requirements, it may continue using that cache until a new profile is requested. Do not mix automatic and manual ownership casually: record which system owns profile creation for each target and verify the export instead of inferring from project settings.
What happens when a device is added later
Adding a device creates or updates a team-level device record. It does not mutate existing profiles or signed apps.
For a manually managed Ad Hoc build:
- register the validated UDID in the correct team;
- edit or regenerate the intended Ad Hoc profile with that device selected;
- download or synchronize the refreshed profile;
- build again, or perform an authorized re-sign with compatible app entitlements and signing assets; and
- verify the profile embedded in the replacement IPA before delivery.
Downloading the new profile only places a file on a Mac. An IPA is a signed archive, so inserting or replacing files after signing changes the signed bundle. The replacement profile must be part of a new signing/export operation.
Inspect the profile embedded in an IPA
Use a copy of the IPA and a temporary extraction directory on macOS:
unzip -q ClientBuild.ipa -d ClientBuild-unpacked
APP_PATH=$(
find ClientBuild-unpacked/Payload \
-maxdepth 1 -name '*.app' -print -quit
)
security cms -D -i "$APP_PATH/embedded.mobileprovision" \
-o /tmp/ipaflow-profile.plistRead evidence relevant to the decision:
plutil -extract Name raw -o - /tmp/ipaflow-profile.plist
plutil -extract UUID raw -o - /tmp/ipaflow-profile.plist
plutil -extract ExpirationDate raw -o - /tmp/ipaflow-profile.plist
plutil -extract Entitlements.application-identifier raw -o - \
/tmp/ipaflow-profile.plist
plutil -extract ProvisionedDevices xml1 -o - /tmp/ipaflow-profile.plist
plutil -extract DeveloperCertificates xml1 -o - /tmp/ipaflow-profile.plistThen inspect what the app actually claims and verify its signature:
codesign --display --entitlements - --xml "$APP_PATH" \
| plutil -convert xml1 -o - -
codesign --verify --deep --strict --verbose=2 "$APP_PATH"Do not decide from a profile name alone. Compare the device list, expiry, application identifier, certificate authorization, and signed entitlements with the intended release. Inspect a Provisioning Profile Inside an IPA and Check an IPA’s Code Signature provide the deeper diagnostic steps.
Before sending the replacement artifact, run the iOS Distribution Checklist against the exact IPA and target device.