XenMobile: Push Notifications for Secure Mail for iOS

Secure Mail for iOS can receive notifications about email and calendar activity when the app is running in the background or is closed. Secure Mail supports notifications provided through Background App Refresh or push notifications provided through the Apple Push Notification service (APNs).

How Push Notifications Work

During an installation or upgrade, Secure Mail prompts users to allow push notifications. Users can also allow push notifications later by using iOS Settings.

To provide push notifications, Citrix hosts a listener service on Amazon Web Services (AWS) to perform the following functions:

• Listen for Exchange Web Services (EWS) push notifications sent by Exchange Servers when there is Inbox activity. Exchange does not send any mail content to the Citrix service.No personally identifiable information is stored by the Citrix service. Instead, a device token and subscription ID identifies the specific device and Inbox folder to be updated within Secure Mail.
• Send APNs notifications, containing only badge counts, to Secure Mail on iOS devices.

The Citrix listener service does not impact mail data traffic, which continues to flow between user devices and Exchange Servers through ActiveSync. The listener service, which is configured for high availability and disaster recovery, is available in three regions:

• Americas
• Europe, Middle East and Africa (EMEA)
• Asia Pacific (APAC)

For details about the EWS push notification service, see the Microsoft article Notification subscriptions, mailbox events, and EWS in Exchange.

System Requirements for Push Notifications

If your NetScaler Gateway configuration includes Secure Ticket Authority (STA) and split tunneling is off, NetScaler Gateway must allow traffic (when tunneled from Secure Mail) to the following Citrix listener service URLs:

Provisioning profiles and app IDs:

APNs requires a provisioning profile created with an explicit and unique app ID. APNs does not support apps that use a provisioning profile created with a wildcard (*) app ID.

XenMobile Management Tools for APNs signature signing is compatible with these browsers:

• Chrome (minimum version 36)
• Firefox (minimum version 31)
• Internet Explorer 10 or 9
• Safari (minimum version 7)

To access the tools, see XenMobile Management Tools.

Configuring Secure Mail for Push Notifications

App Store distribution

The move to the public app store also simplifies the process of setting up Apple Push Notifications for Secure Mail. You no longer have to request a certificate from Apple and upload it to XenMobile Tools. Instead, on the console, set Push notifications to ON and then select your region.

Configure Exchange and NetScaler to allow traffic to flow to the listener service.

Exchange Server configuration

Allow outbound SSL (over port 443) from your firewall to the Citrix listener service URL for the region where your Exchange Server is located. For example:

If you have a proxy server between EWS and the Citrix listener device, you can do one of the following.

• Send EWS traffic through the proxy and then on to the listener device.
• Bypass the proxy and route EWS traffic to the listener device directly.

To send EWS traffic through the proxy server, configure the EWS web.config file in the ClientAccess\exchweb\ews folder, as follows.

<configuration>
<system.net>
<defaultProxy>
<proxy usesystemdefault=”false”
proxyaddress=”http://proxy.example:8080″
bypassonlocal=”true” />
</defaultProxy>
</system.net>
</configuration>

For Exchange 2013 environments, you must add the system.net section to the web.config file manually. Otherwise, configurations described in this article should work for Exchange 2013. For troubleshooting, contact your Exchange administrator.

To bypass the proxy server, configure the bypass list to allow Exchange to make connections to the Citrix listener service. For details, see “Push Event Notifications” in https://msdn.microsoft.com/en-us/library/office/aa579128(v=exchg.140).aspx.

When Secure Hub is enrolled with certificate-based authentication, you must also configure Exchange Server for certificate-based authentication. For details, see this XenMobile Advanced Concepts article.

NetScaler Gateway configuration

While the Exchange server needs to allow traffic to the listener service, NetScaler must allow traffic to the registration service. In this way, devices can connect to register for push notifications.

If your EWS and ActiveSync servers are different, configure your NetScaler traffic policy to allow EWS traffic.

Enterprise distribution

