Local and Remote Notification Programming Guide: APNs Overview

APNs Overview

Provider Responsibilities

Your provider servers have the following responsibilities for participating with APNs:

• Receiving, via APNs, globally-unique, app-specific device tokens and other relevant data from instances of your app on user devices. This allows a provider to know about each running instance your app.

• Determining, according to the design of your notification system, when remote notifications need to be sent to each device.

• Building and sending notification requests to APNs, each request containing a notification payload and delivery information; APNs then delivers corresponding notifications to the intended devices on your behalf.

For each remote notification request a provider sends, it must:

1. Construct a JSON dictionary containing the notification’s payload, as described in Creating the Remote Notification Payload.

2. Add the payload, a globally-unique device token, and other delivery information to an HTTP/2 request. For information about device tokens, see APNs-to-Device Connection Trust and Device Tokens. For information about the HTTP/2 request format, and the possible responses and errors from APNs, see Communicating with APNs.

3. Send the HTTP/2 request to APNs, including cryptographic credentials in the form of a token or a certificate, over a persistent, secure channel. Establishing this secure channel is described in Security Architecture.

Using Multiple Providers

Figure 6-2 depicts the sort of virtual network that APNs enables for the devices running your apps. To handle the notification load, you would typically deploy multiple providers, each one with its own persistent and secure connection to APNs. Each provider can then send notification requests targeting any device for which the provider has a valid device token.

Figure 6-2Pushing remote notifications from multiple providers to multiple devices

Quality of Service, Store-and-Forward, and Coalesced Notifications

Apple Push Notification service includes a Quality of Service (QoS) component that performs a store-and-forward function. If APNs attempts to deliver a notification and the destination device is offline, APNs stores the notification for a limited period of time and delivers it when the device becomes available again. This component stores only the most recent notification per device and per app. If a device is offline, sending a notification request targeting that device causes the previous request to be discarded. If a device remains offline for a long time, all its stored notifications in APNs are discarded.

To allow the coalescing of similar notifications, you can include a collapse identifier within a notification request. Normally, when a device is online, each notification request that you send to APNs results in a notification delivered to the device. However, when the apns-collapse-id key is present in your HTTP/2 request header, APNs coalesces requests whose value for that key is the same. For example, a news service that sends the same headline twice could use the same collapse identifier value for both requests. APNs would then coalesce the two requests into a single notification for delivery to the device. For details on the apns-collapse-id key, see Table 8-2.

Security Architecture

APNs enforces end-to-end, cryptographic validation and authentication using two levels of trust: connection trust and device token trust.

Connection trust works between providers and APNs, and between APNs and devices.

• Provider-to-APNs connection trust establishes certainty that connection between a provider and APNs is possible only for an authorized provider, owned by a company that has an agreement with Apple for push notification delivery. You must take steps to ensure connection trust exists between your provider servers and APNs, as described in this section.

• APNs-to-device connection trust ensures that only authorized devices can connect to APNs to receive notifications. APNs automatically enforces connection trust with each device to ensure the legitimacy of the device.

For a provider to communicate with APNs, it must employ a valid authentication key certificate (for token-based connection trust) or SSL certificate (for certificate-based connection trust). You obtain either of these certificates from your online developer account, as explained in “Configure push notifications” in Xcode Help. To choose between the two certificate types, read Provider-to-APNs Connection Trust. Whichever certificate type you choose, provider connection trust is prerequisite to a provider sending push notification requests to APNs.

Device token trust works end-to-end for each remote notification. It ensures that notifications are routed only between the correct start (provider) and end (device) points.

A device token is an opaque NSData instance that contains a unique identifier assigned by Apple to a specific app on a specific device. Only APNs can decode and read the contents of a device token. Each app instance receives its unique device token when it registers with APNs, and must then forward the token to its provider, as described in Configuring Remote Notification Support. The provider must include the device token in each push notification request that targets the associated device; APNs uses the device token to ensure the notification is delivered only to the unique app-device combination for which it is intended.

APNs can issue a new device token for a variety of reasons:

• User installs your app on a new device

• User restores device from a backup

• User reinstalls the operating system

