SAML authentication for Citrix XenDesktop and XenApp

Citrix recently published an article announcing a technical preview of their SAML based authentication technology for XenApp and XenDesktop.

This is a very exciting development and something we have been seeking for a long time. Federated authentication has been around for some time in various guises for NetScaler, Web Interface and for some older XenApp versions, actually KCD: the latter mysteriously disappearing in version 7.x of XenApp and XenDesktop.

At Synergy 2016, Citrix announced a new version of XenApp/XenDesktop, version 7.9. This latest release, available early June 2016, incorporates their SAML authentication technology.

“The 7.9 release introduces Federated Authentication Service to provide secure business-to-business access to contractors and partners as well as simplify Active Directory domain integration as part of an acquisition, merger or cloud transition. The new Federated Authentication Service integrates with SAML-based identity providers via Citrix NetScaler to allow each business unit to manage their own accounts yet still provide the same secure, remote access to their virtualized apps and desktops hosted on XenApp and XenDesktop”

In this blog we will explain how to implement the Technical Preview. Use it to become familiarized with the technology, in order to be ready to implement it when the release of XenApp/XenDesktop version 7.9 becomes available.

Please do not implement the technical preview in a live environment.

Outside of Windows 10, the classical Microsoft Windows logon experience supports two basic authentication mechanisms:

  • username/password
  • smart card

With the Federated Authentication Service, Citrix introduce a Virtual Smart card (VSC) to logon to a Windows server or desktop. In order to facilitate this module an additional component is introduced, the “User Credential Service” (UCS). This service acts as an intermediary between StoreFront, Virtual Desktop Agent (VDA) and the Certificate Authority (CA).

Here is a high level architecture overview of the technology:


When implementing the Federated Authentication Service, please ensure to meet the necessary prerequisites. The following components should be up and running in your infrastructure:

  • SAML 2.0 Identity Provider (IdP)
  • Public Key Infrastructure (PKI) / Certificate Authority (CA)
  • NetScaler
  • Desktop Delivery Controller (DDC), StoreFront and a VDA

The installation and initial configuration of these components are not covered in this blog post. With the above prerequisites in mind, the starting point for this configuration was an operational Active Directory, AD Certificate Services,  AD Federation Services, together with the NetScaler and XenDesktop environment. Before installing the Federation Authentication Service a basic preflight of Citrix services was conduced.

  • Being able to use the Receiver for Web to access StoreFront.
  • Launching a published application with the Windows Receiver on a Windows device
  • Using NetScaler Gateway for:
    • Client less access to StoreFront
    • ICA-proxy towards XenDesktop
  • Authenticating with LDAP on Netscaler Gateway


User Credential Service Installation/Configuration

The installation of User Credential Service (UCS) consists of three components that need installing:

  • Citrix.UCSLogonDataProvider-x64.msi. Install this on the StoreFront server.
  • Citrix.Authentication.IdentityAssertion_x64.msi. Install this on the VDA server. (If you have a 32-bit VDA installation, use the 32-bit version.)
  • UserCredentialService.msi. Install this on a Windows 2012 R2 server.

We encountered some issues with the installation and only manged to get them properly installed when launching from a Administrative Command Prompt by calling msiexec.exe with the /i switch.

Configure your AD and for smart card logon

The Active Directory Domain Controller environment needs to be configured for certificate authentication by ensuring that there are up-to-date Domain Controller certificates installed for Kerberos authentication. Look at CTX206156 for an example deployment.


Logon to your StoreFront server and open PowerShell as an administrator. Run the following commands:

& "$Env:PROGRAMFILES\Citrix\Receiver StoreFront\Scripts\ImportModules.ps1"
$siteId = 1
Install-DSUcsClaimsFactory -siteId $siteId -virtualPath "/Citrix/StoreAuth"
Install-DSUcsLogonDataProvider -siteId $siteId -virtualPath "/Citrix/Store"

Change the virtualpath parameter so that this matches your StoreFront installation paths.

Group Policy (GPO)

When you have installed the UCS component, locate the  CitrixUserCredentialService.admx/adml GPO template and copy this file to the GPO template location. (C:\Program Files\Citrix\UserCredentialService\PolicyDefinitions)

Create a new GPO object and locate the Administrative template for Citrix Components/Authentication


Enable the “User Credential Service” and enter the FQDN of the server that is hosting the User Credential Service.

Enable “Virtual Smartcards” and specify the “Prompt Scope” and “Consent timeout” value. In our setup we used the default values.

Close the GPO and apply it on your StoreFront servers and VDA’s

Run gpupdate on your StoreFront servers and VDA’s. Verify if the GPO is active by opening the Registry and browse to:


Verify if the FQDN of your UCS server is listed


Logon to the UCS server. Open the Citrix User Credential Service console and Select your UCS server. If you did not start the USC console with a local admin account you will be prompted for credentials.

The initial setup is a three-step process:


  1. Deploy certificate templates to AD Certificate Services.
    • These three templates will be installed and enabled on your Certificate Authority
    • Citrix_RegistrationAuthority_ManualAuthorization

    • Citrix_RegistrationAuthority

    • Citrix_SmartcardLogon

    • The technical preview does add the templates, but the initial ACL is incomplete. Open the certificate template plugin in MMC and add “Authenticated Users” with read permissions to all three Citrix templates.
  2. Setup Certificate Authority
    • Specify the correct Certificate Authority
  3. Authorize the UCS service
    • Authorizing is done in two steps. First request a certificate and then approve the pending request on your CA. Once the certificate is issued and installed, the initial setup for the UCS service is complete.


