In the first part of this article, we discussed what certificates and profiles are and how they are used for Apple platform development. In the second part of this article, we will be wrapping up the discussion by actually signing an app by creating all of the necessary signing assets inside of the developer portal and then placing them inside of Xcode.
The tasks that we will cover in this article are:
- Creating an App ID inside of the developer portal
- Creating a development and App Store certificate
- Creating a development and distribution provisioning profile
- Creating a new scheme called “App Store” in the Xcode project
- Assigning certificates and profiles to each scheme
A lot of the steps below will reference the Developer Provisioning Portal. This is the location on the Apple Developer website where you will perform the tasks for most of the headings below.
If you already have a paid developer account, navigate to the Apple Developer website, select “Account,” then “Certificates, Identifiers & Profiles.” This is the Provisioning Portal where you will see sections for Certificates, Identifiers, Devices, and Provisioning Profiles.
Creating App IDs
An App ID is the way Apple registers and uniquely identifies your app, and registers your particular app’s bundle ID with your account to provision the services your app might access (iCloud, APNS, HomeKit, HealthKit, etc.). This process is required before creating a provisioning profile for the app, so we’ll go ahead and do this first.
To register a bundle ID in the developer portal, perform these steps:
- Select “App IDs” under the “Identifiers” tab in the provisioning portal sidebar
- Select the “+” button at the top of the list
- Enter a Name for App ID registration (Use your app name, or app name + extension name)
- Select “Explicit App ID” and enter your Bundle ID in the provided text field
- Under the “App Services” section, select the services that you wish to enable in your app — you can always edit this list later.
- Select “Continue”
- The next screen will recap what will be saved; select “Register” if you’re happy with the changes
That’s it. The bundle ID is now registered and a profile can be generated based on the bundle ID. If you end up changing the bundle ID, you’ll need to remove the App ID if it will no longer be used by another app, and create a new App ID to serve the new bundle ID.
So, what’s the difference between an App ID versus a Bundle ID? In a nutshell, App IDs are unique identifiers in the Apple App Store ecosystem — there can only be one app with a particular App ID on the App Store. A Bundle ID is defined by you during the project setup, however, and is unique to your developer account, using reverse domain name notation (i.e. com.martiancraft.appname).
Creating the Certificates
As discussed in the first part of this article, we will need to generate a certificate to aid in the signing process for apps on Apple Platforms. This certificate is a many-to-one relationship, meaning that a single certificate can be used to sign all of your apps for development or distribution. I’ll walk you through creating a development and App Store distribution certificate, but the process is similar for most of the other types of distribution certificates.
The first step is to create a Certificate Signing Request (CSR) that will be provided to the developer portal in order to generate the valid certificate. To create this file, perform these steps:
- Open Keychain Access (Located in /Applications/Utilities)
- Navigate to Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority
- In the window that appears, fill out your email and name, then select “Save to disk” for the “Request is” option.
- Click Continue, then save the file to a known location on your Mac
Now that we have a CSR, we need to provide that file to Apple to generate the fully validated certificate. To do this, open the developer provisioning portal website and follow these steps:
- Navigate to Certificates, Identifiers & Profiles > Certificates > All
- Select the “+” button to create a new certificate
- Select “iOS App Development” to create a development certificate capable of signing apps for debug release to registered devices.
- Select Continue
- On the next page, you’ll be given instructions for how to generate a CSR using Keychain (which we just did), so click Continue
- The next page will instruct you to upload the created CSR file to the portal. Locate the file on your Mac and upload it by clicking Continue.
- On the next page you will see a Download button to download the validated certificate. Once downloaded, double-click on the file to add it to Keychain and join the validated certificate with the private key stored on your Mac generated through the CSR process.
Now when navigating to Keychain Access > Login Keychain > Certificates, you will see a public and private key pair that are prefixed by “iPhone Developer” (this denotes that the certificate is used for iPhone development signing; Mac signing certificates will have the prefix “Mac development”).
Complete these steps again, except when performing Step 3, select “App Store and Ad Hoc” for the type of certificate to create. This will create a certificate that is capable of signing iOS apps for App Store delivery.
When creating a new certificate, it’s valid for one year — when it expires the old certificate will need to be deleted and a new one generated to take the place of the old one. Whenever a certificate that is linked to a provisioning profile gets revoked or modified, the provisioning profile linked to the certificate must also be re-generated.
Registering Devices
If you will be building and running debuggable versions of your apps on devices, then you will need to register your devices’ UDID. This UDID will be included in the provisioning profiles that we create in the next step, and each time you want to add a new device you need to re-generate your profile, so we’ll perform this step first.
To register your devices, you’ll need the UDID of the iOS device you want to register. This can be found in iTunes or Xcode (find it in Xcode by connecting your device to your Mac, selecting Window > Devices > your device, and then copying the UDID string from the “Identifier” section) and is a unique string to your physical device.
To register a new device, follow these steps:
- Navigate to Certificates, Identifiers & Profiles > Devices > All
- Select the “+” button to add a new device
- Enter a name. We recommend using the format of “[Person First Name]’s [Device Type] ([Added / Modified] [Date Here])” when managing a large team to keep track of what devices are still in use.
- Enter the UDID to be registered
- Click Continue
This device will now be registered to your account; however, devices can be registered to multiple developer accounts. Once a device has been registered, it can be included in a provisioning profile to allow a signed app to run on that device.
Creating Profiles
A provisioning profile is at the heart of app signing. It determines which devices are eligible to run the app being signed, it also denotes the signing certificate used to sign the app, and it also determines which services the app has access to on the device (iCloud, APNS, etc.).
Creating a provisioning profile is a fairly straight forward process. Once you have the developer provisioning portal open, perform these steps:
- Navigate to Certificates, Identifiers & Profiles > Provisioning Profiles > All to get a list of all the profiles currently created in the account.
- Select the “+” button to create a new profile
- Here you will see all of the provisioning profile types you can create. Select “iOS App Development” and click Continue.
- On the next screen, select the App ID that was created at the beginning of this tutorial, then click Continue.
- On the following screen, you will be prompted to select from the available valid certificates which you want to use for signing with this profile. Select the newly created certificate, then click Continue (There can be multiple valid certificates in the case of development certificates, so selecting all of them will mean that all of the certificates can sign an app with the provisioning profile).
- On the “Select Devices” screen, select any of the devices registered to your account that you’ll want to create a build for. Any devices selected here will be eligible to run a build that’s signed with this profile and certificate settings. Click Continue when done.
- On the “Generate” screen, you are able to provide a human-readable name for the provisioning profile. At MartianCraft, we typically follow the format of “[App Name]: [Profile Type] Profile” (example: “MartianApp: Development Profile”). Click Continue once you’ve decided on a name.
- On the last screen, you will be able to Download the newly created profile. Once downloaded, drag and drop it on top of the Xcode icon in the Dock to easily add it to ~/Library/MobileDevice/Provisioning Profiles (the directory home of the provisioning profiles that Xcode is using to sign apps). You can also manually manage any profiles by dragging and dropping them into this folder yourself.
To generate an App Store profile, simply repeat the process, but when performing Step 3, select the “App Store” profile type instead. This will create an App Store profile that can be used to sign apps destined for sale. You’ll notice that with this profile type, however, you’re not able to select devices for the app to run on (since App Store signed apps can run on all devices). During setup, you’ll only select an App Store distribution certificate and specify the name for the profile.
It’s important to note that during setup you selected a certificate that is linked to the profile, in addition to selecting devices that the profile can sign apps to run on. If any of these settings change (You revoke a certificate, need to create a new certificate, add a new device, remove an existing device), you will need to re-generate the provisioning profile.
Re-generating a profile is an easy task, however: Simply navigate to Certificates, Identifiers & Profiles in the provisioning portal > Provisioning Profiles > All, and select the profile you wish to re-generate. Next, select the “Edit” button to change the App ID, Certificate settings, or selected devices.
Assigning certificates to schemes in Xcode
Now that we have all of the assets needed to sign an iOS app, we’ll bring everything together inside of Xcode to assign the certificate and provisioning profile to a specific scheme.
By default, Xcode automatically creates two schemes: Debug and Release. We’ll take advantage of these two schemes to use the Debug scheme with the Developer Profile and Certificate, and we’ll use the Release scheme to sign with the App Store Profile and Certificate.
With the certificates already imported into the Keychain and the Provisioning Profiles already added to the Provisioning Profiles directory as discussed in the last section, open the Target’s “General” tab in Xcode.
Once here, you’ll see a section for “Automatically manage signing.” Uncheck this box since we will manage signing (certificates and provisioning profiles manually). You’ll then see two sections appear: “Signing (Debug)” and “Signing (Release).”
For the Signing, in the drop-down menu for “Provisioning Profile” under the “Signing (Debug)” heading, select the profile that was generated for development. The matching certificate will automatically be paired and displayed under the “Signing Certificate” section. Do the same for the “Signing (Release)” section, except select the App Store profile that was generated in the provisioning portal from the drop-down menu.
That’s all you need to do in order to specify manually created provisioning profiles. It’s not that bad, now is it? Now you’re ready to begin building and running.
Some common errors and how to fix it
- Provisioning Profile doesn’t match bundle ID When Xcode shows this error, it’s because when the provisioning profile was generated the incorrect App ID / Bundle ID combo was selected in the drop-down menu and the provisioning profile generated is for signing a different project Bundle ID.
- Code Signing Entitlements file do not match those specified in your provisioning profile When this message is shown in Xcode, it’s because the local entitlements (see the Capabilities tab for the project Target) doesn’t match what’s registered in the profile. If you add a feature like iCloud or Keychain support, then it must be registered in the provisioning portal and a new provisioning profile must be generated and used to sign with.
- No Matching Provisioning Profiles Found can be displayed whenever the selected certificate doesn’t have any profiles that can be used as a pair to sign with. Check to ensure the generated provisioning profiles were imported into Xcode, and if that doesn’t work, double check that when you set up the provisioning profile in the developer portal that the desired certificate to be used for signing was selected as an available certificate to use. You can then re-generate the profile, download, and re-import.
For more common provisioning errors and how to fix them, visit the Apple developer website for more information.
Building and Signing
With the setup that we performed, you can easily build and run the target from Xcode to a device that was registered with the Provisioning Profile and Xcode will happily oblige.
In order to release to the App Store; however, you’ll want to select “Generic iOS Device” from the build to menu, then select Product > Archive. This will create an archive build and will sign it using the App Store Provisioning Profile and Certificate.
Submitting the app is done in the Xcode Organizer (available from Window > Organizer). Select the archive that you wish to deliver to the App Store, and click the “Upload to App Store…” button in the sidebar. Follow the prompts and when prompted to select a development team, choose the option to “Use local signing assets.”
Conclusion
As you can see with these two articles, provisioning is an art and hopefully these two articles have helped to demystify the process a bit. For new developers, this process can be a bit overwhelming. Fortunately, this is a process that only needs to be done every year and at the start of a new project.
We’ve touched on all of the basics of provisioning and also dove into the process and dissected each piece, but if you still have provisioning questions, Apple has a few video resources from past WWDCs that can provide more insight into the process. Check out the links to them below.