• Other system-defined events

As a result, apps must request the device token at launch time, as described in APNs-to-Device Connection Trust and Device Tokens. For code examples, see Registering to Receive Remote Notifications.

Provider-to-APNs Connection Trust

There are two schemes available for negotiating connection trust between your provider servers and Apple Push Notification service:

• Token-based provider connection trust: A provider using the HTTP/2-based API can use JSON web tokens (JWT) to provide validation credentials for connection with APNs. In this scheme, you provision a public key to be retained by Apple, and a private key which you retain and protect. Your providers then use your private key to generate and sign JWT provider authentication tokens. Each of your push notification requests must include a provider authentication token.

  You can use a single, token-based connection between a provider and APNs can to send push notification requests to all the apps whose bundle IDs are listed in your online developer account.

  Every push notification request results in an HTTP/2 response from APNs, returning details on success or failure to your provider.

• Certificate-based provider connection trust: A provider can, alternatively, employ a unique provider certificate and private cryptographic key. The provider certificate, provisioned by Apple when you establish your push service in your online developer account, identifies one topic, which is the bundle ID for one of your apps.

  You can use a certificate-based connection between a provider and APNs to send push notification requests to exactly one app, which you specify when configuring the certificate in your online developer account.

Token-Based Provider-to-APNs Trust

Token-based provider trust employs a certificate of type “Apple Push Notification Authentication Key (Sandbox & Production).” You configure and obtain this certificate using your online developer account, as explained in “Generate a universal provider token signing key” in Xcode Help. This certificate has the following characteristics:

• The one certificate is valid for sending push notification requests for every app associated with your account.

  The certificate is also valid for connections to Apple Watch complications for your apps, and for voice-over-Internet Protocol (VoIP) status notifications for your apps. APNs delivers these notifications even when those items are running in the background. See APNs Provider Certificates for details, and see Voice Over IP (VoIP) Best Practices in Energy Efficiency Guide for iOS Apps.

• When you send a push notification request over a JWT token-based APNs connection, you must include your provider authentication token.

• The APNs authentication key certificate never expires, but you can revoke it permanently using your online developer account; once revoked, the certificate can never be used again

Figure 6-3 illustrates using the HTTP/2-based APNs provider API to establish trust, and using JWT provider authentication tokens for sending notifications.

Figure 6-3Establishing and using token-based provider connection trust

As shown in Figure 6-3, token-based provider trust works as follows:

1. Your provider asks for a secure connection with APNs using transport layer security (TLS), represented as the arrow labeled “TLS initiation” in the figure.

2. APNs then gives your provider an APNs certificate, represented by the next arrow in the figure (labeled “APNs certificate”), which your provider then validates.

   At this point, connection trust is established and your provider server is enabled to send token-based remote push notification requests to APNs.

3. Each notification request that your provider sends must be accompanied by a JWT authentication token, represented in the figure as the arrow labeled “Notification push.”

4. APNs replies to each push, represented in the figure as the arrow labeled “HTTP/2 response.”

   For specifics on the responses your provider can receive for this step, see HTTP/2 Response from APNs.

Certificate-Based Provider-to-APNs Trust

A certificate-based provider connection is valid for delivery to one specific app, identified by the topic (the app bundle ID) specified in the provider certificate (which you must have previously created, as explained in “Generate a universal APNs client SSL certificate” in Xcode Help). Depending on how you configure and provision the certificate, the trusted connection can also be valid for delivery of remote notifications to other items associated with your app, including Apple Watch complications for your apps, and for voice-over-Internet Protocol (VoIP) status notifications for your apps. APNs delivers these notifications even when those items are running in the background. See Communicating with APNs for details, and see Voice Over IP (VoIP) Best Practices in Energy Efficiency Guide for iOS Apps.

With certificate-based trust, APNs maintains a certificate revocation list; if a provider’s certificate is on the revocation list, APNs can revoke provider trust (that is, APNs can refuse the TLS initiation connection).

Figure 6-4 illustrates the use of an Apple-issued SSL certificate to establish trust between a provider and APNs. Unlike Figure 6-3, this figure does not show a notification push itself, but stops at the establishment of a Transport Layer Security (TLS) connection. In the certificate-based trust scheme, push notification requests are not authenticated but they are validated using the accompanying device token.

