Article

Establishing a Token-Based Connection to APNs

Secure your communications with APNs using stateless authentication tokens.

Overview

Token-based authentication offers a stateless way to communicate with APNs. Stateless communication is faster than certificate-based communication because it does not require APNs to look up the certificate, or other information, related to your provider server. There are other advantages to using token-based authentication:

  • You can use the same token from multiple provider servers.

  • You can use one token to distribute notifications for all of your company’s apps.

Token-based requests are slightly larger than certificate-based requests because each request contains the token. You must also update and encrypt your tokens at least once an hour using the provider token signing key that Apple provides you.

Obtain an Encryption Key and Key ID from Apple

You need an APNs authentication token signing key to generate the tokens used by your server. You request this key from your developer account on developer.apple.com, as shown in Figure 1.

Figure 1

Creating an authentication token signing key

Create a new key that supports APNs in your developer account.

When you request a key, Apple gives you:

  • A 10-character string with the Key ID. You must include this string in your JSON tokens.

  • An authentication token signing key, specified as a text file (with a .p8 file extension).

Secure both pieces of information carefully. You will use the authentication token signing key to encrypt your JSON tokens, so this key must remain private to prevent anyone else from generating those tokens.

For detailed instructions on how to request an authentication token signing key, see Communicate with APNs using authentication tokens in Xcode Help.

Create and Encrypt Your JSON Token

The token that you include with your notification requests uses the JSON Web Token (JWT) specification. The token itself contains four key-value pairs, which are described in Table 1.

Table 1

Keys you include in the authentication token

Key

Description

alg

The encryption algorithm you used to encrypt the token. APNs supports only the ES256 algorithm, so set the value of this key to ES256.

kid

The 10-character Key ID you obtained from your developer account; see Obtain an Encryption Key and Key ID from Apple.

iss

The issuer key, the value for which is the 10-character Team ID you use for developing your company’s apps. Obtain this value from your developer account.

iat

The “issued at” time, whose value indicates the time at which this JSON token was generated. Specify the value as the number of seconds since Epoch, in UTC. The value must be no more than one hour from the current time.

The keys are divided between the header and claims payload of the JSON Web Token. The header of the token contains the encryption algorithm and Key ID, and the claims payload contains your Team ID and the token generation time. Listing 1 shows an example of a JSON token for a fictional developer account.

Listing 1

Sample JSON for an authentication token

{
   “alg” : “ES256”,
   “kid” : “ABC123DEFG”
}
{
   “iss”: “DEF123GHIJ”,
   “iat”: 1437179036
}

Encrypt the resulting JSON data using your authentication token signing key and the specified algorithm. Your provider server must include the resulting encrypted data with all notification requests.

For detailed information about the JWT specification, see https://tools.ietf.org/html/rfc7519. For additional information about JWT, along with a list of available libraries for generating signed JWTs, see https://jwt.io.

Attach Your Token to Notification Requests

When creating the POST request for a notification, include your encrypted token in the authorization header of your request. The token is in Base64URL-encoded JWT format, and is specified as bearer <token data>, as shown in the following example:

Listing 2

Adding the authentication token to your POST request

authorization = bearer eyAia2lkIjogIjhZTDNHM1JSWDciIH0.eyAiaXNzIjogIkM4Nk5WOUpYM0QiLCAiaWF0I
		 jogIjE0NTkxNDM1ODA2NTAiIH0.MEYCIQDzqyahmH1rz1s-LFNkylXEa2lZ_aOCX4daxxTZkVEGzwIhALvkClnx5m5eAT6
		 Lxw7LZtEQcH6JENhJTMArwLf3sXwi

For information about how to construct your POST requests, see Sending Notification Requests to APNs.

Refresh Your Token Regularly

For security, APNs requires you to refresh your token regularly. Refresh your token no more than once every 20 minutes and no less than once every 60 minutes. APNs rejects any request whose token contains a timestamp that is more than one hour old. Similarly, APNs reports an error if you recreate your tokens more than once every 20 minutes.

On your provider server, set up a recurring task to recreate your token with a current timestamp. Encrypt the token again and attach it to subsequent notification requests.

See Also

Security

Establishing a Certificate-Based Connection to APNs

Secure your communications with APNs by installing a certificate on your provider server.