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


The evolution of access control

Do you remember what it was like when everyone had desktop computers and data security focused on the best way to physically lock computers to heavy desks?

Many customers are asking us the question how they would be able to take control again of their “environment” where the environment now has become scattered amongst on-premise or outsourced resources, Cloud resources and Mobile devices.

In this blog post, we’ll review the ways security and access control have changed over the years, highlighting how Enterprise Mobility Management solutions (we’ll be showing you the  Microsoft Enterprise Mobility suite here) are poised to provide integrated solutions for the current world with mobile devices and online (Cloud) services.

We’re using the Microsoft Enterprise Mobility (EMS) solution as the explicit example here, because Microsoft has a different vision on how to solve these issues compared to other solution providers like MobileIron or Airwatch. The main and most important difference in vision between those providers, is the way they are handling the delivery of (mobile) applications and data. Where MobileIron and Airwatch (as an example, there are many other providers out there) are desperately trying to create “controlled bubbles”, the Microsoft vision is to use the native device and application experience, while protecting the access towards the application and the data. That’s a fundamental other way of taking care of the challenge here. It’s not that the “bubble” approach is wrong to begin with (even more, there are specific use cases to use the approach) but the end-user will lose the “native device experience” but even more the end-user will end up using the EMM solution provided mobile apps to replace the native apps…

bubble approach

Picture: showing the MobileIron “apps” with the “bubble” approach 

We’ve seen cases at customers where the “bubble” approach failed or at least was not that successful as end-users did not fully accepted the fact that they where losing the native device apps like Outlook mail of ActiveSync. Let’s not get going about the quality of those non-native EMM apps here but you’re able to imagine the challenges there for the EMM providers 😉

So what’s the vision of Microsoft here ? Well, Microsoft has of course the best interest in using their  applications but on the other hand they have a great bundle of solutions to their availability. But first, let us have a look in the way things have been changed the past years for now:

Mobile Access version 1: Mobile Laptops

In the past, corporate data was hosted on-premises. It was accessed by desktops that were physically connected to the corporate network. Then, laptops emerged as the dominant corporate device, and the Virtual Private Network (VPN) was born.
VPNs provided 3 primary functions:

1. They made it possible for laptops to reach corporate services on the Intranet
2. They restricted corporate access to Internet-connected laptops
3. They helped prevent data loss by encrypting communications and running agents on the laptops that helped contain data

Over time, VPN technology evolved. The criteria that could be used for access control (e.g. require the laptop to be domain-joined) expanded and the technology to prevent data loss matured.
Eventually, new types of VPNs such as SSL VPNs emerged. SSL VPNs enabled app-specific, as opposed to device-wide, access to corporate services from the Internet. This reduced the attack surface and also enabled new scenarios such as accessing corporate services from web browsers running on unmanaged devices.

Mobile Access version 2: Smart Mobile Devices

Later, when smart mobile devices arrived in the corporate computing landscape, they needed access to corporate resources, and VPN technology was the tool available to provide that. Mobile devices, primarily connected to the Internet, needed network reachability to corporate services. However, theses always-on devices brought many security concerns from their early general lack of IT controls. This drove demand for complementary technology to the VPNs which would help protect data.
All of this created an opportunity for integrated solutions based on Mobile VPN, Mobile Device Management (MDM), and Mobile Application Management (MAM). The management system would provision a VPN profile to a mobile device and thereby give it controlled access to corporate services on the Intranet. MDM and MAM features would help provide data protection on mobile devices analogously to the agents deployed by VPN clients on laptops.
Over time, Mobile VPNs emerged into per-app Mobile VPNs. The per-app variety provided similar benefits to mobile devices that SSL VPNs had provided to mobile laptops in the past. They reduced the attack surface and enabled new scenarios.

Mobile Access version 3: Identity-based Access Control and Data Protection

Now, we are in an era of mobile access where increasing amounts of corporate data lives outside of the network perimeter. Data still lives on corporate networks, but it’s also in cloud services, on mobile devices, and in mobile apps. Perhaps one day you won’t have any corporate data left on-premises, but the moment you start adopting cloud services you need to rethink the way access is controlled and data is protected.