The next step is to configure the “User Roles” on the UCS. The setup of UCS includes one “default” role. You can specify which role you would like to use in the GPO. If you do not specify a role in the GPO the default role will be used. In our test setup, we’ve used the default role.

  • Specify the list of StoreFront server you would like to use the specific role
  • Specify the list of VDA’s you would like to logon to with the specific role
  • Specify the list of Users you would like to logon to StoreFront with the specific role

Specify all the above settings and we are done with the configuration of the UCS.



The technical preview does not open up the local firewall yet on the UCS server. Configure the local firewall manually to accept incoming requests on port 80.

NetScaler Gateway Authentication/Session Profile

Once the installation and configuration of the UCS is complete, we can begin with the configuration of the Netscaler Gateway setup.

The setup used in testing is similar to this schematic:


Authentication Profile

  • Import your ADFS signing certificate (public key only)
  • Create a SAML authentication server
  • Create a SAML authentication policy and bind the SAML authentication server
  • Bind the SAML authentication policy to the Netscaler Gateway virtual server
add ssl certKey adfs_signing_cert -cert adfs_signing_cert.cer

add authentication samlAction adfs_auth_svr -samlIdPCertName adfs_signing_cert" -samlSigningCertName <nsg_fqdn> -samlRedirectUrl "https://<adfs_fqdn>/adfs/ls" -samlUserField "Name ID" -samlIssuerName <nsg_fqdn>

add authentication samlPolicy adfs_auth_pol ns_true adfs_auth_svr

bind vpn vserver nsg_vsrv -policy adfs_auth_pol -priority 100


AD FS Configuration

We’ll need to establish a relying party trust on the AD FS server between it, as the identity provider (IdP), and the NetScaler Gateway virtual server, a service provider (SP),  configured for use with SAML 2.0 protocol/authentication.

Initially, create a metadata.xml file on and place this on the Netscaler

metadata.xml eample file:

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="_724200788f8391f96053f72adc628fecc808d09a" entityID="<nsg_fqdn>">
 <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol urn:oasis:names:tc:SAML:1.1:protocol urn:oasis:names:tc:SAML:1.0:protocol">
 <init:RequestInitiator xmlns:init="urn:oasis:names:tc:SAML:profiles:SSO:request-init" Binding="urn:oasis:names:tc:SAML:profiles:SSO:request-init" Location="https://<adfs_fqdn>/adfs/ls"/>
 <ds:KeyInfo xmlns:ds="">
 <NSG Cert in pem format, public key only>
 <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<nsg_fqdn>/cgi/samlauth" index="0"/>

Next, logon to the AD FS server and create a new Relying Party Trust using the wizard. In the wizard point to the metadata.xml file on the NetScaler.


Open the properties of the Relying Party Trust and uncheck “Monitor replying party” on the Monitoring tab


Remove the Encryption certificate on the Encryption tab


Set the secure hash algorithm to SHA-1 on the Advanced tab.


Click on OK. This completes the initial configuration of the Relying Party Trust in AD FS.


ADFS needs to pass two claim on to the NetScaler gateway virtual server in order to correctly process the authentication process. Right click on the NSG relying party trust en select “Edit claim rules”. Add a Send LDAP attributes and Send Claims using a custom rule.

Send LDAP attributes Claim (Send UPN as NameID)

c:[Type == "", Issuer == "AD AUTHORITY"]
 => issue(store = "Active Directory", types = (""), query = ";userPrincipalName;{0}", param = c.Value);

Send Claim using a custom rule (Send LogoutURL)

 => issue(Type = "logoutURL", Value = "https://<adfs_fqdn>/adfs/ls/", Properties[""] = "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified")

Session Profile

  • Create a NSG session profile
  • Create a NSG session policy and bind the session profile
  • Bind the NSG session policy to the Netscaler Gateway virtual server
add vpn sessionAction ses_prof_rfw -transparentInterception ON -defaultAuthorizationAction ALLOW -SSO ON -ssoCredential PRIMARY -icaProxy ON -wihome "https://<storefront_fqdn>/Citrix/<rfw_path>" -wiPortalMode NORMAL -clientlessVpnMode OFF

add vpn sessionPolicy ses_pol_rfw "REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver" ses_prof_rfw

bind vpn vserver nsg_vsrv -policy ses_pol_rfw -priority 100


StoreFront configuration

Configure StoreFront to fully delegate the authentication to NetScaler. Logon to the StoreFront server and open the StoreFront management console. Browse to the Manage Authentication Methods and select “Pass-through from NetScaler Gateway”.


Select Configure Delegated Authentication and check “Fully delegate credential validation to NetScaler Gateway”.



Ready to test the configuration

Having configured the Federated Authentication Service, we are ready to test it. The technical preview has only support for RfW and a Windows Receiver.

  • Open a browser and browse to your NSG virtual server.
  • Your browser redirects you to the AD FS server for authentication.
  • Once AD FS has completed authentication, the browser is returned to NSG and you will be logged on to StoreFront.
  • Launch a published application or desktop and seamless logon will commence.

This is how it looked in our environment:




StoreFront troubleshooting is described here:

Desktop Agent

To enable tracing, create a folder named c:\logs, and set permissions so that the Broker Agent Service can write to it. Open the BrokerAgent.exe.config file in c:\Program Files\Citrix\Virtual Desktop Agent

Add a line:

<add key="Citrix.Authentication.IdentityAssertion.LogFileName" value="c:\logs\ucs.log"/>

User Credential Service

To enable tracing, create a folder named c:\logs, and set permissions so that the User Credential Service can write to it. Open the Citrix.Authentication.UserCredentialService.exe.config file in C:\Program Files\Citrix\UserCredentialService

Add a line:

<add key="Citrix.Authentication.UserCredentialService.LogFileName" value="c:\logs\ucs.log"/>


Federated Authentication Service Blog