Hour 22. Managing and Provisioning iOS Devices
What You’ll Learn in This Hour:
• How to prepare iOS applications for distribution
• How to create a distribution certificate
• How to create an App ID
• How to create and install a distribution provisioning profile
Once your application works as you want it to, you have to start thinking about the big picture: getting it out of Xcode and onto the devices (whether iOS or OS X) where it will be used.
If you’re developing just for yourself, you really have no reason to go beyond the rapid development provisioning for iOS devices that you were introduced to in the first hour (or beyond just building your application for use on your own Mac). However, if you want to distribute your application, you need to complete a few additional steps.
These steps fall broadly into two separate categories: housekeeping steps to ensure that your application is distributable, and steps that Apple requires if you want to make the application available via the App Store.
In this hour, you learn how to prepare your iOS devices to receive your software and how to inform Apple about resources that must be allocated (such as a namespace for your iCloud data storage) to enable other devices to receive your app. In the next hour, we look at the App Store itself and Apple’s requirements for distributing for iOS and OS X.
Unlike most other hours in this book, you cannot follow the instructions here entirely literally. We create several configuration documents for application distribution that are required, by virtue of how Apple manages the App Store, to be completely unique among all apps. To avoid conflicts with other readers of the book, and confusion when the App Store complains that an identifier is already taken, make sure to use your own email addresses and company and bundle identifiers when following the steps in this hour.
Creating an iOS Distribution Certificate
The first thing that is necessary for distributing, as opposed to developing, iOS applications is a distribution certificate. Distribution certificates consist of unique public and private key pairs, used by the distribution process and the users who will receive your application to verify that it really came from you. They’re necessary to prevent some malicious third party from sneaking out an update version of your software that might contain damaging code and fooling your users into thinking that it is an official release from you.
Did You Know?
You need to fully understand two key terms used repeatedly through this and the following hours:
• Certificates are a mechanism to ensure that you are who you say you are (or rather, that anyone who says they’re you, really is you). Certificates are used to sign applications to provide a guarantee that the application is authentic and belongs to a specific developer or development team.
• Provisioning profiles are used to associate specific certificates with specific hardware devices and specific applications. They effectively specify combinations of who, where, and what may be run, enabling you to control how your team uses your development resources and enabling Apple to limit the damage that an unfinished application can do “in the wild,” by restricting its distribution to only those devices where you have explicitly enabled that application.
As of Xcode 4.3, you can create a distribution certificate in several ways. The way that Apple hopes that you use is automatic provisioning, letting Xcode manage the creation of the necessary certificates for you. Unfortunately, this process doesn’t always work.
To determine whether you are already set up, open the Organizer from the Xcode toolbar and pick devices in the Organizer and profiles in the Organizer sidebar. If you see an iOS device distribution profile there, along with an IOS device development profile, and you can select it and it doesn’t tell you that it is an invalid profile, Xcode’s automatic creation of the certificates for you has worked. If you don’t see the distribution profile, or it tells you that it is not a valid distribution profile, something went wrong in the process, probably in the insertion of the certificate parts into your keychain. In this case, you must clean up Xcode’s mess and create the certificates and profile manually.
If you’re one of the lucky ones for whom everything worked, you can skip ahead to “Creating an App ID.” If all that appears in the Organizer is your development profile, and not a broken distribution profile, you can skip ahead to “Creating a New Distribution Certificate and Provisioning Profile by Hand.”
Fixing Broken Distribution Certificates and Profiles
If Xcode starts the automatic process but leaves you with a broken distribution profile, follow these steps to get back to a clean slate so that you can build a working profile by hand:
1. Open the Organizer from the Xcode toolbar and pick Provisioning Profiles under Library in the sidebar.
2. Select the distribution profile that was partially created. It may have a status line showing “Valid signing identity not found,” or it might only show a warning when you select it.
3. Delete the problematic profile and close the Organizer.
4. Launch the Keychain Access program from the Utilities folder of your Applications directory.
5. Pick the Login keychain, and the Certificates category, from the Keychain Access sidebar.
6. Use the Search field on the Keychain Access toolbar to search for “iPhone.”
7. Select any certificates with names that start with “iPhone developer” and delete them.
8. Cancel the search for “iPhone” and delete the Apple Worldwide Developer Relations Certificate Authority certificate.
By the Way
It seems likely that in the future Apple will start using certificates named iOS Developer rather than iPhone Developer. You might want to keep an eye out for these, as well.
Now Xcode’s Organizer and your keychain should be clean and ready to accept a new certificate that you create and install by hand.
Creating Distribution Certificates and Provisioning Profiles Manually
To create a new distribution certificate and provisioning profile manually, you work through the Keychain Access program and Apple’s Online Provisioning Portal in addition to Xcode. The process has several parts. You must first use Keychain Access to create a request for a certificate, and then use the Provisioning Portal to actually obtain the certificate. After you’ve obtained the certificate, you can install it in your keychain again, and then you use a combination of Xcode and the Provisioning Portal to create provisioning profiles for distributing your application. Let’s start with creating a request for a certificate.
Creating Certificate Requests with Keychain Access
Keychain Access enables you to configure a request for a certificate that you can send to a certificate authority. To use Keychain Access to configure the request, follow these steps:
1. Launch Keychain Access from the Utilities subfolder of your Applications directory on your Mac.
2. Open the Keychain Access preferences and click the Certificates tab.
3. Configure the preferences as shown in Figure 22.1, with both the Protocol and the Revocation List set to Off. Close the preferences.
Figure 22.1. Setting the Protocol and Revocation options in the Certificates section of the Keychain Access preferences to Off.
4. From the Keychain Access menu, choose Certificate Assistant, Request a Certificate from a Certificate Authority.
5. Provide the team agent email address as it appears in your iPhone Developer Program registration.
By the Way
The team agent is the sole individual allowed to actually submit files to the App Store. If you have already registered the team agent under a different user ID or on a different computer, you must duplicate their already-created distribution certificates and public and private keys into your keychain. Apple provides a tutorial on how to do this in Tech Note TN2250 available at http://developer.apple.com/library/ios/#technotes/tn2250/.
6. Provide the common name that should be associated with your certificate. This can be your company name or your personal name. If you’ve requested other certificates for other purposes, be consistent with this value.
7. Select the Save to Disk option, and check the Let Me Specify Key Pair Information check box.
8. You should not have to specify a certificate authority email address because you are going to save the request to disk rather than have Keychain Access submit it automatically. However, Keychain Access sometimes insists that you put something in this field before it will let you click Continue. Because it will not be used, it is safe to just use your own email address here if Keychain Access wants a value before proceeding.
9. When you have everything filled in, your request should look something like what is shown in Figure 22.2. Click Continue, and then choose a place to save the certificate request. The default filename and your desktop are good choices. Click Save.
Figure 22.2. Here is the completed certificate request before clicking Continue.
10. In the dialog that appears, specify a key size of 2048 bits and the RSA algorithm. Click Continue.
11. A dialog appears indicating that your certificate request has been saved. Click Done.
Requesting the Certificate Through the Provisioning Portal
Now that you’ve created the certificate request, you can send it to the Provisioning Portal, which requests the actual certificate for you. To use the Provisioning Portal to request your certificate, follow these steps:
1. Navigate to the Provisioning Portal (http://developer.apple.com/ios/manage/overview/index.action) in a web browser and sign in using your developer ID.
2. Click the Certificates category in the navigation list on the left. Then click the Distribution tab along the top of the work area.
Watch Out!: Don’t Let the Tabs Fool You
The contents of the Distribution tab and the Development tab look an awful lot alike, and every time you make an action in the portal, the portal defaults back to the Development tab. Sometimes it even seems to default back to the Development tab when you look away from your screen for a few moments.
You don’t want to know how many times I’ve gone through all the steps of setting up certificates or creating profiles only to discover that I’ve accidentally missed a switch to the Development tab somewhere in the middle of the process and have to delete everything and start all over again. Pay really close attention to those tabs, and hopefully you’ll pull out less of your hair than I have.
If you’ve just deleted a broken distribution certificate and profile from your keychain and organizer, you will probably see a current distribution certificate listed.
3. a. If, and only if you just deleted the broken certificate from your Keychain Access application, make sure you’re really on the Distribution tab, and then revoke it, and continue with step 4.
b. If there was no distribution certificate in your Keychain Access application, but a distribution certificate already appears here, ready for download, the certificate may have been created properly and just not downloaded. Skip ahead to step 9.
4. Beside the line that says “You currently don’t have a valid distribution certificate,” click the Request Certificate button.
A page opens with instructions for this certificate-creation process that you’re currently in the middle of, and a note that Xcode’s automated process is really the preferred way of requesting these certificates. If Xcode had done it right, you wouldn’t be here now, so forge ahead.
5. Near the bottom of the page, you’ll see Choose File. Click it.
6. Navigate to the certificate request that you saved to your desktop in step 9 in the preceding section, select it, and click Continue. Back on the Distribution tab (you’re still on the Distribution tab, right?), click Submit.
The page for the Distribution tab on the Provisioning Portal then reloads and shows your new distribution certificate, probably with a status of Pending.
7. Wait a minute or two, and then reload the page for the Distribution tab. The status should now be Issued, and there should be a button in the Actions column to download your distribution certificate. If the status is still Pending, wait a bit longer and try this step again.
8. When the Download button appears, click it. The distribution profile then downloads to your computer.
9. Click the link to download the Worldwide Developer Relations (WWDR) intermediate certificate. The link should be located immediately beneath the list of distribution certificates in the Provisioning Portal.
10. Back in the Finder on your Mac, navigate to where you saved the WWDR intermediate certificate and your distribution certificate.
11. Double-click each of the certificate files (the WWDR and distribution certificates) that you just downloaded. Keychain Access should launch (if it is not already open), and the certificates should be installed in the Certificates list for your Login keychain. The private keys for each should be installed in your Keys list for your Login keychain.
12. Select the iPhone Distribution certificate in your keychain and click its disclosure triangle. You should see an associated private key, as shown in Figure 22.3.
Figure 22.3. Showing the iPhone distribution certificate in Keychain Access and its associated private key.
Did You Know?
If you do not see the key here, try looking directly in the keys under your Login key-chain, opening each likely one to see whether there is one associated with the iPhone distribution certificate. If the private key is present, you’re ready to create a distribution profile. If the private key is missing, something went wrong, and you must start from the “cleaning up” step again and repeat the process.
This entire process seems rather unstable at the moment, and many people seem to end up having to repeat it several times before everything works properly. According to reports on the Web, some developers even have to quit and restart the Keychain Access program or Xcode between each step to make it through the entire process successfully. Because Apple is moving toward Xcode performing all the steps automatically for you, this process should be easier soon (we hope).
By the Way
Thankfully, because a certificate’s purpose is to identify you or your team, you generally will need just one distribution certificate for all of your development work. So, once you get this certificate downloaded and installed properly, you should not have to repeat this process.
Creating an App ID
The next thing you need so that you can make use of your distribution certificate is a registered identifier for your application. App IDs are identifiers that are used to distinguish your application from all others in the App Store and to make certain that Apple’s iCloud and push notification services are connecting the right iCloud data, and right push notifications, to your application. You create these unique identifiers through the iOS Provisioning Portal, as well.
Watch Out!: App IDs Are like Tattoos
After you’ve created an App ID, you’re stuck with it, and the closest you can do to removing it is to hide it. Make sure you really want a particular App ID before you create it. Apple doesn’t currently even give you a way to hide App IDs, although if you create more than a few, some of them will inevitably be hidden off the bottom of your screen (probably not the ones you want though). A kind third-party developer has created Safari and Chrome extensions that parse Apple’s iOS Provisioning Portal pages and let you hide selected App IDs. You can find it at https://github.com/simonwhitaker/app-id-sanity/downloads.
To create an App ID in the Provisioning Portal for your application, follow these steps:
1. Navigate to the Provisioning Portal (http://developer.apple.com/ios/manage/overview/index.action) in a web browser and sign in using your developer ID.
2. Click the App IDs category in the navigation list on the left, and then click the Manage tab.
3. Click the New App ID button in the upper right of the Manage tab. A new page loads under the Manage tab, where you set up the appropriate details for your application.
4. Fill in the description with a short descriptive string or name for your App ID. Remember that these IDs are forever, so do not create them unnecessarily, and don’t give them descriptions that you might regret later.
5. Enter the bundle identifier for your application. If you don’t know the bundle identifier, or you want to use something other than the identifier that Xcode created automatically from your initial project setup parameters, follow these steps:
a. Open your iOS project in Xcode.
b. Select the iOS project in the Navigator area, and the iOS application target in the sidebar of the Editor area.
c. Display the Info tab in the Editor area and find and disclose the Custom iOS Target Properties.
d. Find the bundle identifier line. If it contains something like COM.SGF.${PRODUCT_NAME:rfc1034identifier}, and your target is named iBLine, the bundle ID that is being written into the application is COM.SGF.iBLine.
Watch Out!: Case Matters (Kind Of)
There is currently some confusion about case sensitivity of bundle IDs. Although they apparently are not supposed to be case sensitive, it appears that some parts of Xcode and the Provisioning Portal assume that they are lowercase, and some parts do not automatically downcase uppercase characters in the specified string.
The result is that you can get a mixed-case string stuck in the Provisioning Portal, which won’t let you delete it, and which won’t let you actually use it to provision devices because on their end they downcase the strings and then discover a mismatch with the profile.
So, it is currently safest to explicitly downcase your bundle ID manually if you have previously specified a bundle prefix or application ID that would cause a mixed-case bundle identifier to be created.
By the Way
You can set up a wildcard App ID for all the applications developed with a particular bundle identifier prefix if you use a wildcard in place of the product name in the App ID Request page.
It is probably not a great idea to use something like just your company prefix and a wildcard for the App ID, even though that would let you use the same App ID for any application you wanted to provision. A better use is creating wildcarded App IDs for collections of cooperating products that all need access to the same iCloud data storage and so forth.
If I were planning to develop a whole host of bee-related products for SGF, I might use com.sgf.beez.* for my bundle identifier in the Provisioning Portal and com.sgf.beez.ibline for the iBLine bundle identifier in Xcode.
e. If you need to convert your bundle ID manually to lowercase, double-click the Value for the bundle identifier under the Info tab and specify a lowercase and properly formatted string. In Figure 22.4, I set the iBLine target we’ve been working on to use com.sgf.ibline as the bundle identifier.
Figure 22.4. Setting the bundle identifier to use a name with all lowercase letters.
6. Back in the Provisioning Portal, make sure that the bundle seed ID is set to use your team profile. Depending on your configuration, the Provisioning Portal may require that you explicitly set this value, or it may have it automatically configured with no options for you to select.
7. After you have the Create App ID page in the Provisioning Portal configured approximately as shown in Figure 22.5, click the Submit button.
Figure 22.5. Creating an App ID with a description of the App ID and a bundle identifier.
8. The App IDs page should reload, and your newly created App ID should show up in the list, similar to what is shown in Figure 22.6. If you need to modify its configuration (for example, to enable access to iCloud data containers, or to configure for access to Apple’s push notification service), you can set up those features by clicking the Configure button at the right of the App ID details.
Figure 22.6. The App ID has been successfully set up. If you need to make any adjustments to the configuration, click the Configure option at the right end of the line.
Creating a Distribution Provisioning Profile
After you have successfully installed a distribution certificate and configured an App ID for your product, you can put these together to create distribution profiles for your application. Your distribution profiles can either associate specific iOS devices with the App ID and your identifying certificate or they can be App Store distribution certificates that enable distribution of your application through the App Store for anyone to download or purchase. To create a provisioning profile for your application using your distribution certificate, follow these steps:
1. Navigate to the Provisioning Portal (http://developer.apple.com/ios/manage/overview/index.action) in a web browser and sign in using your developer ID.
2. Click the Provisioning category in the navigation list on the left. Then click the Distribution tab along the top of the work area. Remember that the pages for the Distribution and Development tabs look quite similar and have an insidious and annoying tendency to try to trade places when you’re not looking.
3. Click the New Profile button near the top of the page that’s displayed for the Distribution tab.
4. Enter a profile name. This should be adequately informative that you can tell what the profile is for from the name. For iBLine, I’m naming my profile App Store Distribution for iBLine.
5. From the pop-up menu for the App ID, pick the App ID you just created for your application.
6. Decide whether you want to distribute your application via the App Store or via Ad Hoc distribution and select the appropriate option. If you decide to use Ad Hoc distribution, you must also pick the devices where the profile will enable the application to be installed.
By the Way
Usually, you would use the App Store for your final production builds and Ad Hoc distribution for your development team for testing. If you use Ad Hoc distribution, you must send your built products to your team members yourself, instead of using the App Store to distribute your product. In the next hour, we cover Ad Hoc distribution, including the Enterprise type of distribution whereby your users can download and install your app directly on their iOS device.
Watch Out!: Developer Apps Are Not for Sharing
Do not use the Ad Hoc distribution mechanism to distribute software to people who are not members of your development team. Unless you have an Enterprise developer account, which enables distribution to arbitrary devices in an enterprise, Apple reserves the right to revoke developer credentials without warning and without recourse if you distribute software to end users, rather than developers, outside the App Store mechanism.
7. After filling out the Distribution Provisioning Profile page approximately as shown in Figure 22.7, click the Submit button.
Figure 22.7. Setting up the Distribution Provisioning Profile.
A new page loads under the Distribution tab for provisioning in the Provisioning Portal. It should contain a new line listing your just created profile, probably with a status of Pending.
8. Wait a minute or two, and then reload the page in your browser. When your newly created distribution profile status changes to Active and a Download button appears in the available actions for it, click Download.
9. Navigate to the downloaded file (it should have the extension .mobileprovision) in the Finder and double-click it. Xcode launches if it is not already running, and the Organizer opens.
10. Select the Devices tab on the toolbar of the Organizer and the Provisioning Profiles item in the Library group of the Organizer sidebar.
11. Look for a new profile line that matches the Distribution Provisioning Profile you just created. If everything worked, and you’ve been following along with similar configurations for your iOS application build, the Organizer should show you something like what is shown in Figure 22.8, where the most important detail to check is that the Status line for my App Store distribution for iBLine profile says “Valid Profile.”
Figure 22.8. After creating your Distribution Provisioning Profile, go to the Organizer and verify that the status line for your profile says “Valid Profile.”
Congratulations, you’ve made it through the certificate installation and provisioning profile creation process successfully. Now you can move on to the final step of making Apple’s required tweaks in your application for submitting to the App Store and finalizing the submission process.
Begin Soapbox Mode
A lot of people are annoyed that Apple requires all this certificate and provisioning business for distributing iOS applications and wonder why they cannot just build apps and distribute them like they can OS X applications. The answer is that iPhones are phones, and first and foremost as phones, they must function as phones.
That means that if someone picks one up and dials for emergency help, it had better function as a phone and dial properly. If just anyone could write apps and distribute them without restriction, there’s a very real chance that a broken application or a malicious application could interfere with the basic phone functionality. This might not bother you on your phone-turned-development platform, but for many people, their iPhone is just a phone (and might be their only phone).
Be careful what you wish for, too. For instance, unless you think your grandmother (standing in for all our grandmothers) is sufficiently savvy enough to keep malicious applications off of her phone, and unless you are comfortable with the fact that her phone could potentially crash during an emergency, don’t wish too hard for easy, open development and distribution mechanisms for iOS apps.
Summary
This hour walked you through the process Apple requires to get your application set up to begin the App Store submission process or to prepare the app for Ad Hoc distribution. These steps are the practical requirements that you must complete to create a certificate that guarantees your identity and the app’s authenticity; to create a unique identifier so that the app can find its data in the cloud and receive notifications if needed; and to create a provisioning profile that associates the App ID, your identifying distribution certificate, and the hardware on which the app is allowed to run.
There are a few steps where optional configuration is possible, such as configuring the App ID (using the Configure button on the App IDs page in the Provisioning Portal) to enable iCloud support or modifying the Distribution Provisioning Profile (using the Modify button on the Distribution tab of the Provisioning page) to change the profile name. To a large extent, however, the steps in this hour are almost identical for every iOS application that you decide to provision and distribute.
Q&A
Q. Is there a way to move my distribution certificate from the machine I created it on to another machine?
A. Yes. To do this, you need to export both the private and public keys for your distribution certificate and copy them to the new machine. It is recommended that you copy them and store them somewhere secure on a CD or other durable media for safekeeping anyway, because if you lose the private key, all your provisioning profiles will become invalid and you’ll have to delete them all and start again. Apple details the process for copying the keys at http://developer.apple.com/library/ios/#technotes/tn2250/.
Q. I’m getting a weird error when I try to install an iOS App Store provisioning profile that says something about there being no devices configured for development under my profile. But I have one (or more) iOS devices set up for development and can see them in the Provisioning Portal. What’s up?
A. Developer, meet another Xcode bug. The problem is really that you don’t have an OS X device registered with the development portal. I know you’re working on an iOS project. Xcode should, too, but well, it is Xcode. Sometimes you have to remember that it is still growing and treat it like it is a bit daft. To correct the problem, select your OS X machine from the sidebar of the Devices tab in the Organizer. On the page that appears, click the Enable Developer Mode button, wait until Xcode comes back from thinking to itself, and then click the Add to Portal (+) button at the bottom of the Organizer. Now go back and try to install your provisioning profile. Bug, meet developer. Squash.
Q. This hour talked a bunch about setting up provisioning for iOS devices. Do I have to go through all of this rigmarole for provisioning OS X machines, as well?
A. Not all of it, at least at the moment. When you build an OS X application, you produce a standalone OS X application that you can double-click and run in the Finder and that you can copy to other machines and run the same way. You do have to do some of this if you want to distribute through the App Store for OS X applications, however.
Workshop
Quiz
1. Why might the Organizer tell you that your distribution provisioning profile is invalid?
2. Can you delete that App ID you created as a joke, with that uncomplimentary reference to your boss’s receding hairline?
3. Should you just use the wildcard team App ID for all of your apps and avoid the risk of creating something you’ll wish you hadn’t later?
Answers
1. There are several possible causes. The most likely is that you do not have a private key installed for the distribution certificate in your keychain. If you have, or can obtain a copy of it from somewhere, finding the file, quitting Xcode, and double-clicking it to install it into your keychain should cause Xcode to improve its behavior on the next launch. If you do not have access to the private key, you must start at the beginning of this hour, delete the broken certificate from your keychain, and create a new one. If you already have the private key and it is already installed, you’ve hit an Xcode bug. You can do one of two things: Quit and restart Xcode, export the certificate and private key from your keychain, delete them from the keychain, and reinstall them from the exported files, reboot, or various combinations of these things. Alternatively, you can just delete the key and certificate and start over from the top. The “delete and do it again” option is often a faster route to getting Xcode to recognize the key properly than any amount of trying to convince it to pay attention to the already properly configured certificate that’s right under its nose.
2. No. App IDs, like diamonds, are forever. This is frustrating, but it actually makes sense. App IDs uniquely associate applications and their iCloud data, notifications, and other resources that really should be unique to the application. If you could delete an App ID, someone else on your team could possibly create another app with the same ID and completely confuse things by having a different app that appears to want access to the same iCloud storage and push notification services. Think twice before creating App IDs that might haunt you later.
3. That depends. If you want to let all your applications have access to the same collection of iCloud data and notifications, using the team wildcard solves your App ID dilemma and keeps your collection of App IDs from growing out of bounds. If you need to partition your iCloud data so that only some is shared between only some apps, you need to create additional, only partially wildcarded App IDs for each application group.
Activities
1. Recruit a friend for your development team and add his iPhone to your list of development devices. Then create a new Ad Hoc distribution profile that includes both your iOS device and his iOS device and install it in Xcode.
2. Sneak a peek in the Build settings for your project, looking for the Code Signing group. Configure one of the Debug or Release build configurations to use your new Ad Hoc distribution profile, and experiment with Archiving and Sharing your application with your new development team member. If you get stuck, don’t worry. We cover this in more detail in the next hour.
3. Reenable one of the crash-producing bugs that we previously fixed in iBLine. A good choice would be the bug that bit us when the last point was deleted from the list and then another point was added. Install this buggy version of iBLine on your iOS device, and then crash the app. Now connect your iOS device to your computer, launch Xcode, and open the Organizer. Select the Devices tab, and look under the Device Logs in the group for your iOS device. Pretty cool, huh? This is also the mechanism you use to connect crash reports that your users might generate back to your code. If you receive crash reports, you can drag them into the log area to add them to the list and connect them to Xcode.