Picture: showing that within the current world the apps, devices and resources are scattered

In the mobile-first, cloud-first world, a fundamentally different approach was needed, so we built access control and data protection directly into mobile devices, mobile apps, and the cloud infrastructure itself.  In this world your network perimeter is replaced by an “identity perimeter.”


Picture: showing that within the perimeter protection layers do not apply anymore

That’s what Microsoft has built with Office 365 and the Enterprise Mobility Suite, as a supplement to the classic VPN provisioning mechanisms that other  EMM providers like MobileIron or Airwatch have for on-premises apps. Microsoft EMS delivers integrated identity, access control, management, and data protection – built to protect your corporate data wherever it lives, using technologies like Device and Application Management, Information Right Management, Risk based contextual based authentication, Analytic Security Services and more.

With Microsoft EMS, whenever a mobile device or app attempts to authenticate to an online service (Microsoft or 3rd party) or on-premises web app, subjects the request to criteria you define, consulting with the management system as needed. Is the mobile device managed and compliant with your IT policies? Is the mobile app managed? Has the user presented multiple forms of authentication? Is the PC domain-joined and managed or controlled ? Is the request coming from the corporate network or the internet? All of these criteria and more are provided without the need for VPN. It’s just built-in the solution.
The diagram below shows how Microsoft EMS ensures that you have the access controls in the cloud needed to replace the access controls in your VPNs.


Picture: illustration of conditional access using Microsoft EMS

In addition to providing cloud access control, Microsoft EMS also provides native data protection. Again, this is based on identity and integrated with management.
Was a corporate identity used to access the data? If yes, then the mobile apps will prevent the data from being shared with consumer apps or services via Save-As, Open-In, clipboard, etc (Intune MAM with or without device enrollment into MDM). Is the document itself explicitly protected by an access policy (using IRM like Azure RMS)? If so, enforce access control on that file, even when it roams outside of apps and devices under management.

This integrated approach to data loss prevention enables the same application to isolate the corporate and personal data that it handles. This means your employees will not have to use separate apps for work. They can just use native or Office mobile apps for work and personal use and the right protections will apply at the right times. The diagram below shows this concept.


Picture: showing the Microsoft EMS approach to handle Data Loss Prevention

As mobile access evolves from VPN-based to identity-based, we foresee several benefits:

  • Cost savings compared to VPNs. VPN technology is typically expensive and complex. Deploying VPN agents, profiles, and certificates is also complex and expensive. As more and more of your data moves to the cloud, you’ll enable larger and larger populations of cloud-only users that don’t require a VPN and everything it carries.
  • Simpler access infrastructure to operate. Instead of operating a global scale network perimeter with various proxies, gateways, and VPNs, you just need to connect your existing on premise AD with the Azure Active Directory. From there, Office 365 and other SaaS apps will route their authentication through Azure AD and your modern access controls will be enforced.
  • Better end-user experiences. With EMS’s identity-based access control, your end users will not have to install and launch separate VPN apps. The access control experience is natively a part of the sign-in experience in the mobile apps. Since your traffic isn’t bounced from the Internet to the Intranet and back, your employees get better latency and performance in their mobile apps.
  • Positioned for the future. Once your basic cloud access infrastructure is in place, you have a solid foundation for future innovation. Because the capabilities are provided from the cloud, improvements come often and automatically. You don’t need to plan upgrades or migrations to start to take advantage of the latest and greatest. Compare this to your VPN infrastructure today and the tremendous amount of effort it takes to upgrade to the latest and greatest.

As Route443, we’re often working by the identity-based model for mobile access control and data protection, as it has our special interest we’re following any developments very closely. We see this development as one of the best things offered in the industry to help you provide great mobile experiences to your employees and in the most future-proofed way.

In the meantime, if you’d like to know more on how you are able to use this functionality within your corporate environment, please contact us and let us know how we can assist you.