XenMobile: Configuring WorxMail APNs

This step-by-step guide shows how to configure WorxMail APNs to achieve near real-time mail sync.

A brief history of how mail sync in the background was achieved in WorxMail.

Prior to XM 9.0, WorxMail achieved background sync using a VOIP tagging mechanism, which maintained a constant connection to the server when WorxMail was in the background to deliver near real-time mail sync. However this mechanism has certain drawbacks like battery drain etc.

Thus, the Background Refresh Model was introduced in XenMobile 9.0 to replace the VOIP-tagging mechanism.

This model handles mail sync when WorxMail is in background through callbacks that are invoked by iOS platform. The frequency of callback is determined by iOS and is hard to quantify as it is dependent on Apple’s unpublished algorithms. Users may experience varying levels of delay in automatic sync of mail in Background Refresh Model.

To address the need of near real-time mail sync when WorxMail is in background, Citrix has added Push based notifications that leverage APNs.

At a high level, this is how the flow looks:

  1. At FTU, after upgrade, or when the policy change to turn On APNs is received by the client, the client will make an initial EWS Push subscription request to Exchange with the URL of the listener service and folder ID for badge updates. This is how Exchange knows that it needs to ping the listener service for updates to the client’s mailbox
  2. When there is a mailbox activity (new email, calendar event) for any registered WorxMail user, Exchange server will notify the Citrix Notification service.
  3. The Citrix Notification service will send an APNS based push notification to WorxMail. If the user has installed WorxMail on more than one device, the APNS based notification will be sent to all those devices.
  4. The APNS notification will not have content of the email (Sender, Subject etc).
  5. If WorxMail is in background, upon receipt of APNS notification, WorxMail badge icon will get updated.  The user can then launch WorxMail to sync with Exchange server.
    • Refer to EWS Push Notifications.
    • https://msdn.microsoft.com/en-us/library/office/dn458791(v=exchg.150).aspx

1.1.    Prerequisites

1)      Pre-Configured XMS Server.

2)      MDX ToolKit 10.0.7

3)      Access to Apple Developer portal.

UPDATE: Static IPs are updated in this blog for Citrix Listener Service, these can be used to configure firewall / proxy rules.

4)      Allow outbound SSL (over 443) connection from Exchange Server (or web proxy) to Citrix listener service.

  1. For Americas: https://us-east-1.mailboxlistener.xm.citrix.com  (IP: 52.6.252.176; 52.4.180.132)
  2. For EMEA: https://eu-west-1.mailboxlistener.xm.citrix.com (IP: 54.77.174.172; 52.17.147.220)
  3. For APAC: https://ap-southeast-1.mailboxlistener.xm.citrix.com (IP: 52.74.231.240; 54.169.87.20)

5)      If Exchange Server is configured for client certificate authentication there is one parameter that needs to be updated:

  1. uploadReadAheadSize on EWS folder

http://www.butsch.ch/post/Exchange-20XX-Client-Certificate-und-IIS-ActiveSync-uploadReadAheadSize.aspx

6)      If you have a proxy server, the bypasslist will need to be configured to bypass the proxy for push notifications

  1. Refer to the section under Push notifications:

https://msdn.microsoft.com/en-us/library/office/aa579128(v=exchg.140).aspx

UPDATE: Static IPs are updated in this blog for Citrix Registration Service,  these can be used to configure firewall / proxy rules.

7)    If your NetScaler Gateway configuration includes Secure Ticket Authority (STA) and split tunneling is off, NetScaler Gateway must allow outbound SSL (over 443) connection from NetScaler and WorxMail (when tunneled from Secure Mail)
1. For Americas: https://us-east-1.pushreg.xm.citrix.com (IP: 52.7.65.6; 52.7.147.0)
2. For EMEA: https://eu-west-1. pushreg.xm.citrix.com (IP: 54.154.200.233; 54.154.204.192)
3. For APAC: https://ap-southeast-1. pushreg.xm.citrix.com (IP: 52.74.236.173; 52.74.25.245)

Note: ALL SCREENSHOTS are for representational purposes, they may vary as versions change.

2.1.    Create new App ID and Profile

Step

 
1.           Logon to Apple Developer account. 
2.           Click on Certificates, Identifiers & Profiles.


3.           Under iOS Apps, click on Identifiers.

4.           Under App IDs, click on the + symbol to create a new App ID.You may also modify an existing App ID for WorxMail.


5.           Input App ID Description.


6.           Select Explicit App ID and enter the Bundle ID.Typically Bundle ID follows the naming convention, something like com.companyname.appname


7.           Under App Services, select Push Notifications and select continue.
8.           Select Submit.

9.           Select Done.


