Apple Code Signing, Explained with Three Cards

APPLE SIGNING · 01 / 12

Stop memorizing certificates, App IDs, and provisioning profiles as separate objects. Connect who may sign what, and where it may run, and Xcode's signing errors begin to make sense.

Code signing matches a trusted identity to an execution policy.

WHO
Signing certificate
Is this signer trusted?

WHAT
App ID
Which bundle and capabilities?

WHERE · WHEN · HOW
Scope and rights
Devices, dates, and entitlements

↓

AUTHORIZATION
Provisioning Profile
Apple's signed authorization that binds these conditions

Why signing configuration feels confusing

A signing error rarely points to a single cause. The certificate may have expired, the bundle identifier may not match the profile, or the app may request an entitlement that the profile does not authorize.

The confusion starts when we memorize certificates and provisioning profiles as unrelated files. Apple's technical note frames a provisioning profile as an authorization mechanism for running third-party code—not merely a file you download for development.^[1]

The one sentence to remember
A certificate proves who signed the code. A provisioning profile proves that this signer is authorized to run this app under these conditions.

Separate the three core pieces

CERTIFICATE

The signer's identity. An Apple Development certificate signs builds that run on development devices. An Apple Distribution certificate is used for distribution workflows, including submission to App Store Connect.^[2] The actual signing operation also needs the matching private key stored in the Mac's Keychain.

APP ID

The app's identity and capability scope. A practical mental model is Team ID + Bundle ID. If the target's Bundle Identifier does not match the App ID authorized by the profile, Xcode cannot use that profile.

PROFILE

A bundle of execution conditions. It connects signing certificates, an App ID, allowed devices, an expiration date, and entitlement limits. You create it through the Apple Developer website or Xcode, and Apple signs it cryptographically.^[1]

The five questions a profile answers

1. Who? Was the app signed by an allowed development certificate?
2. What? Does the application's identifier match the App ID?
3. Where? For development or Ad Hoc, is this device registered?
4. When? Is the profile still valid?
5. How? Are the requested entitlements allowed?

Apple's TN3125 explains the structure in terms of who, what, where, when, and how.^[1] This frame turns a vague signing failure into a much smaller search space.

MYTH “The provisioning profile contains my private key.”

CORRECTION The profile contains information about allowed certificates. The private key remains part of the signing identity in Keychain.

App Store distribution has one apparent exception. After validating the submitted signature and profile, the App Store re-signs the app. The final app downloaded by a customer therefore has no embedded provisioning profile.^[1]

What Xcode does when automatic signing is on

After you select a Team, provide a unique Bundle ID, and enable Automatically manage signing, Xcode can manage device registration and development provisioning profiles for you.^[3]

1. Select a Team — choose the developer account and organization scope.
2. Check the Bundle ID — provide the identifier connected to the App ID.
3. Manage assets — let Xcode manage development devices and profiles.
4. Apply at build time — select a compatible identity and profile.

Automatic signing does not remove the model. It asks Xcode to satisfy the same model on your behalf. When it fails, you still return to the Team, Bundle ID, certificate, device, and entitlements.

Inspect the state on your own Mac

1. List usable code-signing identities

security find-identity -v -p codesigning

If the list is empty—or the expected team's identity is missing—check the certificate and private-key pair before recreating profiles.

2. Inspect the signature applied to the app

codesign -dvvv --entitlements :- "/path/to/MyApp.app"

Inspect the Authority, TeamIdentifier, Identifier, and entitlement output. Reading the built app's actual signature is usually faster than arguing with an error message from memory.

3. Decode the embedded profile for inspection

security cms -D \
  -i "/path/to/MyApp.app/embedded.mobileprovision" \
  -o /tmp/profile.plist
plutil -p /tmp/profile.plist

Use this only for diagnosis. Apple warns that the exact internal format of a provisioning profile is not a documented contract and may change. Production logic should not depend on its private structure.^[1]

Use this troubleshooting order

1. Team — Did you select the correct personal or organization team?
2. Bundle ID — Do the target, App ID, and profile identify the same app?
3. Signing identity — Is the matching private key in Keychain, not just the certificate?
4. Purpose — Are you mixing Development and Distribution assets?
5. Device — For development or Ad Hoc distribution, is the device registered?
6. Expiration — Are both the certificate and profile still valid?
7. Entitlements — Does the App ID and profile authorize every capability the app requests?

What to take away

• A certificate represents the signer's identity.
• An App ID represents the app and its capability scope.
• A provisioning profile binds who may run what, where, when, and with which entitlements.
• Automatic signing preserves this relationship; Xcode merely manages it for you.

Official sources

1. Apple TN3125: Inside Code Signing — Provisioning Profiles
2. Apple Developer Account Help — Certificates overview
3. Apple Developer Documentation — Running your app on simulated or physical devices

This article reorganizes the concepts and diagnostic workflow for readers rather than reproducing Apple's wording. Apple, Xcode, and App Store are trademarks of Apple Inc.