Skip to content

A Beginner's Guide to iOS Provisioning Profiles

February 16, 2017Hari Sriskantha4 min read

If you've spent any time developing an app for iOS, then you've probably stumbled across the bit of the Developer Console called 'Certificates, Identifiers & Profiles'.

Certificates, Identifiers & Profiles

This is not a blog post about how to do anything in that section.

Instead, it's a rough guide to what everything means -- in the hope of providing some relief/context when you've just seen the error 'No code signing identities' for the millionth time and feel like throwing your laptop out the window while shouting 'Code sign this!'

(Note: this article focuses on App Store apps, rather than in-house apps, which you can create through the Apple Developer Enterprise Program.)

Why Provisioning Profiles?

Good question. The key thing is that, unlike Android, you can't install any old app on an iOS device: it has to be signed by Apple first.1 However, when you're developing an app, you probably want to test it before sending it to Apple for approval. Provisioning profiles are simply a way for you to do that: they're like a 'temporary visa' that lets you run and test your app on a physical device. And like all good visa schemes, this means dealing with some bureaucracy...

The Components

Provisioning profiles always require the following components:2

  • A certificate
  • A unique app identifier (an 'App ID')

In some cases, they also require:

  • A list of devices the app can run on

The Certificate

This is a public/private key-pair, which identifies who developed the app.3 (Without such certificates, I could e.g. create an app called 'Facebook' and pretend that it's an update to the actual Facebook -- and hence trick you into giving me your login credentials.)

When you try to create a new certificate, you'll be presented with several options. For provisioning profiles, the key ones are:

  • iOS App Development: a development certificate. These are for developers who want to test the app on a physical device while writing code.
  • App Store and Ad-Hoc: a distribution certificate. These are for when you're ready to give the app to other people -- first for testing (the 'Ad-Hoc' bit) and then for general distribution via TestFlight or the App Store.

When you join an iOS development team, you're either a 'Member' or an 'Admin'. Anyone can create development certificates, but only those with admin privileges can create distribution certificates.

The App ID

This is a unique identifier for your app. Apple recommends using a 'reverse-domain name style string' of the form: com.yourcompanyname.yourappname. You can then associate 'entitlements' to your App ID, such as iCloud, Push Notifications, Apple Pay, etc.

It's also possible to create 'wildcard' App IDs, e.g. com.yourcompanyname.*, which can be used for multiple apps. While these can be useful in some cases, note that you can't associate entitlements to them.

Extra tip: if you're planning on releasing an Android app as well, then you should avoid using hyphens (-) in your App ID -- otherwise you won't be able to use the same one on both platforms.

The List of Devices

This is a list of devices.

This is perhaps the most annoying part of the process: if you want to distribute your app to testers (without using TestFlight), then they need to send you their device's 'Unique Device Identifier' or UDID. Unfortunately, you can't find it within iOS itself: they'll need to connect their device to a computer.

I heartily recommend the website whatsmyudid.com, which provides clear, illustrated instructions about what to do. However, you should still mentally prepare yourself for people sending you all kinds of random, irrelevant strings with the question: 'Is this it?' (Hint: if it's not a 40-character, hexadecimal string, then the answer is no.4)

Creating a Provisioning Profile

Congratulations, you're now ready to build your provisioning profile! Again, there are quite a few options, but the main ones are:

  • iOS App Development: for testing the app on a physical device while developing.
  • Ad Hoc: for distributing the app to non-TestFlight testers (e.g. via HockeyApp).
  • App Store: for distributing the app via TestFlight or the App Store. (Note that this one doesn't work on its own: your app will still need signing by Apple.)

Here are the key differences between them:

Provisioning Profile

Certificate

App ID

List of Devices

iOS App Development

iOS App Development

Yes

Yes

Ad Hoc

App Store and Ad-Hoc

Yes

Yes

App Store

App Store and Ad-Hoc

Yes

No

So when iOS attempts to install an app, it checks the following things:

  • That the private key used to sign the app matches the public key in the certificate;
  • That the App ID is correct;
  • That the entitlements required are associated with the App ID;
  • That the device itself is in the list of devices.

If anyone of these conditions fail, then the app will not install -- and you'll see a greyed-out app icon with no error message or clue for how to proceed. But at least now you have somewhere to start: you can go through those four bullet points manually, and make sure everything is as it should be. (We've found it's usually an issue with the list of devices.)

The End

I hope this post helped demystify what's going on when you create a provisioning profile. If not, then please feel free to leave a question in the comments below!


Footnotes

1 This doesn't apply to the iOS simulator or a jailbroken device. [back]
2 Note that these correspond to the sections of the left-hand menu within 'Certificates, Identifiers & Profiles'. [back]
3 Although this is all a lot more elaborate than Android's system, one of the great advantages is that you can recreate certificates. On Android, if you lose the original private key then you're screwed: you won't be able to update your original app, and you'll have to convince all your existing users to download a new one. [back]
4 I once even got sent a 40-character, hexadecimal string that wasn't a valid UDID, and looked nothing like the actual one they eventually sent me. To this day, I still have no idea where they got it from. [back]