Figure 6-4Establishing certificate-based provider connection trust

As shown in Figure 6-4, certificate-based provider-to-APNs trust works as follows:

1. Your provider asks for a secure connection with APNs using transport layer security (TLS), represented as the arrow labeled “TLS initiation” in the figure.

2. APNs then gives your provider an APNs certificate, represented by the next arrow in the figure (labeled “APNs certificate”), which your provider then validates.

3. Your provider must then send its Apple-provisioned provider certificate (which you have previously obtained from your online developer account, as explained in “Generate a universal APNs client SSL certificate” in Xcode Help) back to APNs, represented as the arrow labeled “Provider certificate.”

4. APNs then validates your provider certificate, thereby confirming that the connection request originated from a legitimate provider, and establishes your TLS connection.

   At this point, connection trust is established and your provider server is enabled to send certificate-based remote push notification requests to APNs.

APNs-to-Device Connection Trust and Device Tokens

Trust between APNs and each device is established automatically, without participation by your app, as described in this section.

Each device has a cryptographic certificate and a private cryptographic key, provided by the operating system at initial device activation and stored in the device’s keychain. During activation, APNs authenticates and validates the connection to the device, based on the certificate and key, as shown in Figure 6-5.

Figure 6-5Establishing connection trust between a device and APNs

As shown in Figure 6-5, APNs-to-device trust works as follows:

1. Trust negotiation begins when the device initiates a TLS connection with APNs, as shown in the top arrow in the figure.

2. APNs returns an APNs certificate to the device.

3. The operating system validates this certificate and then, as shown in the “Device certificate” arrow, sends the device certificate to APNs.

4. Finally, as indicated by the bottom arrow in the figure, APNs validates the device certificate, establishing trust.

With a TLS connection established between APNs and the device, apps on the device can register with APNs to receive their app-specific device tokens for remote notifications. For details and code examples, see Registering to Receive Remote Notifications in Configuring Remote Notification Support.

After receiving the device token, an app must connect to the app’s associated provider and forward the token to it. This step is necessary because a provider must include the device token later when it sends a notification request, to APNs, targeting the device. The code you write for forwarding the token is also shown in Registering to Receive Remote Notifications.

Whether a user is activating a device for the first time, or whether APNs has issued a new device token, the process is similar and is shown in Figure 6-6.

Figure 6-6Managing the device token

Obtaining and handling an app-specific device token works as follows:

1. Your app registers with APNs for remote notifications, as shown in the top arrow. If the app is already registered and the app-specific device token has not changed, the system quickly returns the existing token to the app and this process skips to step 4.

2. When a new device token is needed, APNs generates one using information contained in the device’s certificate. It encrypts the token using a token key and returns it to the device, as shown in the middle, right-pointing arrow.

3. The system delivers the device token back to your app by calling your application:didRegisterForRemoteNotificationsWithDeviceToken: delegate method.

4. Upon receiving the token, your app (within the delegate method) must forward it to your provider in either binary or hexadecimal format. Your provider cannot send notifications to the device without this token. For details, see Registering to Receive Remote Notifications in Configuring Remote Notification Support.

When your provider sends a push notification request to APNs, it includes a device token that identifies a unique app-device combination. This step is shown in the “Token, Payload” arrow between the provider and APNs in Figure 6-7. APNs decrypts the token to ensure the validity of the request and to determine the target device. If APNs determines that the sender and recipient are legitimate, it then sends the notification to the identified device.

Figure 6-7Remote notification path from provider to device

After the device receives the notification (and after the final step shown in Figure 6-7), the system forwards the remote notification to your app.

Provisioning Procedures

APNs is available to apps distributed through the iOS App Store, tvOS App Store, and Mac App Store, as well as to enterprise apps. Your app must be provisioned and code signed to use APNs. If you are developing as part of a team, most of these configuration steps can be performed only by a team agent or administrator.

For information on how to configure push notification support in Xcode and in your online developer account, read “Configure push notifications” in Xcode Help.