Configure Citrix XenMobile Certificate Based Authentication with SecureMail SSO, APNS & Microsoft CA

Citrix lack of decent documentation in not a secret and has been discussed with their management not so far ago with a promise of swift action on the matter. This is about to change in the near future and until then, community  is the place to go for proper documentation on configuration requirements for different deployment scenarios.

I have learned this the hard way over the course of my career, every environment is different and with these differences, present new challenges in terms of design and configuration. In a recent engagement, we had the task of deploying Citrix XenMobile with Certificate Based Authentication on top of Citrix SecureMail with Certificate Based Authentication for seamless single sign on experience.

In very big organizations, separation of duties and services render access to different components required for a specific configuration very hard. In our case access to CA components and Exchange components existing configuration was tough especially when changes were requested given that these components are not custom built for XenMobile sole use but rather for many other services as well.

Citrix documentation on this matter is barely fair because most of this configuration is actually done on CA  Issuing/Enrollment and Exchange rather than XM and NS. CA related configuration is found scattered over multiple Citrix support articles depending on the error faced but then again you would have to face and troubleshoot all of these related issues to get everything configured properly.

I am going to document required configuration on Certificate Authority Issuing/Enrollment, Exchange, XenMobile, and NetScaler to achieve Client Based Authentication for XenMobile and SecureMail with APNS. This might not be as well a complete guide but based on the amount of logs reviewed and troubleshooting done, should be close enough.

Microsoft Issuing Certificate Authority:

1- Create a User Certificate Template for XenMobile use by duplicating the built-in Users Template and applying the listed below configuration:

Authenticated Users Must have Read and Enroll permissions or obviously an certificate would not be issued to them when enrolling:

Assign XM Service Account full permissions on the enrollment template though not mandatory but saves times when troubleshooting.

For the purpose of creating a User Enrollment Certificate, assign the Enroll permissions to the Users template and you can disable after the creation of the certificate is done. The reason I say this is because many environments tend to disable the default Users template and create one of their own.

Open MMC with XenMobile Service Account and make sure to open Certificates with My User Account:

Choosing to “Export all Extended Properties” will ensure that all Root and Intermediate certificates required are imported to XenMobile when this certificate is added to XenMobile.

We need to manually export Root and ALL Intermediate certificates associated with this certificate in order to import into NetScaler and link them accordingly. This is a VERY important step so make sure that all Root and Intermediate certificates are exported in Base-64 format for NetScaler and note down how these certificates are chained.

Now we have two certificates at least, one is the exported .PFX XenMobile Enrollment Template and the other is the exported Root CA for NetScaler ( any Intermediate need to be also exported ).

This is to be done on Issuing CA and on Web Enrollment CA in order to make sure that enrollment will not fail with 50X and 40X errors. The output of this PowerShell command should be empty and if it is not, all certificates that show inside this file need to be deleted from Trusted Root Certificates on all CA related machines.

Get-Childitem cert:\LocalMachine\root -Recurse | Where-Object {$_.Issuer -ne $_.Subject} | Format-List * | Out-File “c:\computer_filtered.txt”

Microsoft Web Enrollment Certificate Authority:

2- Most probably, Microsoft Certificate Authority has separated roles on different servers, so we have to make sure that IIS is configured accordingly as its the most important piece of the puzzle especially with Web Enrollment CA role.

Certificate bound to Web Enrollment server needs to have Negotiate Client Certificates  and DS Mapper Usage enabled in order for XenMobile to connect successfully and SecureMail to SSO using User Cert. To ensure the same, we run the following command and what matters here is the certificate bound to 0.0.0.0:443 :

netsh http show sslcert

In order to enable this setting, we need to unbind the certificate and rebind it again with it enabled through the following commands. Note that Citrix/Microsoft command in some troubleshooting articles do NOT include the DS Mapper Usage enable so be careful, I have added the same below and  that the three values are extracted from the above command output and pasted into the below:

netsh http delete sslcert ipport=0.0.0.0:443

netsh http add sslcert ipport=0.0.0.0:443 certhash=cert_hash appid={app_id} certstorename=store_name verifyclientcertrevocation=Enable VerifyRevocationWithCachedClientCertOnly=Disable UsageCheck=Enable DSMapperUsage=Enable clientcertnegotiation=Enable

Run the following as well on Enrollment server to make sure that no non self signed certificates are going to break certificate enrollment:

Get-Childitem cert:\LocalMachine\root -Recurse | Where-Object {$_.Issuer -ne $_.Subject} | Format-List * | Out-File “c:\computer_filtered.txt”

XenMobile:

3- Make sure that port 443 is open from all XenMobile servers to all Web Enrollment servers and proceed to configure XenMobile PKI and Gateway settings:

Notice that because we exported all certificate extended properties earlier, Root and Intermediate CAs are imported with the certificate and should show as Root or Intermediate. By default the certificate should be named ( Users ) but have recently seen it named in the service account name it was requested with but don’t worry it wont brake the setup so just ignore.

Test the connection and make sure it is successful, don’t forget to add / after the certsrv URL. If connection fails to certsrv then double check your IIS settings as the problem lies there for sure or port 443 is not opened.

Only check the direct issuing CA here ( mostly intermediate in large environments ) which would be normally the one directly above your certificate in the chain.

The key size here should match wat was chosen when the XM User Cert Template was created. For the signature algorithm, I have seen CA templates with SHA256withRSA and XM was configured with SHA1RSA with everything working fine.

NetScaler:

4- Make sure that port 443 is open from Subnet IP SNIP to all Web Enrollment servers and proceed to adding/linking Root/Intermediate CAs:

I don’t have any intermediate certificates here but if you do, make sure they are LINKED in the correct order as shown in your User certificate chain, this is very crucial.

A CA certificate needs to be added to the XenMobile Access Gateway Virtual Server, note here that Root and ALL intermediate certificates associated with user cert need to be added here using the same procedure:

A primary certificate authentication policy needs to be added to the XenMobile Access Gateway Virtual Server as well with following config:

Exchange 2016 (CAS 2013):

5- Make sure that port 443 is open from all exchange servers to web enrollment servers and the following IIS settings set:

Make sure that both NetScaler SNIP and Exchange CAS servers have access to Citrix APNS regions as per below and also make sure that Push notification is enabled inside SecureMail. If using proxy on Exchange servers, the following needs to be completed else disregard:

DS Mapper Usage brakes SecureMail SSO if disabled so make sure it is enabled after re-adding the certificate using the command below. Default command available in some Citrix/Microsoft troubleshooting articles doesn’t include the DS Mapper Usage by default so use the command provided here:

netsh http delete sslcert ipport=0.0.0.0:443

netsh http add sslcert ipport=0.0.0.0:443 certhash=cert_hash appid={app_id} certstorename=store_name verifyclientcertrevocation=Enable VerifyRevocationWithCachedClientCertOnly=Disable UsageCheck=Enable DSMapperUsage=Enable clientcertnegotiation=Enable

There are other ways of achieving SSO to SecureMail with SecureHub and client settings but some customer requirements differ from prerequisites for that method.

Troubleshooting Tips:

• Web Enrollment IIS Logs and search for ZDM and SNIP in order to determine if its a 200 OK or failed with specific 4XX or 5XX error.

• Concentrate troubleshooting efforts on SecureHub logs and Web Enrollment IIS logs rather than XenMobile or NetScaler logs especially when dealing with Citrix Support since it will take a very very long time and it seems they only understand binary  .

• Always use Fresh SecureHub and SecureMail logs when troubleshooting. Uninstall both and install again with directly sending over the logs after failure.

• SecureHub Error and Warning entries are very important but always look at the DEBUG as well. Most Certsrv errors I have found lurking in Debug such a Cannot Sign CSR or 4XX Forbidden.

• IIS settings on Web Enrollment are the source of most errors and any failure needs to be troubleshooted using the IIS logs for that server.

• Recently at a customer site, we had to add all intermediate certificates to Access Gateway as OCSP Optional not only Root cert with error AG chain broken.

• Check the certificate bind properties on Web Enrollment and Exchange CAS to make sure that Negotiate Client Certificate and DS Mapper Usage are enabled because if not SSO may brake. It is recommended to restart the whole server rather than restart IIS alone or IIS Admin Service.

• A very good document to have in hard is the Certificate Based Authentication, Issues and Troubleshooting for iOS Devices .

Conclusion:

We have been assured that Citrix documentation is going to get better in the coming months and some change notifications on Citrix documentation page has been starting to popup so that is always good news. I would love to see Citrix support ( procedures ) get better as well because they really do miss common sense sometimes and it is very hard to convince them other wise.

Salam .