If you distribute Secure Mail as an enterprise app through Secure Hub, you must generate an Apple Provisioning Profile, which involves requesting a certificate from Apple using XenMobile Tools and uploading the certificate to the XenMobile server. An explicit app ID is required to be able to request a certificate.

Follow these steps to configure enterprise Secure Mail for push notifications :

8. If your previously deployed Secure Mail had a wildcard app ID, let your users know that they must reinstall Secure Mail.

To troubleshoot outbound connections, check the Exchange event logs, which include log entries when a subscription request or the notification for a subscription is invalid or fails. You can also run Wireshark traces on the Exchange Server to track outbound traffic to the Citrix listener service.

For other issues, try the Secure Mail Test Tool.

When does iOS deliver notifications to Secure Mail?

If Secure Mail is running in the foreground, notifications are always delivered to Secure Mail. This is the only time that Citrix can guarantee that notifications are delivered. When Secure Mail enters the background, the application badge count always updates. However, notifications (lockscreen and banner notifications) rely on Background App Refresh and, particularly when iOS suspends or terminates the app, notifications are not a certainty. The following factors are outside the control of Citrix.

The following cases may affect the delivery of notifications:

• The battery is low.
• Secure Mail is not used frequently (rarely opened into the foreground).
• Emails received outside of core usage times in which the app is suspended for an extended period in the background; for example, between midnight and 6 a.m.

Notifications are not delivered to Secure Mail in the following cases:

• If the user closes Secure Mail, until the user manually reopens the app.
• If the system has terminated Secure Mail. and the app has not been automatically restarted.
• When Secure Mail is not active. Important note: Notifications may not be delivered to Secure Mail when it is not active for many reasons, including but not limited to the following cases:
  • If the device is in Low Power Mode and Secure Mail is in the background. This is the most common case in which notifications are not delivered.
  • If Background App Refresh is off for Secure Mail and if Secure Mail is in the background. Note that users control this setting.
  • If the device has poor network connectivity. This situation depends entirely on the iOS device.

When Secure Mail does not receive a notification, Secure Mail does not sync new data to the device. As a consequence, the following situations occur:

• Secure Mail syncs data only when users bring the app to the foreground.
• Lockscreen notifications stop occurring for new mail. Calendar reminders still appear, however.

How does Background App Refresh affect Secure Mail and APNs?

If the user turns off Background App Refresh, the following situations occur:

• Secure Mail does not receive notifications when Secure Mail is not the background app.
• Secure Mail does not update the lockscreen with new email notifications.

Disabling Background App Refresh has a major effect on the behavior of Secure Mail. As stated earlier, badge updates based on APNs still occur, but no email is synced to the device in this mode.

How does Low Power Mode affect Secure Mail and APNs?

The behavior of the system with respect to Secure Mail is the same in Low Power Mode as it is when Background App Refresh is disabled. In Low Power Mode, the device does not wake up apps for periodic refresh and does not deliver notifications to apps in the background. The side effects are therefore the same as those listed in the Background App Refresh section above. Note that in Low Power Mode, badge updates still occur, based on APNs notifications.

How does APNs affect email notifications that appear on the lock screen?

New mail notifications that appear on the device lock screen are generated based on data that is synced down to the device by Secure Mail. Importantly, this information does not come from the listener service.

In order to show new mail notifications, Secure Mail needs to be able to sync data from Exchange so that Secure Mail has the information available to create the notifications.

If APNs notifications are not delivered to Secure Mail in the background, Secure Mail does not detect the notifications and hence does not sync new data. Because no new data is available to Secure Mail, no email notifications are generated on the device lockscreen, even when APNs notifications are not delivered.

What other issues can cause APNs-driven sync to fail in the background?

A number of issues can cause APNs-driven sync requests to fail, including the following:

• An invalid STA ticket.
• A slow network connection. When Secure Mail is woken in the background, the app has 30 seconds to sync all data from the server.
• If the data protection policy is enabled and Secure Mail is woken by an APNs notification, when the device is locked, Secure Mail cannot access the data store and sync does not occur. Note that this is only the case in which the system is attempting to cold start Secure Mail. If a user has already started Secure Mail at some point after unlocking the device, APNs-driven sync succeeds even when the device is locked.

