Push notifications for Secure Mail

Secure Mail for iOS and Secure Mail for Android can receive notifications about email and calendar activity when the app is running in the background or is closed. Secure Mail for iOS supports notifications provided through Remote Push Notifications provided through the Apple Push Notification service (APNs). Secure Mail for Android supports notifications provided through the Firebase Cloud Messaging service (FCM).

How push notifications work

To provide push notifications for iOS and Android, 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.

• Send FCM notifications to Secure Mail on Android 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)

System requirements for push notifications

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

Configuring Secure Mail for push notifications

To set up Apple Push Notifications or FCM for Secure Mail for app store distribution, in the Endpoint Management console, set Push notifications to ON and then select your region. The following figure shows the setting for iOS.

For Android, the following figure shows the same Push notification setting as for iOS. In addition, if the EWS is hosted in a different region from where the mail server resides, complete the EWS HostName setting. The default setting is empty. If you leave the setting empty, Endpoint Management uses the host name of the mail server.

Configure Exchange and Citrix ADC 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 Exchange Web Services (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="true" bypassonlocal="true" />
</defaultProxy>
</system.net>
</configuration>

For more details about configuring proxies, see Proxy 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.

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

Citrix Gateway configuration

Although the Exchange Server needs to allow traffic to the listener service, Citrix ADC 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 Citrix ADC traffic policy to allow EWS traffic. For more information about integrating Citrix Endpoint Management with Citrix Gateway, see the section Integrating with Citrix Gateway and Citrix ADC.

Troubleshooting

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.

Secure Mail Push Notifications FAQs

When does Android deliver notifications to Secure Mail?

In Android, notifications are always delivered to Secure Mail.

How does FCM 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.

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

When you receive a new mail, the You have new messages FCM notification appears. Once the email sync completes in the background, the new mail appears in Secure Mail.

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 lock screen, even when APNs notifications are not delivered.

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 in the background app.

  Note:

  This situation occurs only if Rich Push notifications are disabled. For more information about Rich push notifications, see Rich push notifications for Secure Mail for iOS.

• Secure Mail does not update the lock screen 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.

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

Various issues can cause FCM-driven sync requests to fail, including the following:

• An invalid STA ticket.
• When Secure Mail is woken in the doze mode, the app has 10 seconds to sync all data from the server.

If any of the preceding conditions occurs, Secure Mail cannot sync data. As a result, lock screen notifications do not appear.

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 locks screen notifications.

How else does Secure Mail generate lock screen 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 lock screen notifications appear to be real time.

In the event that Background App Refresh wakeups are required, lock screen 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 these two situations:

• When an email arrives in a user’s Inbox on Exchange.
• When Secure Mail syncs that message and generates the lock screen 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?

An important difference, that may lead to confusion, is that Secure Mail does not always show new email in real time on the lock screen. This behavior differs from Gmail, Microsoft Outlook, and other apps. The primary reason for this difference is security. To align with the behavior of the other apps, the Citrix listener service requires the user credentials to authenticate with Exchange. The credentials are required to get the email content. The credentials are also required to pass this email content through the Citrix listener service and to 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 behavior 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 lock screen 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 lock screen 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 lock screen 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 lock screen 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 lock screen notifications based on data that Microsoft provides in the APNs notification. The reason is that 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 the Gmail model, iOS simply takes the data and generates a lock screen 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. This trust allows Microsoft to access the user’s mailbox, which poses a security risk.

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