Sending Apple Push Notifications in ASP.NET and C# – part 2 (Generating APNS Certificates)
In last post we covered concepts of push notification, and in this post we will learn how to generate Apple Push Notification certificate to sign our requests.
Why do you need an Apple APNS certificate?
Apple requires that each organization maintain their own certificate to ensure a secure mechanism for their corporate devices to communicate across Apple’s push notification messaging network.
Generating the Apple Push Notification SSL certificate on Mac:
To request an iPhone Development Certificate, you first need to generate a Certificate Signing Request (CSR) utilizing the Keychain Access application in Mac OS X Leopard. The creation of a CSR will prompt Keychain Access to simultaneously generate your public and private key pair establishing your iPhone Developer identity. Your private key is stored in the login Keychain by default and can be viewed in the Keychain Access application under the ‘Keys’ category. To generate a CSR:
1. In your Applications folder, open the Utilities folder and launch Keychain Access.
2. In the Preferences menu, set Online Certificate Status Protocol (OSCP) and Certificate Revocation List (CRL) to “Off”.
3. Choose Keychain Access -> Certificate Assistant -> Request a Certificate from a Certificate Authority. Note: If you have a noncompliant private key highlighted in the Keychain during this process, the resulting Certificate Request will not be accepted by the Program Portal. Confirm that you are selecting “Request a Certificate From a Certificate Authority…” and not selecting “Request a Certificate From a Certificate Authority with …”
4. In the User Email Address field, enter your email address. Please ensure that the email address entered matches the information that was submitted when you registered as an iPhone Developer.
5. In the Common Name field enter your name. Please ensure that the name entered matches the information that was submitted when you registered as an iPhone Developer.
6. No CA (Certificate Authority) Email Address is required. The ‘Required’ message will be removed after completing the following step.
7.Select the ‘Saved to Disk’ radio button and if prompted, select ‘Let me specify key pair information’ and click ‘Continue’.
8.If ‘Let me specify key pair’ was selected, specify a file name and click ‘Save’. In the following screen select ‘2048 bits’ for the Key Size and ‘RSA’ for the Algorithm. Click ‘Continue’.
9.The Certificate Assistant will create a CSR file on your desktop.
Submitting a Certificate Signing Request for Approval
- After creating a CSR, log in to the iPhone Developer Program Portal and navigate to ‘Certificates’ > ‘Development’ and click ‘Add Certificate’.
- Click the ‘Choose file’ button, select your CSR and click ‘Submit’. If the Key Size was not set to 2048 bits during the CSR creation process, the Portal will reject the CSR.
- Upon submission, Team Admins will be notified via email of the certificate request.
- Once your CSR is approved or rejected by a Team Admin, you will be notified via email of the change in your certificate status.
Approving Certificate Signing Requests
- After submitting a CSR for approval, Team Admins will be directed to the ‘Development’ tab of the ‘Certificates’ section. Here, CSRs can be approved or rejected by clicking the corresponding action next to each request.
- Once a CSR is approved or rejected, the requesting Team Member is notified via email of the change in their certificate status. Each iPhone Development Certificate is available to both the Team Member who submitted the CSR for approval and to the Team Admin(s).
Downloading and Installing Development Certificates
- In the ‘Certificates’ > ’Distribution’ section of the Portal, control-click the WWDR Intermediate Certificate link and select “Saved Linked File to Downloads” to initiate download of the certificate.
- On your local machine, double-click the WWDR Intermediate certificate to launch Keychain Access and install.
- Upon CSR approval, Team Members and Team Admins can download their certificates via the ‘Certificates’ section of the Program Portal. Click ‘Download’ next to the certificate name to download your iPhone Development Certificate to your local machine.
- On your local machine, double-click the downloaded .cer file to launch Keychain Access and install your certificate.
- Team Members can only download their own iPhone Development Certificates. Team Admins have the authority to download the public certificates of all of their Team Members. Apple never receives the private key for a CSR. The private keys are not available to anyone except the original key pair creator and are stored in the system keychain of that Team Member.
Generating an App ID
- Team Agents or Team Admins should navigate to the ‘App ID’ section of the Program Portal.
- Click ‘Add ID’.
- Enter a common name for your App ID. This is a name for easy reference and identification within the Program Portal.
- Enter a Bundle Identifier in the free-form text field. The recommended usage is a reverse-domain name style string, e.g., com.domainname.applicationname. For a suite of applications sharing the same Keychain access, you should use a wild-card character in the Bundle Identifier
(e.g. com.domainname.* or *). This Bundle Identifier will need to match whatever CF Bundle Identifier you use for your application in Xcode.
- You need to create an App ID without .* in the iPhone developer Portal. An App ID without .* means its unique and works only for a single application(for Push-Notification).
- Click ‘Submit’. At this time, the 10 character Bundle Seed ID is generated and concatenated with the Bundle Identifier you entered. This resulting string is your App ID. Note: The Bundle Seed ID does not need to be entered into Xcode.
- Generate a new App ID for each set of applications with shared Keychain Access needs. If you are creating a suite of applications that will share the same Keychain access (e.g. sharing passwords between applications) or have a set of applications with no Keychain Access requirements, create a single App ID for all applications utilizing a trailing asterisk as a wild-card character.
Registering an App ID for Apple Push Notification service
- In the App ID section of the Program Portal, locate the App ID you wish to use with the Apple Push Notification service. Only App IDs with a specific bundle ID can be used with the APNs. You cannot use a “wild-card” application ID. You must see “Available” under the Apple Push Notification service column to register this App ID and configure a certificate for this App ID.
- Click the ‘Details’ link next to your desired App ID.
- In the Configure App ID page, check the Enable Push Notification Services box and click the Configure button. Clicking this button launches the APNs Assistant, which guides you through the next series of steps that create your App ID specific Client SSL certificate.
- Download the Client SSL certificate file to your download location. Navigate to that location and double-click the certificate file (which has an extension of cer) to install it in your keychain.
- When you are finished, click Done in the APNS Assistant.
- Double-clicking the file launches Keychain Access. Make sure you install the certificate in your login keychain on the computer you are using for provider development. The APNs SSL certificate should be installed on your notification server.
- When you finish these steps you are returned to the Configure App ID page of the iPhone Dev Center portal. The certificate should be badged with a green circle and the label “Enabled”.
- To complete the APNs set-up process, you will need to create a new provisioning profile containing your APNs-enabled App ID.
Creating a Development Provisioning Profile
- In the ‘Provisioning’ section of the Portal, Team Admins should click ‘Add’ on the Development tab.
- Enter a name for the provisioning profile.
- Specify which devices will be associated with the provisioning profile. You must specify a device in order for that device to utilize the provisioning profile. If a device’s UDID is not included in the provisioning profile the profile and your application cannot be installed on that device.
- Specify which iPhone Development Certificates will be associated with the provisioning profile. You must specify an iPhone Development Certificate in order for the application code signed with that same certificate to run on the device.
- Specify a single App ID for the Development Provisioning Profile. Each Development Provisioning Profile can specify only ONE App ID, therefore, if you have applications requiring different Keychain access, you will need to create a separate Development Provisioning Profile for each of those applications. If you are installing a suite of applications with the same required Keychain access or have a set of applications not requiring access to the Keychain, use an App ID containing the wild-card asterisk character to build all of your applications.
- Click ‘Submit’ to generate your Development Provisioning Profile.
Installing a Development Provisioning Profile
All Team Agents, Admins and Members can download a Development Provisioning Profile from the ‘Provisioning’ section of the Portal after it has been created. Only those developers whose Apple device IDs and iPhone Development Certificates are included in the provisioning profile will be able to install and test their application on their device.
- In the ‘Provisioning’ section of the Program Portal, click the download button next to the desired provisioning profile.
- Drag the downloaded file onto the Xcode application icon in the dock or into the ‘Organizer’ window within Xcode. This will automatically copy the .mobileprovision file to the proper directory. Alternatively, you can drag the .mobileprovision file onto the iTunes icon in the dock or copy the file to ‘~/Library/MobileDevice/Provisioning Profiles’. If the directory does not exist you will need to create it. Click on the ‘+’ button in the Provisioning section of the Organizer window to install your .mobileprovision file.
Building and Installing your Development Application
Now that you have an approved iPhone Development Certificate, an assigned Apple device and a properly installed Development Provisioning Profile, Xcode can now build your application and install it on your development device. If you have a single iPhone Development Certificate and iPhone Development Provisioning Profile, you don’t need to change any settings in Xcode to start running your applications. To compile and install your code:
- Launch Xcode and open your project.
- In the Project Window, select ‘Device – iPhone OS’ from the ‘Device | Debug’ drop down menu in the upper-left hand corner.
- Highlight the project Target and select the ‘Info’ icon from the top menu bar.
- In the Target Info window, navigate to the ‘Build’ pane. Click the ‘Any iPhone OS Device’ pop-up menu below the ‘Code Signing Identity’ field and select the iPhone Development Certificate/Provisioning Profile pair you wish to sign and install your code with. Your iPhone Development certificate will be in bold with the Provisioning Profile associated with it in grey above. In the example below, ‘iPhone Developer: Team Leader’ is the Development Certificate and ‘My First Development Provisioning Profile’ is the .mobileprovision file paired with it.Note: If the private key for your iPhone Development certificate is missing, or if your iPhone Development certificate is not included in a provisioning profile, you will be unable to select the iPhone Development Certificate/Provisioning Profile pair and you will see the following. Re-installing the private key or downloading a provisioning profile with your iPhone Development certificate included in it will correct this.
- In the Properties Pane of the Target Info window, enter the Bundle Identifier portion of your App ID. If you have used an explicit App ID you must enter the Bundle Identifier portion of the App ID in the Identifier field. For example enter com.domainname.applicationname if your App ID is A1B2C3D4E5.com.domainname.applicationname. If you have used a wildcard asterisk character in your App ID, replace the asterisk with whatever string you choose.
In my next post, I will cover Apple Push Notifications certificates installation on windows.