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:

saml2

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

Onward!

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.

StoreFront

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

GPO

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:

HKEY_LOCAL_MACHINE/SOFTWARE/Policies/Citrix/Authentication/UserCredentialService/Addresses

Verify if the FQDN of your UCS server is listed

UCS

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:

UCS3

  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.

UCS7

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.

UCS8

Firewall

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:

NSG_ADFS_UCS_VDA

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">
 <md:Extensions>
 <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"/>
 </md:Extensions>
 <md:KeyDescriptor>
 <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
 <ds:KeyName><nsg_fqdn></ds:KeyName>
 <ds:X509Data>
 <ds:X509SubjectName>CN=<nsg_fqdn></ds:X509SubjectName>
 <ds:X509Certificate>
 <NSG Cert in pem format, public key only>
 </ds:X509Certificate>
 </ds:X509Data>
 </ds:KeyInfo>
 </md:KeyDescriptor>
 <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<nsg_fqdn>/cgi/samlauth" index="0"/>
 </md:SPSSODescriptor>
</md:EntityDescriptor>

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.

https://<nsg_fqdn>/vpn/metadata.xml

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

ADFS1

Remove the Encryption certificate on the Encryption tab

ADFS2

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

ADFS3

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

Claims

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 == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
 => issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"), query = ";userPrincipalName;{0}", param = c.Value);

Send Claim using a custom rule (Send LogoutURL)

 => issue(Type = "logoutURL", Value = "https://<adfs_fqdn>/adfs/ls/", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/attributename"] = "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”.

SF1

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

SF2

 

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:

 

Troubleshooting

StoreFront

StoreFront troubleshooting is described here: https://docs.citrix.com/en-us/storefront/3/sf-troubleshoot.html

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"/>

Netscaler

http://support.citrix.com/article/CTX114999

Federated Authentication Service Blog

http://discussions.citrix.com/forum/1642-saml-federated-authentication-tech-preview/

 

Azure AD as an Identity Provider

Let’s take a quick look at Azure Active Directory (AAD) in the identity provider role. Anyone using Office 365 , be it logging on with a standard account or a federated one, utilizes an Azure AD identity, with the latter brokering access to Office 365 resources.

What happens when we wish to connect our own SaaS/web applications to  the Azure AD world? Well, Windows Azure brokers a number of identity-based technologies to support such requirements. As a means of illustrating this, we’ll show an example using Azure AD as a SAML 2.0 Identity Provider (IdP), connecting up to a basic web application using a pHP-based SAML Service Provider: simpleSAMLphp.

We login to our Azure tenant (Azure Service Manager). Scroll down to the Active Directory icon.

2016-04-27_11-34-58

On the directory tab, click on the organization and then the Applications tab.  From the bottom of the screen, create a new application by clicking on the Add icon.

2016-04-27_11-35-18

Select Add an application my organization is developing.

2016-04-27_11-35-32

Give your SaaS/Web application a name (e.g. simpleSAMLphp Demo).  Using the radio button, select the type of application. Since this is a SAML-P application using the browser, we need to select the Web Application / Web API  option.

2016-04-27_11-35-43

Click on the arrow. Enter the details for your SAML application.

2016-04-27_11-35-54

For Sign-On URL fill in the Assertion Consumer Service (ACS) URL for the Service Provider (simpleSAMLphp). We’ll revisit these settings in a  moment. For the App-ID URI, the Identifier or Entity ID of the SAML Service Provider is expected.

Here’s an example using our  simpleSAMLphp application.

2016-04-27_11-36-12

Here we’ve gone back and changed the Sign-On URL to the base URL of the SimpleSAMLphp admin page. This is where (for the test) we want to send users to when accessing the “application”. It’s the Reply URL which is the address to which Azure AD will send the SAML authentication response. Further down in the application configuration in Azure Manager, we see the Single Sign-On settings.

2016-04-27_11-36-26

Here are the actual settings used, albeit with a dummy URLs.

Sign-On URL

https://saml.mydomain.com/login

Reply URL

https://saml.mydomain.com/login/module.php/saml/sp/saml2-acs.php/default-sp

App URI (Identifier)

https://saml.mydomain.com/login/module.php/saml/sp/metadata.php/default-sp

On the Service Provider side, the metadata from the tenant) Azure Identity Provider needs to be parsed and added to the SimpleSAMLphp configuration file (saml20-idp-remote.php). This is done by downloading the Azure IdP metadata file directly, e.g.

https://login.microsoftonline.com/<AzureTenantID/federationmetadata/2007-06/federationmetadata.xml

Connect to the simpleSAMLphp web administration interface. From the federation tab, select the XML to simpleSAMLphp metadata converter.

2016-04-27_11-36-41

Cut and paste the Azure XML document from the tenant into the simpleSAMLphp web browser, convert the text and then copy to the clipboard. This text can be then appended directly to the saml20-idp-remote.php file.

Here’s an example. Replace the Azure Tenant ID with your own ID accordingly.

$metadata['https://sts.windows.net/<Azure Tenant ID>/'] = array (
  'entityid' => 'https://sts.windows.net/<Azure Tenant ID>/',
  'contacts' =>
  array (
  ),
  'metadata-set' => 'saml20-idp-remote',
  'SingleSignOnService' =>
  array (
    0 =>
    array (
      'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
      'Location' => 'https://login.microsoftonline.com/<Azure Tenant ID>/saml2',
    ),
    1 =>
    array (
      'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
      'Location' => 'https://login.microsoftonline.com/<AzureTenantID>/saml2',
    ),
  ),
  'SingleLogoutService' =>
  array (
    0 =>
    array (
      'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
      'Location' => 'https://login.microsoftonline.com/<Azure Tenant ID>/saml2',
    ),
  ),
  'ArtifactResolutionService' =>
  array (
  ),
  'keys' =>
  array (
    0 =>
    array (
      'encryption' => false,
      'signing' => true,
      'type' => 'X509Certificate',
      'X509Certificate' => '<CERTIFICATE>',
    ),
  ),
);

Testing Authentication

From the Azure Application Portal, we can access the new test application.

2016-04-27_11-36-57

From them we’re taken to the simpleSAMLphp administration page (https://saml.mydomain.com/login)

Within simpleSAMLphp we can select our identity provider for logon (Azure AD)

2016-04-27_11-37-08

Click on the Select button to initiate the logon process.

2016-04-27_11-37-17

Logon with your Azure AD credentials to the application and we’re returned to the simpleSAMLphp landing page.

2016-04-27_11-37-33

Since Azure is brokering the connection with the application, this process also extends to using ADFS where the domain is federated. Azure performs the necessary realm discovery and routes the  user to their home domain.

With these and a number of services, Azure offers a solid convergence point for brokering connections with your web applications and workspaces. It’s a rapidly evolving space, so stay tuned…

If you’d like to know more or on how you can implement this and related technologies within your own  environment, please contact us. We’ll be happy to assist.