Since XenApp and XenDesktop 7.9 and StoreFront 3.6, it is possible to use SAML authentication with a number of external identity providers and integrate that with the Citrix Federated Authentication Service so that users can be authenticated from NetScaler through to StoreFront.
In this post, I will show you how you can use ADFS as an Identity Provider, passing authentication to StoreFront though the NetScaler with SAML authentication and FAS. This can help if two companies are merging together, but do not want to merge domains. It can also help if you have third-party companies accessing applications in your environment which may have required forest trusts to be formed between the required domains, slightly overkill in scenarios where only one application is accessed.
Authentication can be anything when using FAS. In my case, ADFS links to Active Directory so users log on using username (UPN) and password however in theory you could enter whatever you are asked for and be authenticated by NetScaler, issued a certificate and then authenticated to Active Directory with that corporate certificate. For example, you could be asked for a username and random one time code. No password is asked.
Moving forward, the SAML SP (Service Provider) is the NetScaler within your company, and the SAML IdP (Identity Provider) exists on the domain that want access to your applications and resources.
Since SAML won’t work directly with Active Directory, we set up authentication with FAS so that authentication can occur at the VDA using certificate based authentication. This is a requirement because Active Directory support either username/password or Smart Card auth.
♣ Prerequisites/Introduction
♣ Configure ADFS
♣ Configure NetScaler with SAML
♣ Configure StoreFront and the Citrix Federated Authentication Service
Prerequisites/Introduction
It is important to understand the flow when using SAML with NetScaler for authentication to StoreFront and VDAs:
- As a user logs on to NetScaler Gateway (the SAML Service Provider), NetScaler redirects the request to a SAML Identity Provider such as ADFS, Okta, Google or Ping Identity.
- User authenticates with the Identity Provider via Active Directory for example. A SAML token is signed and handed to the user.
- User passes token to NetScaler which in turn passes token to Active Directory in your environment. Active Directory trusts the Identity Provider and accepts the SAML token.
- The SAML token is used by NetScaler to look up the users identity and the assertion is sent to StoreFront.
- StoreFront contacts the Federated Authentication Service and askes for a certificate to be generated for the authenticated user.
- The Federated Authentication Service speaks with Active Directory Certificate Services, which issues a certificate for the authenticated user. At this stage the Federated Autentication service holds the user certificate and private key.
- When the authenticated user makes a connection to a VDA, the VDA has to authenticate the user so contacts FAS and redeems the certificate.
Note: This post assumes you have a working Active Directory Certificate Services installation running. Many articles on the internet contain guidance to deploying an internal PKI.
What else you need to use SAML with ADFS and FAS:
- XenApp/XenDesktop 7.9+ and StoreFront 3.6+.
- An ADFS server. (I am using ADFS 3.0 on Windows Server 2012 R2).
- A dedicted server (Citrix recommendation) for FAS. Recommended to have 1-2 FAS servers per StoreFront store that is using FAS.
- External FQDN for NetScaler Gateway URL and ADFS URL.
- A public certificate for the external NetScaler Gateway URL and ADFS URL.
- Three internally issued certificates for:
- Token-signing.
- Token-decryption.
- Signature verification.
- Note: Whilst ADFS generates self-signed Token-signing and decrypting certificates, I recommend using your own internally issued certs.
- SQL server (although possible to use Windows Internal Database, SQL is always recommended).
Configure ADFS
Before installing the ADFS role on Windows Server, draw up PowerShell and enter command Add-KdsRootKey -EffectiveTime ((get-date).addhours(-10)). This command immediately creates a Key Distribution Service Root Key, stored in Active Directory and allows us to create a group Managed Service Account password for the ADFS service account we create later. Run this command from a Domain Admin or Enterprise Admin account.
Now intall the ADFS role using Server Manager, then launch the Active Directory Federation Services Configuration Wizard -> Next. 
Specify a Domain Admin account to perform the ADFS configuration. Click Next. 
Import a public issued cerificate that matches the external ADFS URL. In my case, this is adfs.jgspiers.com. Set the Federation Service Name as your ADFS URL. The Federation Service Display Name will show to all users at log on. Click Next.
Note: The ADFS URL must be different from the ADFS server hostname. In my case, the ADFS server has a hostname of idp.jgspiers.com and an ADFS URL reachable via adfs.jgspiers.com.
Under Create a Group Managed Service Account enter a unique name. Managed Service Accounts are supported in Windows Server 2012 onwards and come with strict, complex passwords which are changed automatically every 30 days. Click Next.
Check Specify the location of a SQL Server database and enter your SQL server details. Click Next. 
Click Next after reviewing your options. 
Click Configure. 
Providing no errors occur, the ADFS server will be successfully configured. Click Close. 
Create an internal A Record for your ADFS URL. You also need to create an external A Record on your public DNS servers for the ADFS FQDN.
Next on the ADFS server, launch PowerShell and run command Set-ADFSProperties -AutoCertificateRollover $false. I am doing this because I do not want to use the ADFS generated Token-decrypting and Token-Signing certificates. Instead we will use our own generated through ADCS (Active Directory Certificate Services). In my case I have two certificates with subjects of:
- tokensigning.jgspiers.com
- tokendecrypting.jgspiers.com
Enrol the certificates, install them on the ADFS server and then launch the ADFS Management console. Browse to AD FS -> Service -> Certificates and delete the existing, autogenerated Token-decrypting and Token-signing certificates.
Use the Add Token-Signing Certificate and Add Token-Decrypting Certificate actions to add your own self-signed certificates as shown below. 
Token-decrypting certificate: 
Token-signing certificate. 
Within the ADFS Management Console, click each certificate and select the Set as Primary action.
On the ADFS server, launch MMC and add the Computer Certificates Snap-in. Navigate to the Personal store, right-click on the Signing certficiate and click All Tasks -> Manage Private Keys. 
Click Add. 
Click Object Types and check Service Accounts -> OK. Enter the name of the Managed Service Account you used during ADFS configuration. 
Specify Read permissions for the service account and click OK. Perform the same action on the Decrypting certificate. Afterwards, restart the Active Directory Federation Services service. 
Navigate back to the ADFS Management Console and browse to AD FS -> Trust Relationships -> Add Relying Party Trust. Using this wizard we create a trust relationship between ADFS and NetScaler.
Click Start. 
Check Enter data about the relying party manually and click Next.
Enter a descriptive display name and optional notes. Click Next. 
Check AD FS profile and click Next. 
Click Next. 
Check Enable support for the SAML 2.0 WebSSO protocol and enter the NetScaler external URL with /cgi/samlauth appended to the URL. Click Next.
Enter a unique identifier string for the Relying Party Trust. In this example, I’m simply using the NetScaler URL. This same identifier string will later be referenced in the NetScaler SAML policy so take note of it. Click Next. 
Click Next as we are not configuring MFA. 
Specify to Permit or Deny all users access to this relying party. I’m going to specify Deny then show you how to create Issuance Authorization Rules to restrict ADFS log ons to certan Active Directory group members for example. Click Next.
Click Next. 
Click Close. The Relying Party Trust will now be successfully created. 
The new Party Trust shows as below, highlight it, then click Edit Claim Rules. 
Click on the Issuance Authorization Rules tab. By default, no rules are created because I did not select Permit during the Relying Party creation wizard. When no rules are available, no users can authenticate with ADFS. Click Add Rule. 
Select the drop-down Permit or Deny Users Based on an Incoming Claim. Click Next.
Note: If you wanted all users to be able to authenticate through ADFS, simply choose drop-down option Permit All Users.
Specify a rule name and then under Incoming claim type select Group SID. Click Browse and search for a Domain Security Group. You can then Permit or Deny access to users that are a member of this group. In my example, only Domain Admins will be permitted access. Click Finish. 
The new rule appears. You can create multiple rules if required. 
Click on the Issuance Transform Rules -> Add Rule. 
Using the drop-down select Send LDAP Attributes as Claims. We want to send the users UPN as a claim in the signed token sent to NetScaler from ADFS. Click Next. 
Enter an appropriate Claim Rule Name. Under LDAP Attribute select User-Principal-Name. Under Outgoing Claim Type select Name ID. Click Finish. 
Click Add Rule again. 
Using the drop-down select Send Claims Using a Custom Rule. Click Next. 
Enter a name as below and copy the below text in to the Custom rule box:
=> issue(Type = “logoutURL”, Value = “https://adfs.jgspiers.com/adfs/ls/”, Properties[“http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/attributename”] = “urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified”);
Note: Replace adfs.jgspiers.com with your own ADFS URL.
Click Finish -> OK.
Highlight the NetScaler Relying Party Trust and click Properties. 
Click on the Signature tab and click add. Add a certificate (can be internally issued) for signature verification requests. NetScaler signs requests before sending them to the Identity Provider and therefore the IdP must trust such requests from NetScaler. The certificate you add here does not have a private key. The private key resides on the NetScaler, and is used for signing. So you will see later that the same certificate is imported to NetScaler along with the private key.
Click on the Endpoints tab. There should be a single entry under SAML Assertion Consumer Endpoints. Click Edit. 
Double check that the details are as below. Click OK. 
Next we can do some basic browser tests to make sure ADFS is responding properly before configuring NetScaler. Open a web browser and browse to https://youradfsURL.com/adfs/ls/idpinitiatedsignon. You should receive an HTML page as below.
Next navigate to https://youradfsURL.com/adfs/ld/federationserverservice.asmx and confirm you receive an XML response as below. If both tests look successful, we are ready to configure NetScaler SAML authentication.
Configure NetScaler with SAML
I’m using NetScaler Unified Gateway, so my SAML policies will be attached to an AAA vServer. If you are only using NetScaler Gateway without a Content Switch, the actions I take specifically around where I am creating and attaching SAML policies are different, but you should be able to understand the differences and adjust for your environment.
First you need to create a SAML Server. Navigate to Security -> AAA – Application Traffic -> Policies -> Authentication -> Basic Policies -> SAML -> Servers -> Add.
Specify an appropriate name. Under IDP Certificate Name, import the Token-signing certificate found on your ADFS server. Under Redirct URL and Single Logout URL specify the ADFS external URL with /adfs/ls/ appended to the end. Under User Field specify Name ID. Under Signing Certificate Name import the NetScaler signing certificate with private key. This is the same certificate you imported under the NetScaler Relying Party Trust properties within the Signature tab. This certificate will sign authentication requests that are sent to your IdP. The Issuer Name must be the same unique identifier name you specified during the creation of the NetScaler Relying Party Trust. Click on More.
Check the radio boxes for RSA-SHA256 and SHA256. Finish creation of the SAML server.
Navigate to Security -> AAA – Application Traffic -> Policies -> Authentication -> Advanced Policies -> Authentication Policies -> Add. 
Enter a name. Under Action Type choose SAML. Under Action choose the SAML server you just created. Under Expression type true. Click Create. 
Now bind the SAML policy to your AAA vServer, as below. 
At this stage when you browse to the NetScaler Unified Gateway URL, you should be redirected to ADFS for authentication. Authenticate using your UPN credentials. Click Sign in.
If successful you’ll be directed to Unified Gateway. StoreFront passthrough will not yet work, which brings us to the final step.
Configure StoreFront and the Citrix Federated Authentication Service
To begin, as a Citrix recommended practice, deploy a dedicated server to host the Federated Authentication Service. The server must be running Windows 2008 R2 or later. This service automatically on behalf of users enrols for certificates against Active Directory Certificate Services, so it is important that this server is secured.
To insall FAS, launch the XenApp/XenDesktop 7.9+ media and click on Federated Authentication Service.
Accept the License Agreement and click Next. 
Click Next. 
Click Next. Port 80 TCP will be used. 
Click Install. 
Once FAS has installed, log on to your StoreFront server and launch PowerShell. You are going to enable FAS on the Store of your choice. Run the following commands and propagate to remaining servers if applicable:
- Get-Module “Citrix.StoreFront.*” -ListAvailable | Import-Module
- $StoreVirtualPath = “/Citrix/Citrix” (Note: Change /Citrix/Citrix to your own store path)
- $Store = Get-STFStoreService -VirtualPath $StoreVirtualPath
- $Auth = Get-STFAuthenticationService -StoreService $Store
- Set-STFClaimsFactoryName -AuthenticationService $Auth -ClaimsFactoryName “FASClaimsFactory”
- Set-STFStoreLaunchOptions -StoreService $Store -VdaLogonDataProvider “FASLogonDataProvider”
![]()
On a Delivery Controller, run commands asnp citrix.* and Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true
Next we need to use Group Policy to specify which servers are used for FAS. On the FAS server, navigate and copy all files and folders from C:\Program Files\Citrix\Federated Authentication Service\PolicyDefinitions. 
Copy them to the PolicyDefinitions folder within SYSVOL aka your Group Policy Central Store.
Now create a Group Policy Object which points to your FAS, StoreFront and VDA servers. You could link the policy to a high level OU or at the domain level if you don’t want to be more granular. Expand Computer Configuraton -> Policies -> Administrative Templates -> Citrix Components -> Authentication and double-click Federated Authentication Service.
Check the Enabled radio box. Click Show beside DNS Addresses and enter your FAS server hostname. Click OK. 
You can also enable the ability for in-session certificates by configuring the In-session Certificates setting. By default, VDAs will not allow access to FAS issued certificates after a user logs on, however this setting does allow the use of certificates and places a certificate in the users personal certificate store after logon. This is useful when you have applications or web applications that require client certificate authentication or you need to sign documents using a digital certificate.
You can specify that prompts for consent to use the certificate in-session can appear on-screen per-application, once for a session or not at all. You can also configure how long a consent lasts for before asking again.
Note: Make sure to also check Available after logon within the FAS administration console under User Rules or else users will be denied access to their certificates when they log on to a VDA. 
Log on to your FAS server and launch the Citrix Federated Authentication Service console. You may have to run a gpupdate before the FAS address appears as below. Click Ok. 
On the Initial Setup page, click Start next to Deploy certificate templates. 
Click OK. As mentioned in the note, FAS will attempt to install three certificate templates on to your ADCS server. This may require that the account you are running the FAS tool with is a Domain or Enterprise Admin. These steps can also be performed manually if needed using PowerShell.
The first section will turn green once the templates have been installed. The second step may also turn green without any additional input. If it dooesn’t, click Start under step 2 and select your Certificate Authority. Do not proceed to step 3 just yet. 
On your Certificate Services server, the three certificate templates show as below. 
Open the Certificate Authority console and navigate to Certificate Templates, right-click and select New -> Certificate Template to Issue. 
Highlight the three Citrix FAS related templates and click OK.
Note: You can choose to optionally deploy either the Citrix_RegistrationAuthority or Citrix_RegistrationAuthority_ManualAuthorization templates. The first template is for auto-enrolment and the second requires certificate requests using that template to be manually issued. If you are using the Citrix_RegistrationAuthority template, you should restrict the permissions so that only the FAS server can auto-enrol this certificate. 
Now return to the FAS server. Click on Start beside step 3, Authorize this service. What this is going to do is submit a certificate request to ADCS based on the Citrix_RegistrationAuthority_ManualAuthorization or Citrix_RegistrationAuthority certificate templates. The first requests manual approval, whilst the second is configured for auto-enrolment. 
Click OK. The request will be sent to the selected Certificate Authority server, but you can specify another. 
If you are manually approving using the Manual Authorization template, the FAS console will wait for approval. At this stage you need to manually issue the certificate request. 
Open up the Certificate Authority console, navigate to Pending Requests. Right-click on the existing pending request and click Issue under All Tasks. 
Once the certificate has been successfully issued, step 3 will turn green. The Initial Setup is complete. FAS now has the ability to issue certificates to users. 
Click on the User Rules tab. A default rule has aleady been created. You can customise this rule, or create your own additional rules. Rules dictate which StoreFront servers can request certificates from FAS, which users certificates can be requested for and which VDAs can consume those certificates. Rules can be applied to different StoreFront servers using Group Policy. For now I will stick with the single default rule and make some modifications. Make sure Certificate Authority matches your CA (you can add multiple CA servers using PowerShell) and the Certificate Template is set to Citrix_SmartcardLogon. Click Edit beside List of Storefront servers that can use this rule.
Ensure only your StoreFront servers have the Assert Identity permission. No other server should be included in the list. Click OK. Click Edit beside List of VDA desktops and servers that can be logged into by this rule. 
By default Domain Computers have Relying Party Allow rights. You can change this to specify that only certain VDA machines can be logged on to using FAS. Click OK. Click Edit beside List of users that StoreFront can log in using this rule.
By default, Domain Users can log on using FAS. Again, you can change this. Click OK. 
Once you are satisfied with all rules, click Apply and then OK. 
It is strongly recommended that you restrict the FAS server to only being allowed to issue certificates using the single Citrix_SmartCardLogon template and to certain users. Excluding administrators is a good example of users who should not be issued a certificate under FAS. You can configure restrictions within the Certificate Authority console.
Next we need to perform some configurations on StoreFront. Launch the StoreFront console and click on the store that users will log on to. Now click Manage Authentication Methods. It is assumed you already have a NetScaler configured against the store.
Click the cog drop-down next to Pass-through from NetScaler Gateway and select Configure Delegated Authentication.
Check Fully delegate credential validation to NetScaler Gateway -> OK. Propagate the change to any remaining StoreFront servers. 
You are now ready to test logging on to NetScaler and connecting to a VDA through StoreFront.
Once the user authenticates with ADFS, StoreFront issues an identity assertion to FAS for user george.spiers@jgspiers.com. 
FAS then begins the issuing of a certificate to user george.spiers@jgspiers.com.
A certificate request is made to the Certificate Authority. 
If the request is granted, FAS issues a certificate to george.spiers@jgspiers.com. 
The request details are logged. 
FAS keeps hold of the certificate and private key. The private key is not shared with StoreFront.
As a user connects to a VDA, the VDA reports that an Identity Assertion Logon is occuring along with details of the user logging on. 
The certificate request can be seen from the Certificate Authority console.
If you double-click on the request, you can see the certificate which expires in 7 days. 
You can also view issued certificates that are cached on the FAS server. Launch PowerShell and issue command Add-PSSnapin Citrix.Authentication.FederationAuthenticationService.V1 and Get-FASUserCertificate -Address IDP.jgspiers.com with address being your FAS server name. These certficates will be cached by default for 7 days.
If in-session certificates are enabled, StoreFront again issues an assertion to FAS. 
A record is then generated to say that VDA1 is accessing the issued certificate for user george.spiers@jgspiers.com. 
You can remove FAS issued certificates for specific users using a command such as Remove-FASUserCertificate -Address IDP.jgspiers.com -UserPrincipalName george.spiers@jgspiers.com from PowerShell on your FAS server. If you run the same command without the -UserPricipalName switch, all issued certificates will be removed from the specified FAS server.
You can also pre-generate certificates using New-FASUserCertificate. This could help in situations where you want to pre-generate certificates during non-peak hours to reduce load on FAS and ADCS servers.
A number of performance counters come installed on the FAS server after you have installed the FAS role. These are helpful in determining how many certificates FAS has currently enrolled, how quick certificates are generated, signed and so on. Certificate generation normally takes around 1 second, the certificate is then cached for 7 days to make logons faster however assertions will still be made to FAS from StoreFront and the VDA when users are re-authenticating within the 7 days.