This article provides answers to frequently asked questions on Citrix Secure Mail APNS for IT Admins.For more information on Push Notifications for Secure Mail, refer to Citrix Documentation – Rich Push Notifications for Secure Mail for iOS.
Q1: Why does Secure Mail for iOS require APNS notifications?
A: In Avatar and previous releases, when Secure Mail application is in the background, it relies on background app refresh functionality of the iOS platform to “wake up” the application to:
- Update the badge
- Show notifications (if turned on)
- Sync emails
The frequency algorithm to wake up the application is more or less depending on the app usage (the more frequent the app is in use the more frequent it checks for new mail while in background mode). Therefore, at times the badge or the mails will not sync for hours.
For customers who want near real time of badge update and a higher frequency of mail syncing, it is recommended to use Secure Mail with Push Notifications.
Q2: Is APNS notification an optional feature in Beetlejuice for Secure Mail for iOS?
A: Yes, it is an optional feature in BeetleJuice. It is turned off by default. The Admin will have to enable the feature (as an app specific policy in AppC/ XMS server). If the customer is ok with background app refresh approach when Secure Mail is in background, then this feature does not need to be enabled.
Q3: How about push notifications for Secure Mail for Android?
A: Android OS allows 3rd party applications to maintain server connections both in foreground and background mode. Hence, Secure Mail for Android maintains a persistent ActiveSync connection to sync emails and sync is near real time.
Q4: Will APNS feature in Secure Mail for iOS work with both XM 9 and XM 10 servers?
Q5: What are the supported upgrade paths?
A: The following table provides supported upgrade paths.
Key points (to elaborate on the above table)
- APNs support requires a unique App ID (Apple iOS requirement). Therefore, this solution will be supported for Secure Mail wrapped with a Unique App ID. Secure Mail that is using a provisioning profile created with a wildcard App ID is not supported for APNs.
- It is not possible to upgrade a wildcard App ID wrapped Secure Mail to a Unique App ID wrapped Secure Mail on the users device. A re-install is required. So, for older customers wanting to leverage this push service, you will need to create a Unique App ID in the Apple Developers portal, a new provisioning profile, a new wrapped version of Secure Mail then load this up to the server as a new app.
Q6: Will the APNs feature work with Office365?
A: Yes, O365 is supported in addition to Exchange 2007, 2010 and 2013.
Q7: Is the APNs feature available for Lotus Notes?
A: The Beetlejuice release (10.0.7) only supports Exchange. We will investigate on what web services are available for Lotus Notes. When the due diligence is completed, we will provide a status update.
Q8: Do I need to install any server components on-premise?
A: No. Citrix will host a “listener” service in the cloud. This service will send out push notifications to your user’s Secure Mail application. Note that no personally identifiable information (PII) is stored or flows through this cloud service.
Q9: Why did you go with a cloud first approach for listener service?
A: Key reasons are:
- Zero on-premise server footprint to support APNS notifications
- No hardware/ software/ monitoring/ server scaling work effort for IT administrators
- No change to mail data flow
- Mail data traffic continues to flow between Device and Exchange Server
- No sensitive data sent to listener service by Exchange server
- APNS notification sends only the badge count to Secure Mail application.
Q10: Why does the feature require a listener service? The Native Mail client does not need a listener service.
A: The native mail client on iOS maintains a persistent ActiveSync connection with the exchange server. Apple allows this only for the native mail client. 3rd party mail clients have to leverage APNs to send remote notifications.
In order to support APNs, a server component is required. The server component receives a trigger from the exchange server and then send an APNs notification to Secure Mail application.
Q11: Where is the listener service hosted?
A: The listener service is hosted on Amazon Web Services (AWS). It is configured as an HA/DR service. The listener service will be available in three regions – Americas, EMEA, APAC. The IT admin will have to select the region that is closest to the Exchange Server.
Q12: What is the Citrix hosted listener service URL?
The listener service URLs and IP addresses are based on region:
Configuration and Setup
Q1: What does the customer IT admin need to do to enable APNs push notifications for WM?
A: The document by the Mobility Experts team provides step-by-step instructions and screenshots to set up APNs notifications, Citrix Blog – Mobility Experts: A Step-by-Step Guide to Configuring Secure Mail APNS
Q2: Can I use the MDM server APNs certificate for my Secure Mail App ID?
A: No. The MDM server APNs certificate is required to enable XDM/ XMS manage iOS devices. The Secure Mail APNs certificate is required to support APNs push notifications for the Secure Mail application.
Q3: How do I generate the APNs certificate for Secure Mail?
A: The APNs certificate for Secure Mail application is generated by IT admin using the Apple developer portal. This is the same portal used to register the app with Apple (with a specific app ID). When the APNs certificate is generated, the IT admin can upload that using the Xenmobiletools portal. For more information, refer to the step-by-step instructions from Apple on generating and exporting APNs certificates – Configuring Push Notifications.
Q4: How do I renew the APNs certificate for Secure Mail when it expires?
A: A new APNs certificate should first be generated via the Apple developer portal and exported. You then go to xenmobiletools.citrix.com and update the certificate that has been previously uploaded for Secure Mail. This is done by selecting the ‘Update’ action for the Secure Mail app ID in the uploaded certificates list.
Q5: The Exchange server is behind a firewall. Do I need to allow outbound connection to the Citrix hosted listener service?
A: Yes. Ensure outbound SSL connections are not blocked by the Firewall to the Citrix hosted service for your region:
Q6: How do I configure Exchange to reach the listener service when there is a proxy server?
A: If you have a proxy server, you should allow Exchange to bypass the proxy and route traffic directly to the listener service:
On Exchange for EWS, make the following update to the XML in the web.config file in the ClientAccessexchwebews folder:
<configuration> <system.net> <defaultProxy> <proxy usesystemdefault="false" proxyaddress="http://proxy.ournetwork:8080" bypassonlocal="true” /> </defaultProxy> </system.net></configuration>
For the Proxy: configure the bypass list to allow Exchange to make the connection to the listener service. Depending on the proxy you are using, you can filter this to the specific FQDN for the listener service. Refer to the section under Push notifications: https://msdn.microsoft.com/en-us/library/office/aa579128(v=exchg.140).aspx.
Q7: What are the configurations required when EWS and ActiveSync servers are different?
A: For Secure Mail to be able to connect to the EWS server, the following configuration is required:
Update the hidden policy for the EWS server FQDN in the Secure Mail policy XML file:
If using STA for Secure Mail, then you need to add the EWS FQDN to the background services policy just like the ActiveSync server FQDN.
Note: EWS usage from the Secure Mail application is only during subscription of EWS push notifications. Mail data traffic will continue to flow via ActiveSync.
Q8: Can ActiveSync and EWS use different authentication methods?
A: No, Secure Mail requires that both Activesync and EWS use the same authentication method for SSO. If you want to enable EWS certificate based authentication only for Secure Mail clients so that other EWS mail clients are not impacted, the following configurations can be selected from:
- Using NetScaler KCD: Using the NetScaler AAA and KCD, the certificate can be used to authenticate at the NetScaler and then this is delegated to the Exchange CAS for authentication. See this post for more details on configuring Secure Mail and KCD with NetScaler AAA – How to: Single Sign on to XenMobile Secure Mail.
- New IIS Site on Exchange server with EWS Virtual Directory: Microsoft supports configuring a new EWS directory and ActiveSync directory in a separate IIS site on the Exchange server. This way, authentication methods can be set differently for EWS. Microsoft documentation for a new virtual directory in Exchange
- As part of the site-creation process, you must bind an IP address to the site; each site should have a unique IP address.
- After you assign an IP address, create a DNS record that allows users to access the new website using a new domain name.
- Secure Mail can be configured to connect to this separate site while leaving all other clients to connect to the default site by specifying the FQDN of the new site in the Secure Mail Exchange server policy. This way the Autodiscovery used by other clients will not be impacted by the new configuration and will still connect to the default site.
Q9: What are the configuration changes required when Split Tunneling is set to Off and STA is enabled?
A: NetScaler Gateway must allow traffic from Secure Mail to the Citrix registration service URLs so that the initial registration of the Secure Mail client to the NetScaler does not fail.
Q10: What do I set the Upload Read Ahead Size to?
A: If the Exchange Server is configured for client certificate authentication, the uploadReadAheadSize parameter needs to be changed in IIS for both the EWS site and the ActiveSync site:
- For a 10 MB attachment limit, it needs to be changed to 10485760 (1024 * 1024).
- For details, refer to: http://www.butsch.ch/post/Exchange-20XX-Client-Certificate-und-IIS-ActiveSync-uploadReadAheadSize.aspx.
Q11: How can I verify that the Outbound connections are working and APNs is setup?
- The outbound connection from Exchange to the listener service can be verified either via the Exchange event logs which will log events when a subscription request or notification for a subscription is invalid/fails. You can also run Wireshark traces on the Exchange server to track outbound traffic to the listener service.
- There are two easy checks that can be carried out to know whether APNs is working or the app is still using local badging:
- First, validate that the badge unread count is equal to what you see for your Outlook client on your laptop/desktop.
- As a second check, send the app to the background for more than 5 minutes and then check if the badge is still updating.
Q12: I do not see the Secure Mail updated APNs policies to configure the settings.
A: This is available in the Beetlejuice wrapper. Ensure that with the Beetlejuice upgrade, you are also using the latest version of the MDX toolkit.
Q13: Can I change the APNs policy from OFF to ON or ON to OFF?
A: This can be changed by the Admin from ‘OFF’ to ‘ON’. The next time Secure Mail checks in with the server to get the latest policies, the badge will begin to update. The scenario of going from ‘ON’ to ‘OFF’ is not supported. If turned OFF, the badge will continue to update.
Q14: Where do I upload the APNs certificate?
A: The listener service will require your Secure Mail’s APNs certificate to push notifications to your end users. The APNs certificate is uploaded via https://xenmobiletools.citrix.com. You will need your citrite id to get access to the portal. Ensure to select the 2nd option on the screen: “Upload Secure Mail APNs certificates”.
Q15: Can I upload the same certificate and app ID for multiple regions?
A: Yes, the same certificate and app ID can be uploaded for multiple regions. However, you can only have one entry per region. To upload for multiple regions, each region will need to be registered under a different citrite ID.
Q1: After the admin enables APNs push, what is the end to end flow?
A: The end -to -end flow is as follows:
- User launches APNs enabled Secure Mail application on their device.
- User is prompted by the iOS platform to allow Notifications. User clicks on “Allow”.
- The iOS platform obtains the device token from the Apple Push Notification service (on behalf of the Secure Mail application).
- Secure Mail registers with the Citrix hosted listener service.
- Secure Mail makes an EWS call to subscribe to EWS push notifications for the inbox folder. Upon success, the Exchange server sends the subscription id to Secure Mail.
- Secure Mail updates the Citrix hosted listener service with the subscription id.
- When there is mailbox activity, the Exchange server will send an EWS push notification to the listener service.
- Listener service will send out an APNs push notification via Apple APNs to Secure Mail. The APNs push notification will have the total unread count of the inbox.
- WM will connect to Exchange server via active sync and sync e-mails as well as trigger mail notifications if enabled by the user in Secure Mail settings.
Q2: Does anything need to be configured on the Exchange Server to make it aware of the Listener service?
- EWS Push Notification APIs will be used by Secure Mail to communicate with the Exchange Server.
- For most customers, EWS will be enabled on the Exchange server since Outlook for Mac uses EWS. Ensure with your Exchange Admin that EWS is not blocked or allowed for only specific user agents.
- At FTU, after upgrade, or when the policy change to turn on APNs is received by the client, the client makes a push subscription request to Exchange. The URL of the listener service will also be communicated as part of this request to Exchange. This is how the Exchange server knows which Listener service to communicate with to trigger push notifications to the device.
- Refer to the tech note on EWS Push notifications for complete details of the subscription request from the client.
Q3: What server role on Exchange carries out the communication with the listener service?
A: CAS – Client Access Server
Q4: What kind of information does the Listener service know about a Mailbox?
A: No Personally Identifiable Information (PII) is available to the Listener Service. The Listener service will store the following information:
- Device Token ID: Assigned to the device during initial registration with the listener service
- EWS subscription ID: assigned by Exchange to the client upon EWS Push subscription request
- EWS folder ID of inbox.
- Active Sync ID hashed with SHA-256
- Email address hashed with SHA-256
- iOS version
- APNs specific information: notification id, etc
- No mail data will flow through the listener service.
Q5: How will the actual mail data traffic flow?
A: This will continue to flow between the device and the exchange server via ActiveSync (no change in the behavior).
Q6: What happens if the EWS connection from Exchange to the Listener service fails?
- The connection will be retried for up to 15 minutes based on the algorithm described in this StatusFrequency.
- If within 15 minutes, there is still no success, Exchange will terminate the subscription request for the client.
- When Secure Mail is brought into the foreground, it will check its registration status with the listener service every 5 minutes.
- If it has been 30 minutes since the listener service last received an update from Exchange, the client will send a new subscription request to Exchange since Exchange would have terminated the subscription after retrying for 15 minutes.
Q7: Why are we using ‘Push’ instead of ‘Streaming’ notifications? Microsoft seems to recommend the latter.
A: The only reason Microsoft recommends streaming over push is because of the reduction in overhead of an additional listener service that needs to be written and maintained. Since Citrix is hosting the listener service, a push solution is just as viable and effective.
In addition, to use the streaming approach, the server would have to subscribe itself to Exchange for the updates and would require the credentials of the user. For a cloud based offering, this cannot be done. This would be the approach for an On-prem solution.
Q8: What info will help Citrix support if I need assistance troubleshooting my APNs setup?
- Secure Mail logs – set this to Debug level 10 or 15 (preferred)
- Your APNs tenant ID
- Screenshots of the badge count and AppController policy settings