Provisioning Profile Crash Course – Part 1
In this series blog post I will try to give you a brief explanation on what are the requirements and the differences for the Development and the Distribution provisioning profiles.
TL;DR: If you are working mostly alone, e.g. as an indie developer, and you can just keep the “Automatically manage signing” box ticked, you are the lucky one 🎉. Probably you don’t really need to have the knowledge below.
In this first post I will explain how you can create the 2 most common “ingredients” of the provisioning profile: Certificates and Devices. In order to run your new, shiny app on your own device you will need to to have a Development Certificate (currently called Apple Development Certificate), and you need to also register your device.
If you are already at the stage that you want to publish your app in the App Store, you will need the Apple Distribution Certificate. The 2 certificates has no dependency on each other, so you can even test your app on a simulator (although I won’t recommend it), and then you need to generate only a certificate for distribution.
Public key cryptography
The foundations how the provisioning profile works starts with the Digital certificates, most specifically on the Public key certificate. If you are not familiar with it, let see the very basics so you can understand the points afterwards.
The whole concept is coming from the public key cryptography, where the system is using key pairs.
In the pair there is a private key, that you should keep it yourself, and for added security you should also protect it with password. Never, ever share your private key, not to mention the password for it!
The other party in the key pair is the public key, which is intended to share with all of the universe. The 2 keys are different, but the trick is (in very simplified terms) that only the public key can unlock the things that were locked with the private counterpart, and it is true the other way around, so the things locked with the public key can be opened with the private one. I know, the whole trust is on the fact that the private key is indeed kept private.
Based on the public counterpart of your key, a Public key certificate can be issued, which is essentially assuring that the give public key is valid, and also contain identity information along with the issuer information and the expiration date. You can imagine that the issuer should be also proven to be reliable. For us, iOS/macOS developers Apple will be the issuer those publicly used certificates, and also using it for a lot of services. Apart from the general development based certificates, and for the App Store listing there are different certificate types for the push notifications. The whole list and basic information can be found here: https://developer.apple.com/support/certificates/. In this series I am only covering the 2 most important ones:
- Apple Development for signing development versions of your iOS, macOS, tvOS, and watchOS apps. Apps signed with this certificate can be run on any device, which is registered with your Developer Account.
- Apple Distribution which signs your apps for submission to the App Store or for Ad Hoc distribution. This certificate signs the apps for App Store distribution. Usually this type of the certificate is used on CI/CD machines, so the build process can generate a distributable binary.
Creating a certificate
1. Initiate a Certificate Signing Request. The easiest way is to use Keychain Access, on your Mac machine, and you can start it from the Keychain Access -> Certificate Assistant -> Request a Certificate from the Certificate Authority… menu point. Be careful, There is one trick: you should change the default values for the Request is: To Save to disk. Only the email address will be mandatory. If you click on continue, the wizard is going to create a file with .certSigningRequest extension for you. (What you don’t see, that a newly generated private and public key pairs will be also generated, and stored in your Keychain Access database).
2. After the .certSigningRequest file creation you need to upload the previously created request to Apple. Go to the https://developer.apple.com and log in. Under the https://developer.apple.com/account/resources/certificates/list you will find your organization certificates. With the plus sign next to the Certificates title, you can start the process. You can see a quite long list of different certificates, and to be honest some of them are there just for historical reasons. If you need to develop an app and put it in the App Store, you definitely need the first two in the list (Apple Development and Apple Distribution)
After selecting the certificate type, and uploading the certSigningRequest created in step 1, Apple is issuing a certificate for you, usually with the expiry date of 2 years. It can be downloaded, and double clicking on it will automatically save it to the Keychain Access. If you are opening it on the same machine, that you used to generate the certificate request, then you should see the certificate under the My Certificates section (form the top tab-bar), and clicking on the rectangle on the front of the certificate, you should see the private key as well. That’s it for the generation part.
Exporting the certificate
That’s probably the most important part. No matter what type of the certificate you have downloaded form the Developer portal, your certificate and the attached privet key is now only stored (securely) on that particular Mac machine. So, we need a backup (as Apple highly recommends). Firstly because anything can happen with that machine, and your private keys and access to the certificate is lost, secondly if you need to use that certificate on other machines, either for the development, in case that you need to change the machine, or using more than one machine; or for creating an archive for the App Store distribution on different machines, such on a CI/CD server. In order to save the certificate and the associated keys, we need to use the Keychain Access again.
- Make sure that you selected the My Certificates from the top bar (be aware that from other views, the export for the .p12 format won’t work).
- Right Click on the certificate that you want to export, and select the Export… from the list.
- Select the Personal Information Exchange (.p12) format form the File Format list, and set the file name and location accordingly.
- Clicking on Save the system will ask you for a password. I highly recommend to input a strong one, and also make a not of it (I am using password managers for that reason, like KeepassX)!
- After saving the .p12 file, now it is safe to move it to another machine, either to the CI/CD (if it was a Distribution Certificate), or to another developer machine, if it was a Developer certificate.
Revoking a certificate
During the lifecycle of a certificate you might end up in the situation that you don’t need a given certificate anymore. It could happen that you are running in some limit (Apple is limiting the number of active certificates: https://help.apple.com/xcode/mac/current/#/dev3a05256b8 ), or because a certificate is compromised, or the developer is leaving the company or the project. In this case you need to go to the Apple Developer Portal, navigate to the certificates list (https://developer.apple.com/account/resources/certificates/list), select the certificate, and clink on the red Revoke button on the top. Finishing the process then will make it sure that the certificate can not be used anymore.
There is a small caveat though: As you will see the Development Certificates are included in the Development Provisioning profiles. If you revoke a certificate, which was included any of that Provisioning Profile, the given profile will be invalid, and you need to go to the Developer Portal to fix it. That is one of the most time consuming work related to the Provisioning profiles and certificate management.
Apple won’t let you run your code on a physical device, unless that particular device is not registered with your developer account. In order to register a device you need to know its unique identifier. This identifier can be read out in several ways, but the phone needs to be connected to your Mac. Usually I use those methods:
From Xcode: From the Window -> Devices and Simulators window, and select the phone.
From the Finder: Click on the connected phone on the sidebar, and click on the subtitle under the name of the phone. It will show the numbers, and by right clicking on them, you can copy it immediately.
After getting the device UUID, you can go to the Apple Developer portal, and add your device. There are some things that you need to know though:
- You are limited on the number of devices that you can add. You can add only 100 devices from each category: Apple TV, Apple Watch, iPad, iPod, and iPhone.
- There is a one-time option during each 1 year Apple Developer Program subscription to remove (actually to review) your device list. This needs to be confirmed by every year, otherwise you can’t add more devices via the App Store Connect portal.
The Add device wizard is quite straightforward, you can assign a name to the device, which can be different than the original phone name. Here I would suggest to use a wise naming, at least adding the device type and version.
After having the Certificates and the device set up, we are ready to continue with the Identifiers and the Capabilities in my next post.