Since Citrix XenApp / XenDesktop 7.9 the Federated Authentication Service (FAS) is available. Via Citrix FAS it is possible to authenticate a user via SAML and thus connect Citrix as a service provider to existing identity providers, such as Azure-AD.
Sequence of SAML authentication
- The user browse the FQDN (e.g. citrix.deyda.net) of the Citrix Gateway vServer (Service Provider) to start his VA / VD resources
- The Citrix Gateway vServer directs the unauthenticated user directly to the Identity Provider (Azure-AD) to authenticate itself (saml: authnRequest)
- The Identity Provider points to its SingleSignOnService URL (e.g. login.microsoftonline.com) and the user must authenticate
- The user enters his AD credentials and these are checked by the Identity Provider against the user database
- Upon successful verification in the user database, the IdP is informed
- The IdP issues a token (SAML assertion) and sends it to the Citrix Gateway (saml: response)
- Citrix Gateway checks the token (assertion signature) and extracts the UPN from the assertion token. This allows access via SSO to the VA / VD farm via FAS (The SP does not have access to the user’s credentials)
Setup SAML Authentication
In my guide, I’m assuming SAML authentication between Azure-AD and the Citrix ADC (formerly NetScaler) Version > 12. Of course, the SAML authentication would also work with an ADFS environment.
I assume the following things and do not go into detail about them:
- Fully working Citrix Virtual Apps and Desktop Environment (Minimum Version 7.9)
- Citrix ADC with successful base configuration and activated Enterprise or Platinum license
- Internal and external DNS entries for Unified Gateway vServer (e.g. citrix.deyda.net)
- Certificates for DNS entries (wildcard certificates are the easiest)
- Configured Unified Gateway vServer
- Existing Azure Tenant with Azure-AD base configuration (domain, AAD Sync) & activated Azure AD Premium license
If you do not use the same UPN in Azure AD and in the local Active Directory, you still have to adjust it.
To do this, open the Active Directory Domains and Trusts tool.
In the tool, right-click on the top item (Active Directory Domains and Trusts) and select Properties.
In the following window enter the desired domain (e.g. deyda.net) under Alternative UPN Suffixes and confirm the entry via Add.
Check that the domain name has been inserted correctly and confirm with OK.
Now you can bulk edit or manually adjust the UPN of the required users to the Azure-AD domain.
Next, a PKI environment must be created, if there is none in the domain. Go for this on the machine that should receive this role. In my example, it is the domain controller itself.
For this we go to the Server Manager and click Add Roles and Features.
Click through the wizard to the point Server Roles and select the item Active Directory Certificate Services. Confirms the selection with Add Features.
Then click Next in the Server Roles, Features and AD CS tab.
Under the heading Role Services you select the following points:
- Certification Authority
- Certification Authority Web Enrollment
If pop-up windows with additional features appear, you also confirm these with Add Features.
Complete the installation with Install.
Now select the Notifications item in Server Manager and click on Configure Active Directory Certificate Services.
In the following configuration, the default settings can be confirmed with Next.
Configuration used by me:
- Setup Type (Enterprise CA)
- CA Type (Root CA)
- Private Key (Create a new private key)
- CA Name (Deyda-CA)
- Validity Period (5 Years)
Confirm the configuration with Configure.
Now the domain controller must be issued a certificate of the local CA.
To do this, open the MMC on the domain controller.
Click on File and Add / Remove Snap-in …
Now click on Certificates and on Add.
In the following window select Computer account and confirm it with Next.
Finally, close the window with OK.
Right-click on Personal and then on All Tasks > Request New Certificate…
In the Certificate Enrollment window, select your Active Directory Enrollment Policy and click Next.
Select Domain Controller Authentication and confirms this with Enroll.
Citrix Federated Authentication Service
Now we can install and configure the FAS server. In my example, I install the FAS Part on the StoreFront server.
For this mount the ISO of your Virtual Apps & Desktops version and start autoselect.exe.
Then start the installation by clicking on Federated Authentication Service in the following window.
Click on “I have read, understand, and … ” and confirm it with Next.
Now confirm the following default settings with Next.
And click Next again.
Starts the installation with Finish.
You may have to restart your server.
To perform the basic configuration of the FAS through the GPO, copy the ADMX / ADML files from the specified path of your FAS server.
C:\Program Files\Citrix\Federated Authentication Service\PolicyDefinitions
Add them to the PolicyDefinitions Store of your Active Directory.
Create a new one or edit an existing GPO, which will be activated on the following systems:
- FAS Server
- StoreFront Server
- VDA Worker
In the GPO go to the path:
Computer Configuration \ Policies \ Administrative Templates \ Citrix Components \ Authentication
Enter your FAS server in Federated Authentication Service.
Update your local GPOs on the FAS server by running gpupdate /force in the CMD.
Then check the registry that the required entry has been written to the system:
HKEY_LOCAL_MACHINE \ SOFTWARE \ Policies \ Citrix \ Authentication \ UserCredentialService \ Addresses Or / And HKEY_LOCAL_MACHINE \ SOFTWARE \ WOW6432Node \ Policies \ Citrix \ Authentication \ UserCredentialService \ Addresses
Now start the Citrix Federated Authentication Service Tool with the “run as administrator” parameter
Here you can see, the list of FAS servers that have been configured via GPO. Click on OK.
The following window configures the FAS.
Click on Start in the frame 1 Deploy certificate templates.
Click on OK, so that the configuration is carried out automatically, in the background.
After successful setup, the frame 1 appears in green.
Then click on Start in the context of 2 Setup Certificate Authority.
Under Certificate Authority, select your CA configured / created for FAS (e.g. DC01.deyda.local\CA-DEYDA) and click OK.
Upon successful setup, the frame 2 also appears in green.
Now click on Start at 3 Authorize this service.
Here select your CA and click OK.
Point 3 now appears in yellow, because the certificate request must be approved.
Reconnect to the server with the FAS CA and open the Server Manager. In Server Manager, click Tools > Certification Authority.
In the Certification Authority console, click on Pending Requests.
There you right click on the request of your FAS server (e.g. DEYDA \ CTX01) and click on All Tasks > Issue.
Thereafter, the certificate appears under Issued Certificates.
The now approved certificate normally expires in 2 years.
Therefore, it is recommended to include this certificate in the monitoring so that you renew the certificate before it expires.
Here are the PowerShell commands to get the expire date (Replace CTX01.deyda.local with your FAS server).
Add-PsSnapin Citrix.Authentication.FederatedAuthenticationService.V1 Get-FasAuthorizationCertificate -FullCertInfo -address CTX01.deyda.local
After approving, all the points in the FAS Configuration Console appear in green.
In the latest versions of the Virtual Apps & Desktops Image, installing the FAS Server also installs the Citrix FAS Administration BETA Console. All activities relating to configuration can also be carried out herewith. I have already checked this and could not find any errors.
Now click on the User Rules Tab in the FAS Configuration Console and select the following in the upper area:
- Rule name (default)
- Certificate Authority (Your FAS CA, e.g. DC01.deyda.local\CA-DEYDA)
- Certificate Template (Citrix_SmartcardLogon)
At the bottom of Security Access Control Lists, click Edit next to List of Storefront servers that can use this rule.
In the following window you delete the default group Domain Computers.
Then add your StoreFront servers and give them the Assert Identity (Allow) right. Confirm this with OK.
Under List of VDA desktops and servers that can be logged into this rule you can narrow down the list of Citrix Workers to which you can log in via SAML. By default this stands on Domain Computers, which can stay that way.
In the last point, you can restrict the users who can log in to Citrix via SAML. By default, the group Domain Users is stored here, which can stay that way.
After everything is defined click on Apply and close the FAS console.
Now we configure the StoreFront server so that it can talk to the FAS server.
Go to your Citrix StoreFront console and make a note of your stores you want to configure for FAS (e.g. Store).
Starts PowerShell as administrator on a StoreFront server.
Execute the following commands in PowerShell (change the store path in line 2 to your store name):
Get-Module "Citrix.StoreFront.*" -ListAvailable | Import-Module $StoreVirtualPath = "/Citrix/Store" $store = Get-STFStoreService -VirtualPath $StoreVirtualPath $auth = Get-STFAuthenticationService -StoreService $store Set-STFClaimsFactoryNames -AuthenticationService $auth -ClaimsFactoryName "FASClaimsFactory" Set-STFStoreLaunchOptions -StoreService $store -VdaLogonDataProvider "FASLogonDataProvider"
If you want to deactivate this again, e.g. for troubleshooting, you can do this with the following command:
Get-Module "Citrix.StoreFront.*" -ListAvailable | Import-Module $StoreVirtualPath = "/Citrix/Store" $store = Get-STFStoreService -VirtualPath $StoreVirtualPath $auth = Get-STFAuthenticationService -StoreService $store Set-STFClaimsFactoryNames -AuthenticationService $auth -ClaimsFactoryName "standardClaimsFactory" Set-STFStoreLaunchOptions -StoreService $store -VdaLogonDataProvider ""
Now open the Citrix StoreFront console again and click on Manage Authentication Methods in the panel on the right side.
Enable Pass-through from Citrix Gateway if it is not enabled.
Then click on the gear on Pass-through from Citrix Gateway and on Configure Delegated Authentication.
In the following window, check the box next to Fully delegate credential validation to Citrix Gateway and click OK two times to close the windows.
Click, back in the main window of the StoreFront console, on Manage Citrix Gateways.
In Manage Citrix Gateways, you add a new gateway or edit an existing one to connect to your Citrix Gateway which will later be used as SP.
In my case, I edited an existing Gaeway via Edit and configured the following under Authentication Settings:
- Version (10.0 (Build69.4) or later)
- VServer IP address (IP address of the Gateway VIP, e.g. 10.0.0.8)
- Logon type (Domain)
- Callback URL (Address of the Callback, e.g. https://citrix.deyda.net)
Confirm the settings with Finish.
Important here is that also in the internal DNS the callback address citrix.deyda.net is deposited.
In the main menu of the StoreFront console, click on Configure Remote Access Settings and check that the item … (No VPN tunnel) is activated.
The XML Trust must still be activated on the Delivery Controller if this is not already activated.
To do this you start a PowerShell as administrator on a Delivery Controller.
Now run the following command.
asnp citrix.* Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true
To connect our upcoming Service Provider, we now need to create a custom application in the Azure-AD.
To configure the Azure-AD, log in to portal.azure.com.
In the Azure Navigation Panel, we click on Azure Active Directory.
In the Azure Active Directory window, click on Enterprise Applications.
Now click New Application.
And then on Non-gallery application.
In the Add my application window configure the name of the application for the end user, e.g. Citrix FAS and click Add.
Wait for the application to be created. Information is obtained via the Notifications item at the top.
Once the application has been created, click on Azure Active Directory > Enterprise Applications > All Applications and then on the application just created (e.g. Citrix FAS)
In the enterprise application click on Single sign-on.
Under SSO method click on SAML.
The following window configure the communication between the Identity Provider and Service Provider.
Click on the pencil icon in the upper area with the number 1 to edit the Basic SAML Configuration.
Enter here the following:
- Identifier (Citrix Gateway Address, e.g. https://citrix.deyda.net)
- Reply URL (Citrix Gateway Address with /cgi/samlauth, e.g. https://citrix.deyda.net/cgi/samlauth)
Confirm your input with Save.
The settings under point 2 User attributes and claims can remain in the existing standard.
Under SAML Signing Certificate (Item 3), download the Certificate (Base 64) for the Service Provider (Citrix ADC).
From area 4 (Set up Citrix FAS), copy the displayed URLs (Login URL, Azure AD Identifier & Logout URL) to a local file.
Click on the confirmation checkbox at the bottom and click Next.
To allow users to use SAML authentication for Citrix, they must be assigned to the application.
Click on Users and groups.
Now click on Add user.
Now select from the list the users who should be granted access (or select all users) and confirm this with Assign.
I only authorized one test user (user01) for this.
Finally, the Citrix ADC must be configured to communicate with the Identity Provider (Azure-AD).
To do this, we log in to the Admin web interface of the Citrix ADC and navigate to Traffic Management > SSL > Certificates > Server Certificates.
There, click Install to import the previously downloaded certificate from Azure Portal.
Enter the following and confirm the entry with Install:
- Certificate-Key Pair Name (Unique name for the SAML signature certificate, e.g. SAML-Azure-AD)
- Certificate File Name (Downloaded signature certificate, e.g. Citrix FAS.cer)
The installed certificate can not be found under Server or Client Certificates, but under Unknown Certificates.
Then we navigate to Security > AAA – Application Traffic > Virtual Servers to create the SAML Authentication Policy and Authentication vServer.
Under Authentication Virtual Servers, click Add to create a new vServer.
Now enter the following:
- Name (Name of the vServer, e.g. Azure-AD_auth_VS
- IP Address Type (Non Addressable)
Click on OK.
In the following wizard click on No Server Certificate to connect your server certificate (not the IdP certificate).
Click in the Click to select area.
Select your Citrix ADC Server certificate (my wildcard certificate, for example) and click Select.
Click on Bind.
If the certificate is attached (1 Server Certificate) click Continue.
Under the menu item Advanced Authentication Policies click on No Authentication Policy.
Click on the + symbol under Select Policy.
Enter the following:
- Name (Name of the Authentication Policy, e.g. saml_auth_pol)
- Action Type (SAML)
- Expression (HTTP.REQ.IS_VALID)
Click on the + symbol next to Action.
Now configure the Authentication SAML Server with the following parameters:
- Name (Name of the SAML Authentication Server, e.g. saml_auth_server)
- IDP Certificate Name (Certificate from the Azure-AD Application, e.g. SAML-Azure-AD)
- Redirect URL (URL for logging in from the Azure AD application, e.g. https://login.microsoftonline.com/…/saml2)
- Single Logout URL (URL for logging in from the Azure AD application, e.g. https://login.microsoftonline.com/…/saml2)
- Signing Certificate Name (Server Certificate of the Citrix Gateway, e.g. Wildcard201904)
- Issuer Name (FQDN of the Citrix Gateway vServer, e.g. https://citrix.deyda.net)
Confirm the entry with Create.
Check the entries again and click Create.
Under Policy Binding controls the inputs and changes the following:
- Goto Expression (END)
Confirm this with Bind.
If the Authentication Policy is connected click on Continue and Done.
In order to complete the configuration on the Citrix ADC, we only need to bind the newly created SAML Authentication Policy to our Gateway Virtual Server.
To do this, we navigate to NetScaler Gateway > Virtual Servers.
Select the gateway vServer previously configured for FAS in StoreFront (e.g. https://citrix.deyda.net = UG_VPN_ug_10.0.0.8_443) and click Edit.
Resolves all connected LDAP or RADIUS authentication policy from the vServer. Click on the policies (1 LDAP Policy).
Select the policies and click Unbind.
Confirm the window with Yes.
Checks that neither a policy is connected in Basic Authentication nor in Advanced Authentication.
On the right side, click Authentication Profile under Advanced Settings.
Click on the + symbol under Authentication Profile.
Enter a name (e.g. saml_auth_profile) under Create Authentication Profile and click on Click to select under Authentication Virtual Server.
Select the previously created Authentication Virtual Server (Azure-AD_auth_VS) and click Select.
Confirm the entry by clicking on Create.
Click on OK and on Done.
Navigate to NetScaler Gateway > Global Settings to delete the single sign-on domain.
Click on Change Global Settings.
Deletes the possible entry under Single Sign-on Domain.
If necessary, the policies of the Gateway vServer must also be adjusted for Single Sign-on Domain.
If we now open the FQDN of the gateway (https://citrix.deyda.net) via browser.
We will be forwarded directly to Azure-AD and can authenticate ourselves there.
We get our Citrix resources listed and can start them.