For one of my customers I needed to set-up a Citrix FAS environment for using SAML authentication to achieve a single username and password (and providing this information once). To verify that the goals would be reached I first set-up Citrix FAS into my own (demo)environment, followed by a production environment on the customer infrastructure. I did this based on instructions created by fellows in the Citrix community and logically the Citrix documentation. In this article I’m not going to create another configuration article as those are already available. I will point you to these articles and share in this article tips and tricks of occasions I encountered. Most are already available somewhere on the Internet, but it is scattered and not always issue to found.
What is the scenario?
First step is why Citrix FAS is required in your set-up. In other words, how those your scenario looks like. Actually I think the set-up of Citrix FAS it selves is probably the easiest part as the actual usage to get to Citrix FAS is the complicated part. On the Citrix FAS documentation page some scenarios are mentioned (https://docs.citrix.com/en-us/xenapp-and-xendesktop/7-15-ltsr/secure/federated-authentication-service/fas-architectures.html), but several other scenarios are possible as well. In my case we would like to make the access to two not-connected Citrix environment for our end-users as easy as possible (more on this in later article). If you know your scenario just Google and see if there is more information available out of the Citrix Community. For the installation and configuration of Citrix FAS check the article Carl Stalhood - Citrix Federated Authentication Service. Do the steps till the part that mentions NetScaler Gateway configuration. From that point the installation and configuration differ based on the next topic.
What will be your IdP?
When using SAML authentication an IdP (Identity Provider) is required. On this IdP the actual authentication will take place. There are a lot of IdP available like Azure AD, MS ADFS, Ping, oAuth, NetScaler and many more. When you now which IdP you want/need to use it is best to google for the combination of the IdP in combination with Citrix FAS/NetScaler SAML. As each set-up differs and you really need to find out which information needs to be filled in at which spot. Also things can change during time, for example the Azure Portal is redesigned some time ago, so it can happen that the articles you will find are not completely up to date and you need to adjust some steps.
Definity not a full list, but I have collected a couple of articles describing the steps for probably the most used IdPs. A tip read them really carefully and also check al print screens, sometimes not all settings are mentioned in the text (but are visible in the images).
ADFS Authentication to StoreFront using NetScaler, SAML and Citrix FAS - George Spiers
Citrix FAS: Azure AD as Identity Provider - Rene Bigler
Configure NetScaler Gateway SAML to Google with Citrix FAS – JS Consulting Services
Okta Citrix NetScaler Gateway SAML Configuration Guide - Oktba
Domain Controllers need to have Domain Controllers certificate
When using FAS you need to have a Certificate Authority in Enterprise mode. When the CA is installed on a different machines than your domain controller(s), which is logical is production environments your Domain Controllers need to have Domain Controllers certificates available. See CTX218941 for the details how to arrange this.
SAML iDP need to match the userPrincipleName (UPN) in Active Directory
For Citrix FAS to determine the actual AD which should be “mapped” to the SAML iDP the userPrincipleName (UPN) needs to be the same as the SAML iDP.
To accomplish that it can be required that the UPN suffix need to be added to your Active Directory. This is done via Active Directory Domain and Trusts MMC. Select there the Active Directory Domain and Trust node (all up) and choose Properties out of the right mouse button menu. This opens the UPN Suffixes part and you can add the required suffix.
After this configuration change the UPN is available within Active Directory and Computers for the so-called shadow accounts. Create the accounts that the user logon name matches the SAML iDP. The Pre-Windows 2000 logon can differ. The actual password set to the account does not matter, but don’t forget to remove the Change Password at Next Logon checkbox.
SAML Authentication not available in XenApp and XenDesktop wizard
When you are configuring the Gateway service with the XenApp an XenDesktop wizard you won’t have the SAML authentication available. It is only possible to add/change the authentication to SAML within the NetScaler Gateway – Virtual Server part of the GUI.
Remove the Single Sign-on Domain configuration with the NetScaler Gateway Session Profile
Especially when you have set-up the Gateway earlier this one can cause that the authentication will fail at the end. Please check within your Session Profile for the Gateway you are configuring for SAML that the Single Sign-On Domain is NOT filled it. If filled remove the configuration.
Don’t configure Trusted Domains within StoreFront
Last but not least do not configure Trusted Domains within your StoreFront Authentication methods for the Store in use. When configured the last step (actually starting the Published Application or Desktop) will fail. If user can both use their normal AD account as SAML create for each solution a different store with a different set-up.
Apply the FAS GPO also to the StoreFront server(s)
In all documentation/articles on the Internet it is mentioned that the FAS policy need be assigned to the FAS server(s) and the VDAs. However in my environment this was not the case. I got an error 28 on the StoreFront server about an unknown error interacting with the Federated Authentication Service.
When I assigned the GPO to the StoreFront server as well the issue was gone. I found somebody on the Internet claiming that the policy also needs to be assigned to the Delivery Controller, but I did not do that and it was working.
BUG in Citrix ADC 12.1
Within my first testings the creation of the SAML Authentication server went fine. But building up the official test environment at the customer an error was shown Arguments cannot both be specified [samlIdPCertName, metadataUrl], which is kind of strange as I uncheck the import metadata option. I upgrade my own Citrix ADC (also known as NetScaler) and tried to create a new SAML authentication as well. The ended with the same error message. It looks like a bug as it worked earlier. For now you need to use the CLI command (add authentication samlAction <NAME> -samlIdPCertName <ipd certificate> -samlSigningCertName <sp certificate> -samlRedirectUrl "https://<adfs_fqdn >/adfs/ls/" -samlUserField "Name ID" -samlIssuerName <issuername/relaying party identifier>). After that you can adjust settings via the GUI again.
Summarization
In this article I shared some tips and tricks for configuring Citrix FAS in combination with NetScaler as a SAML SP. If you have any addition good tips or tricks, please let me know so I can add them to the article.