How to setup Apple Push Notification (APN) service for WSO2 EMM iOS Agent
Sending a notification is a great way of keeping users informed with timely and relevant content, whether an app is running in the background or inactive. Apple Push Notification service (APNs) is a platform notification service created by Apple Inc. that enables third party application developers to send notification data to applications installed on Apple devices. It is a robust and highly efficient service for propagating information to iOS and macOS devices. Using this notification service, it can display a message, play a distinctive sound, or update a badge on an app icon.
In addition to APNs and developed app, another piece is required for the delivery of remote notifications. That is known as the “provider” which originates the notifications. In this case, it is the WSO2 EMM server. WSO2 EMM server has the following set of responsibilities:
- It receives device tokens and relevant data from WSO2 EMM iOS agent app.
- It determines when remote notifications need to be sent to a device.
- It communicates the notification data to APNs, which then handles the delivery of the notifications to that device.
For each of these notifications, WSO2 EMM Server:
- Constructs a JSON dictionary with the notification’s payload.
- Attaches the payload and an appropriate device token to an HTTP/2 request.
- Sends the request to APNs over a persistent and secure channel that uses the HTTP/2 network protocol.
For each successful HTTP/2 request, APNs forwards the corresponding notification payload to the user’s device. That device handles the receipt of the payload and manages interactions with the user and the delivery of the payload to the iOS agent app.
WSO2 EMM has implemented this capability over an open source java-apns client library where it provides a highly scalable interface to the APN server, while still being simple and modular.
First of all, let’s figure out the basic concepts and how APN service works.
The Path of a Remote Notification
Every provider is responsible for originating remote notifications related to their apps. In this case it is WSO2 EMM server. When it is decided to send a notification, EMM server packages the notification data into a JSON dictionary with help of java-apns client library, which constitutes the payload to deliver to the device. It packages that payload into an HTTP/2 request that includes a device token and other information to use for the delivery of the notification. With the help of java-apns client then forwards that request to APNs, which then routes the payload to the appropriate user device. Below figure shows the path of the delivery process.
The device token included in each request represents the identity of the device receiving the notification. APNs uses device tokens to identify each unique app and device combination. It also uses them to authenticate the routing of remote notifications sent to a device. Each time iOS agent runs on a device, it fetches this token from APNs and forwards it to WSO2 EMM server. Then EMM server stores the token and uses it when sending notifications to iOS agent app and device. The token itself is opaque and persistent, changing only when a device’s data and settings are erased. Only APNs can decode and read a device token.
Registering to Receive Remote Notifications
As it mentioned before, each time iOS agent app launches, it gets registered with APN server. The process as follows:
- Obtain a device token from APNs using platform-specific APIs.
- Send the device token to EMM server.
The obtained device tokens are unique to the iOS agent app and device. So EMM server uses the device token and any other data to generate remote notifications for the specific device. When sending remote notifications to a device, it includes the device token with the operation data.
Important: Cashing device tokens is not advised due to the fact that device tokens are unique to an app and device, they can change over time. Hence always get them from the system when it is needed. The device token can change at any time but is guaranteed to be different when the user restores their device from a backup, when the user installs app on a new device, and when the user reinstalls the operating system. Fetching the token from the system ensures that you always have the current token needed to communicate with APNs. In addition, if the token has not changed, fetching it is fast and does not incur any significant overhead.
Having said that, WSO2 EMM server also follows that best practice by always retrieving the latest device token from the iOS agent app.
Security Architecture
To ensure secure communication, APNs servers employ connection certificates, certification authority (CA) certificates, and cryptographic keys (private and public) to validate connections to, and identities of, providers and devices. APNs regulates the entry points between providers and devices using two levels of trust: connection trust and device token trust. Connection trust establishes certainty that APNs is connected to an authorized provider, owned by a company that Apple has agreed to deliver notifications for. It is provider’s responsibility to take steps to ensure connection trust exists between provider servers and APN server. APN server also uses connection trust with each device to ensure the legitimacy of the device. Connection trust with the device is handled automatically by APNs.
Device token trust ensures that notifications are routed only between legitimate start and end points. A device token is an opaque, unique identifier assigned to a specific app on a specific device. Each app instance receives its unique token when it registers with APNs. The app must share this token with its provider so that the provider can include the token in communications with APNs. The presence of the device token in notification requests ensures that the notification is delivered only to the unique app-device combination for which it is intended.
Why WSO2 EMM requires APN service
WSO2 EMM offers set of operations such as getting device’s current location, send messages to device and ring device with respect to iOS device type. In order to get these operations delivered to devices EMM uses APNs so that devices receive operations even if the agent is inactive. Hence if an user expects to have these operations be working on their EMM setup, it is necessary have APNs be configured prior to execute these operations from the WSO2 EMM.
Configuring WSO2 EMM iOS agent to work with APN service
Prior to configuring the EMM, there are couple of things that should be done in order to use the iOS agent for an user/organization.
- Should have an Apple Developer Enterprise Account
- Should have a valid distribution certificate which is obtained from Apple.
Note: To learn about above requirements, please follow my previous article “How to export iOS In-House developed app as an enterprise application”.
So let’s start the process.
WSO2 EMM iOS agent’s source code is open source and can be downloaded from emm-agent-ios github repository. Clone this repository and then open the project from Xcode.
Once it is opened, change the Bundle Identifier “org.wso2.carbon.emm.ios.agent” to something that matches with the organization. For an instance “org.<organization-name>.emm.ios.agent”. Then select the development team, provisioning profile and signing certificate from the Xcode. To learn the process of how to generate these certificates can be found in my previous post.
Now log into the Apple developer portal and navigate to “Certificates, IDs & Profiles” section. Under “Identifiers” section click “App IDs” and see whether the bundle id that we declared via Xcode is listed. In order to get it listed under this section, make sure that computer has the internet connection and Xcode has a valid developer account.
Then click on the bundle ID and hit edit button.
To create a APNs SSL certificate, first tick “Push Notification”. Once it is enabled portal will allow to generate both development and production certificates.
Obtaining development certificate will allow users to test their apps with APNs sandbox environment which Apple advices developers to use it for testing purposes. Once an app is tested and ready for the deployment, then user/organization can create a production certificate.
Important: It is necessary to keep in mind that when an app is signed by a development provisioning profile and pushed to a device, some services that app is going to use will only work in sandbox environment. For an example, if an app uses APNs and has a production SSL certificate. After it is signed by a development provisioning profile the push token that is generated and use to send notifications to a device will only work in sandbox APN server (gateway.sandbox.push.apple.com). The reason is, because the generated APN device token is different from development profile to distribution profile. So if an organization is at an app development or testing phase, it’s better to use sandbox environment, hence obtaining a development SSL certificate is ideal for that situation.
So let’s create a development SSL certificate for APNs. Click “Create Certificate” button under development SSL certificate section.
Then create CSR file using keychain access tool in Mac OS as follows.
Launch “Keychain Access” application. Click “Keychain Access” from the menubar and select “Request a Certificate from Certificate Authority” under “Certificate Assistant”.
Set user email address, common name and select “Saved to disk” radio button. Then hit “Continue”. In the prompt window, set the CSR file location to be stored and click done. At the end of this process, certSigningRequest file will be generated.
Now let’s go back to portal and upload that generated certificate to the portal and hit “Continue”.
Now the development SSL certificate is ready to be downloaded and click “Download” and double click on the downloaded file. Then it will open from the keychain access tool.
As the figure 11 shows, “Apple Development iOS Push Services” certificate and private key can be found in the keychain access tool. Then its time to export the certificate from keychain access in p12 format. Right click on the certificate and select “export”.
Set the location to save the certificate and it will prompt to set a password as well. Once it is saved on the disk, rename the “p12” extension to “pfx” (since p12 and .pfx are in the exact same PKCS #12 format, changing extension will not affect the file) so that it can be uploaded directly to the EMM server without any issue.
Finally, log into EMM and navigate to “Configuration Management” -> “Platform Configurations” -> “iOS Configurations”. Under “iOS APNS Configurations”, upload the “pfx” file which is just created and set the password. For “Mode”, select “Developer” since the obtained SSL certificate is development.
Note: As it is mentioned before, if an user/organization export the agent as an enterprise app, it is required to have a production SSL certificate for APN service. Otherwise development SSL certificate can be used.
So that’s it! Now users can execute above mentioned set of operations via WSO2 EMM without a hassle.
Troubleshoot
To verify whether the SSL APNs certificate is valid, there’s a free tool “Easy APNS Provider” where it allows users to attach the APN certificate and send notifications to devices.
In this way, it is easier to check the validity of the generated certificate. To obtain the APNs device token, user will have to enable debug on the iOS agent side via Xcode.
Summary
The objective of this article is to provide a comprehensive information about the Apple Push Notification service and how it is used in WSO2 EMM for its iOS agent. Finally, the article explains how to configure iOS agent as well as the EMM server to use APNs.
Reference
[1] https://en.wikipedia.org/wiki/Apple_Push_Notification_Service
