iOS Push Certificate Authentication

Instructions on setting up certificate-based push authentication for iOS.

 Important

We recommend that new applications use token signing for authentication, rather than certificate-based authentication. See:

Apple Setup

Before you can integrate Airship into your iOS apps, there are a handful of steps you must take on the Apple end of things, which requires membership in the iOS Developer Program.

We will be using the Apple Push Notification Service (APNs) as the transport method for iOS push notifications. In the next section we will configure a development app and a production app for push services.

Production vs. Development Apps

When you create or edit an Airship project (and thus its application record on our server), you must select whether your app system is Test (development for sending test messages), or Live (production for sending messages to customers). Apple treats the two servers separately, so a device token for test/sandbox will not work on live/production. Because of this, we suggest making two projects in the Airship dashboard. That way you can continue to build and develop your application even after releasing it, without interrupting your users.

Apple provides two primary types of SSL certificates: The APNs Development iOS certificate and the Apple Push Notification service SSL (Sandbox & Production) certificate. The Sandbox & Production certificate can be used on both test/sandbox and live/production apps, while the APNs Development iOS certificate may only be used with test/sandbox iOS apps.

When building your app using a development provisioning profile, set your Airship project to Test, and upload an APNs Development iOS or Apple Push Services SSL certificate. To push to an app built with a distribution provisioning profile (either with a release build in Xcode, ad hoc distribution, or the iTunes App Store), use a project that is designated as Live, and upload an Apple Push Services SSL certificate.

 Note

To support Catalyst apps in Xcode 11+, it’s necessary that your app be built with a provisioning profile that includes an Apple Developer certificate (for use in Xcode 11 or later) and the Mac capability listed under Enabled Capabilities:

 Warning

Do not a) submit to the App Store or b) test notifications on an ad hoc build while your app’s code is pointing to an Airship app key that is set as Test. Test apps use different tokens that, when included in a push to a Live app, will fail and in many cases cause all other pushes to fail.

Always create a Live Airship project first, and make sure your application code is pointing to the live project’s app key. For more tips on what to check before you release your app, see the iOS Production Launch Checklist.

Get Your Certificate

  1. Log in to the Apple Developer Member Center and go to Account » Certificates, IDs & Profiles, or use this direct link.

  2. In the left side menu, click Identifiers, then click your app’s name in the list of App IDs.

     Note

    If you have not already registered an iOS App ID, click +, select App IDs, and click Continue:

    Fill out the Register an App ID form, making sure to check the Push Notifications checkbox, then click Continue and Register.

    Click your app’s name in the list of App IDs, and skip to step 4 below.

  3. In the list of Capabilities check the box for Push Notifications, then click Configure to continue to the Apple Push Notification service SSL Certificates section. The button will be labeled Edit if it has been configured previously.

     Note

    If the Configure/Edit button is not available, you may not be the team agent or an admin. The person who originally created the developer account is your team agent, and they will have to carry out the remaining steps in this section.

  4. Click Create Certificate to create a Production SSL Certificate. This will generate an Apple Push Notification service SSL (Sandbox & Production) certificate compatible with both the Production and Development environments.

    You should now see the Create New Certificate section to generate an Apple Push Notification service SSL (Sandbox & Production) certificate:

  5. Follow the instructions to create a certificate signing request in the Create New Certificate section, then click Continue after your certificate signing request is uploaded.

    You can now use the newly-created Certificate Signing request to generate the APNs Push SSL certificate. The next step requires the Download button to be active. You may need to reload the page if it is not yet active.

  6. Click Download and save the file for use in the next step, Exporting your .p12 file.

Renewing Your Certificate

If you are renewing either your Test or Live Push SSL Certificate, follow the steps outlined above as if you were uploading the certificate for the first time. There is no need to revoke the previous certificate in order to make this change. There may be two production certificates at the same time, to allow you to continue using the old certificate while uploading the new one.

 Important

Send a test message to make sure that you’ve uploaded the correct, renewed certificate. If you upload the wrong certificate (a certificate not associated with your app and audience) and send a message, Apple will report that your audience is not related to your app, forcing Airship to remove those members of your audience. The Airship error console reports a Rejected Device Token error for each member of your audience when your certificate does not match your app.

Export as a .p12 File

You’re almost there. The final step before heading back over to the Airship application is to save your signing certificate as a .p12 file.

  1. Open the certificate you downloaded in the previous steps, which should open in the Keychain Access app. The certificate should be listed in My Certificates.

  2. Click the certificate in the list, then from the File menu, select Export Items….

     Note

    Be sure to select My Certificates under the Category menu on the lower left-hand side. If My Certificates is not highlighted, you will not be able to export the certificate as a .p12 file.

  3. Save the file in the Personal Information Exchange (.p12) format.

    You will be prompted to create a certificate password. Use this password in the next step: Configure the APNs Service.

Airship Steps

Configure your iOS project for push notifications in the Airship dashboard.

Configure the APNs Service

 Warning

Never use the same push certificate across multiple Airship app keys. You should also never use the same bundle ID across multiple app keys in the same environment (development or production).

Not following these instructions can result in rejected device tokens and APNs feedback processed by the wrong app key. If you need to have a third app key for ad hoc builds (which also use Distribution-type push certificates), the bundle ID should be changed so you can use a different certificate, for example: com.yourcompany.app.adhoc.

You will need the certificate .p12 file and password you generated in the previous section.

  1. Go to Settings » Channels » Mobile App and click Add for iOS.
  2. Select Certificate-based authentication, then enter the certificate password and upload the .p12 file.
  3. Click Add iOS.

Your push certificate is now uploaded and ready for use.