10.          Notice that the new App ID is created.

11.          Under Provisioning Profiles, select the appropriate profile based on your need, here in this usecase, selecting a Distribution provisioning profile.


12.          Click on + symbol to add a new Distribution profile.
13.          Select the type of provisioning profile as per the requirement.If you are using an iOS Developer Enterprise Program, you will have to create an In- House distribution profile.In this document we are selecting Ad Hoc; click continue.

14.          Select the App ID that we created in the previous step and hit continue.
15.          Select the appropriate distribution certificate and click on continue.
16.          Select the devices that you wish to include in the provisioning profile.
17.          Name the provisioning profile and click Generate.


18.          Once the provisioning profile is ready, download the provisioning profile.
19.          Click Done.

2.2.    Generate WorxMail APNs Certificate

Step

 
1.           Go to App IDs under Certificates, Identifiers and Profiles.
2.           Click on WorxMail APNs App ID and click Edit button.
3.           Under Apple push notification service SSL Certificates, click on Create Certificate for Production / Development SSL Certificate.Note: At the time of preparing this document we have used Development SSL Certificate, however please use Production SSL Certificate for you to experience WorxMail APNs.
4.           Open Keychain Access to generate CSR.

5.           Go to Certificate Assistant and click on Request a certificate from a Certificate Authority

6.           Enter the User Email Address and Common Name and save the CSR to disk.

7.           Select the destination and click on Save.

8.           Click Done once completed.

9.           On iOS developer portal, click on Continue.

10.          Click on Choose File to upload the CSR file generated.

11.          Browse to the location and select the CSR.

12.          Click Open.

13.          Click Generate.

14.          Download the Certificate on to the MAC device.

15.          Import the cert into keychain access by double clicking it.
16.          Notice the certificate and its corresponding key.

17.          Go to File > Export items on Keychain Access.

18.          Save the Certificate on to a preferred location.

19.          Enter a password and click on OK.

20.          Enter the Login password and click on Allow.

21.          Note the certificate is now exported.

2.3.    Wrap WorxMail APNs

Step

 
1.           Open MDX ToolKit.

2.           Click For IT Administrators and hit Next.
3.           Click on Browse to select the Worxmail ipa file.
4.           Select the ipa file and hit open.
5.           Click Next>.
6.           *Screenshot updated to latest version of toolkit*Hit Next.
7. Update[29 May 15]: Removing this step as it is not required in the latest version of MDX Toolkit
8. Update[29 May 15]: Removing this step as it is not required in the latest version of MDX Toolkit
9.           Upload Provisioning profile, verify details and Click Create.

10.          Select the Output file name and destination folder.

11.          Click Finish once done.

2.4.    Upload WorxMail APNs Certificate

Step

 Note: The Screenshots may vary
1.           Logon to Citrix Push Server portal: https://xenmobiletools.citrix.com
2.           Select Upload WorxMail APNs Certificates

3.           Select the region where your Exchange Server is located and click Next.Note: Only Select Americas for EAR.In this example we have used APAC.

4.           Select Yes, Im Sure.

5.           Enter WorxMail App ID and browse to WorxMail APNs certificate and enter Worxmail APNs certificate password.Click Submit.

6.           Once the Certificate is successfully submitted, a unique Customer ID is generated. Make a note of this customer ID as we will have to enter this in the MDX Policies.

2.5.    Upload WorxMail APNs App to XMS

Step

 
1.           Logon to XMS Server.

2.           Click on Configure > Apps

3.           Click on ADD to add the WorxMail App.

4.           Select MDX.

5.           Click on Upload.

6.           Browse to the WorxMail MDX file, click Open.

7.           Select your Network Access policy.In this example using Tunneled to the internal network. 
8.  Update[20 May 15]: The following screenshot is updated.Push Notifications should be: ON
Push Notifications Region:
For Americas: Americas
For EMEA: EMEA
For APAC: APAC
Push notifications Customer ID, copy the value from step 2.4 -> 6
9.           Click Next.
10.          Click Save.
11.          MDX Application is successfully uploaded.
12.          Once uploaded, you can log off from XenMobile admin Console.

Users are shown a popup to accept Push Notifications from WorxMail, upon accepting they can experience near real-time mail sync.

I have taken care to minimize the formatting errors to my best, however due to updates to the blog few screenshots are not behaving according to the rules of gravity!!! Please excuse formatting and grammatical errors.

Note:

The Apple push services certificate that you are using expires every year, which is just to make sure end users don’t face any inconsistency with push notifications. Just before your old certificate expires, you’ll need to create a new certificate “Apple Push Notification service SSL Certificates” and update it in Citrix portal

Click on this link for Apple Push Sevices Certificate Update