Anyone who dabbles in macOS or iOS development in Xojo (and elsewhere) has encountered what seems to be the maddening voodoo of getting their development certificates and profiles “just right” only to have them fail the next time they try to build.
Today I’m going to try to clear up some of the mystery surrounding this convoluted process and give you some pointers not only for fixing but also for figuring out where your signing issues lie.
It’s All About Operational Security
Just so we’re all clear about why this process seems so complicated in the first place. What Apple is trying to do is to provide operational security, that is, separation of responsibilities so that on a big team, a single developer can’t just create and push out an app without anyone’s approval. While it adds a bit of complication for individual developers, it also means that as your product (and more importantly your team) grows, you’ll be able to deal with the changes gracefully.
Seemingly Disparate Pieces
There are six different parts that need to come together to successfully sign and deploy on iOS and macOS using the App Store (or Enterprise) which need to be configured properly for all this to work. If you’re just starting out, we suggest doing them in the order specified below to avoid having to go back and regenerate things later.
- The Application Identifier – This is the identifier which Apple requires be unique for every application installed on an Apple device. Typically in the form:
com.yourcompany.app-nameYou will have the best luck with this process if you decide what this is going to be up front because it affects nearly everything going forward. You will define any capabilities which require entitlements in this section. Enabling things in this section may mean that you need to check a corresponding capability in your Xojo project. Changing these capabilities will invalidate the Profiles below. - Testing Devices – This is a list of devices which are allowed to be used for testing. They are specified using the Apple Developer portal using the device UDID. For an iOS device, this can be found either in Finder or in iTunes when the device is connected. I suggest using a meaningful name for the device if you have a lot of them.
- Certificates – Development and Distribution certificates are based on a public-private key-pair (like SSH) and are used for signing applications for testing and distribution respectively. See the Troubleshooting section below for more information.
- Development Certificate – Each person who is writing code for you on your projects and needs to be able to build for a testing device will need one of these which was created in your account. This means that if you have a contractor working for you, you’ll need to add them to your account, set their Role to Developer and specify the apps that this developer is allowed to work on. One certificate per developer, and these need to be renewed each year.
- Distribution Certificate – The person, group or machine that is responsible for building for the App Store (or Enterprise) has a separate key-pair certificate. One certificate per account, and they need to be renewed each year.
- Profiles
- Development Profile – This file is used to link up the who, what and where of developing an iOS or macOS app. When creating a development profile, give it a name appropriate to the group you are creating. It’s important to understand that because these profiles rely on the testing devices and on the individual developers that changes to those groups will require regenerating this profile. If your developers and/or testing devices change often, I suggest creating individual profiles for each developer. If not, you’ll have better luck with just one profile that contains all of your developers and devices. These need to be regenerated at least once per year.
- The Application Identifier – Select the Application Identifier for the app to which this profile applies.
- Certificates – Select each of the developers that should be able to test this app on the selected devices.
- Devices – Select each of the devices that the developers should be able to use in their testing.
- Distribution Profile – This file links together the Application Identifier and the Distribution Certificate. Remember, there is typically one Distribution Certificate per account, so this allows you to grant or revoke the ability to distribute an app. These need to be regenerated at least once per year.
- Development Profile – This file is used to link up the who, what and where of developing an iOS or macOS app. When creating a development profile, give it a name appropriate to the group you are creating. It’s important to understand that because these profiles rely on the testing devices and on the individual developers that changes to those groups will require regenerating this profile. If your developers and/or testing devices change often, I suggest creating individual profiles for each developer. If not, you’ll have better luck with just one profile that contains all of your developers and devices. These need to be regenerated at least once per year.
Dependencies
I’ve touched on this in places above, but I want this to be perfectly clear to anyone that is having trouble with certificates or profiles. The Development and Distribution profiles are highly dependent on the integrity of the Application Identifiers, Devices and Certificates. Any change to those items will mean that either or both of the profiles will need to be regenerated. Luckily (for the profiles anyway), it’s just a matter of editing the profile, adding or updating the data (if any) and clicking Save. Once that’s done, you can download the new profile, give it to anyone on your team that needs it (anyone whose certificates are contained therein) and just by double-clicking on the new file, it will be installed on your system by Xcode.
The table below shows the dependencies of the Development and Distribution profiles. Any changes to the indicated items (including expiration of a certificate) will render the profile Invalid and require that it be regenerated.
| Profile Type | Application Identifier | Devices | Development Certificates | Distribution Certificate |
| Development | X | X | X | |
| Distribution | X | X |
Troubleshooting
Overall
If you’re getting errors during the build process, there’s usually some information about whether it is a Profile or a Certificate that is causing the trouble. The first thing you should do is go to your Apple Developer portal and under Certificates, Identifiers & Profiles check to make sure that none of your Certificates have expired and that all of your Profiles for the current project are still Valid and have also not expired.
Certificates
If for any reason you do not have both parts of the certificate you are trying to use, whether it’s the user’s Development certificate when building for your test devices or the Distribution certificate when trying to build for the App Store (or Enterprise), you’re not going to be successful. Both the public and the private key must be present on your machine for them to work.
It’s important to remember that these certificates can only be downloaded from Apple’s Developer portal once, after which downloading will only give you the public key. If you need to transfer a development certificate from one account to another (like if you replace your computer mid-year), you should find the certificate in your keychain, right-click on it and select Export. When the save dialog appears, make sure the file format is set to Personal Information Exchange (.p12), and set a password for the key after you click Save. When you take the exported key to your new account/machine and double-click on it, the system will ask you for the password and you should be all set.
Enterprise Distribution
If you are a Xojo developer using an Enterprise developer account to distribute iOS applications within your own company without going through the App Store, we highly suggest checking out 2021r3 or later as some important changes have been made to make your builds more successful.