If any of the preceding conditions occur, Secure Mail cannot sync data and hence cannot display locksscreen notifications.

How else does Secure Mail generate lockscreen notifications when notifications are not delivered or APNs is not in use?

If APNs is disabled, Secure Mail is still woken by periodic Background App Refresh events from iOS, assuming that Background App Refresh is enabled and assuming that Low Power Mode is off.

During these wakeup events, Secure Mail syncs new email from the Exchange Server. This new email can then be used to generate email notifications on the lock screen. Thus, even when APNs notifications are not delivered or APNs is disabled, Secure Mail can sync data in the background.

It’s important to note that this will occur less in real time than when APNs is in use and when APNs notifications are delivered to Secure Mail. When iOS routes APNs notifications to Secure Mail, the app immediately syncs data from the server and the lockscreen notifications appear to be real time.

In the event that Background App Refresh wakeups are required, lockscreen notifications do not occur in real time. In this case, Secure Mail is woken up at a frequency that iOS completely determines. As such, some time may elapse between when an email arrives in a user’s Inbox on Exchange and Secure Mail syncs that message and generates the lockscreen notification.

Also note that Secure Mail receives these periodic wakeups even when APNs is in use. In all cases in which Background App Refresh wakes up Secure Mail, Secure Mail attempts to sync data from Exchange.

How does Secure Mail differ from other apps that show content on the lock screen?

A very important difference – and one that leads to confusion – is that Secure Mail does not always show new email in real time on the lock screen in the same way that Gmail, Microsoft Outlook, and other apps do. The primary reason for this difference is security. To align with the behavior of the other apps, the Citrix listener service would require the user credentials to authenticate with Exchange to get the email content and also pass this email content through the Citrix listener service, as well as the Apple APNs service. The approach by Citrix to APNs notifications does not require the Citrix listener service to acquire or store the users’ password. The listener service has no access to the users’ mailbox or password.

A note about the native iOS mail app: iOS allows its own email app to maintain a persistent connection with the mail server, which ensures that notifications are always delivered. Third-party apps outside of the native mail are not allowed this capability.

Gmail app behavior. Google owns and controls both the Gmail app and the Gmail server. This means that Google can read message content and include that message content in the APNs notification payload. When iOS receives this APNs notification from Gmail, iOS does the following:

• Sets the application badge to the value that is specified in the notification payload.
• Displays the lockscreen notification using the message text that is contained in the notification payload.

This is a critical difference: It is iOS, not the Gmail app, that displays the lockscreen notification, based on the data contained in the payload. In fact, iOS may never wake the Gmail app, similar to the way that iOS may not wake Secure Mail when a notification arrives. However, because the payload contains the message snippet, iOS can display the lockscreen notification without any mail data having to be synced to the device.

In Secure Mail, this situation is different. Secure Mail must first sync message data from Exchange before the app can show the lockscreen notification.

Outlook for iOS app behavior. Microsoft controls Outlook for iOS. The organization to which the user belongs, however, controls the Exchange Servers from which data is obtained. Despite this setup, Outlook can display lockscreen notifications based on data that Microsoft provides in the APNs notification, because Outlook for iOS makes use of a model in which Microsoft stores user credentials. Microsoft then directly accesses the user’s mailbox from its cloud service and determines the existence of new mail.

If new mail is available, the Microsoft cloud service generates an APNs notification that contains the new mail data. This model operates in a similar way to the Gmail model, in which iOS simply takes the data and generates a lockscreen notification based on that data. The Outlook iOS app is not involved in the process.

Important security note on Outlook for iOS: There are clear security implications in the Outlook for iOS approach. Organizations need to trust Microsoft with passwords for their users so that Microsoft can access the user’s mailbox, which poses a security risk. For more information about the way Microsoft manages user’s passwords, see this Microsoft Technet article.

For more FAQs specific to administrators on push notifications, please see this Support Knowledge Center article. For more user-specific FAQs, see this article.