SAML Authentication with Azure AD as IdP and Citrix as SP

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

  1. The user browse the FQDN (e.g. citrix.deyda.net) of the Citrix Gateway vServer (Service Provider) to start his VA / VD resources
  2. The Citrix Gateway vServer directs the unauthenticated user directly to the Identity Provider (Azure-AD) to authenticate itself (saml: authnRequest)
  3. The Identity Provider points to its SingleSignOnService URL (e.g. login.microsoftonline.com) and the user must authenticate
  4. The user enters his AD credentials and these are checked by the Identity Provider against the user database
  5. Upon successful verification in the user database, the IdP is informed
  6. The IdP issues a token (SAML assertion) and sends it to the Citrix Gateway (saml: response)
  7. 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)
SAML Auth Azure AD & Citrix Gateway with FAS

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.

Requirements

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

Active Directory

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.

Active Directory Domains and Trusts

In the tool, right-click on the top item (Active Directory Domains and Trusts) and select Properties.

Active Directory Domains and Trusts Properties

In the following window enter the desired domain (e.g. deyda.net) under Alternative UPN Suffixes and confirm the entry via Add.

Add Alternative UPN Suffixes

Check that the domain name has been inserted correctly and confirm with OK.

UPN Suffixes

Now you can bulk edit or manually adjust the UPN of the required users to the Azure-AD domain.

Edit UPN

Certificate Authority

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.

Server Manager

Click through the wizard to the point Server Roles and select the item Active Directory Certificate Services. Confirms the selection with Add Features.

Add Roles and Features Wizard

Then click Next in the Server Roles, Features and AD CS tab.

Active Directory Certificate Services

Under the heading Role Services you select the following points:

  • Certification Authority
  • Certification Authority Web Enrollment
AD CS Role Services

If pop-up windows with additional features appear, you also confirm these with Add Features.

Certification Authority Web Enrollment Add Features

Complete the installation with Install.

Confirm installation selections

Now select the Notifications item in Server Manager and click on Configure Active Directory Certificate Services.

Notifications Configure ADCS

In the following configuration, the default settings can be confirmed with Next.

AD CS Configurations Credentials

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.

Configuration AD CS Confirmation

Now the domain controller must be issued a certificate of the local CA.

To do this, open the MMC on the domain controller.

start run mmc

Click on File and Add / Remove Snap-in …

Add Remove Snap-in

Now click on Certificates and on Add.

Certificates

In the following window select Computer account and confirm it with Next.

Certificates snap-in Computer account

Finally, close the window with OK.

Certificates Local Computer

Right-click on Personal and then on All Tasks > Request New Certificate…

Request New Certificate

In the Certificate Enrollment window, select your Active Directory Enrollment Policy and click Next.

Certificate Enrollment Before you begin
Certificate Enrollment Active Directory Enrollment Policy

Select Domain Controller Authentication and confirms this with Enroll.

Domain Controller Authentication 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.

Citrix Virtual Apps and Desktops  Federated Authentication Service

Click on “I have read, understand, and … ” and confirm it with Next.

Citrix Virtual Apps and Desktops 7 Licensing Agreement

Now confirm the following default settings with Next.

Citrix Virtual Apps and Desktops 7  Core Components

And click Next again.

Citrix Virtual Apps and Desktops 7  Firewall

Starts the installation with Finish.

Citrix Virtual Apps and Desktops 7  Summary

You may have to restart your server.

Citrix Virtual Apps and Desktops 7  Finish

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

Federated Authentication Service GPO Policy Definitions

Add them to the PolicyDefinitions Store of your Active Directory.

Federated Authentication Service GPO Policy Definitions 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
GPO Group Policy FAS

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.

cmd gpupdate /force FAS

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

Registry Editor HKEY_LOCAL_MACHINE \ SOFTWARE \ Policies \ Citrix \ Authentication \ UserCredentialService \ Addresses

Now start the Citrix Federated Authentication Service Tool with the “run as administrator” parameter

Citrix Federated Authentication Service Tool

Here you can see, the list of FAS servers that have been configured via GPO. Click on OK.

Connect to the Federated Authentication Service

The following window configures the FAS.

Click on Start in the frame 1 Deploy certificate templates.

Citrix Federated Authentication Service Configuration

Click on OK, so that the configuration is carried out automatically, in the background.

Deploy certificate templates FAS

After successful setup, the frame 1 appears in green.

Then click on Start in the context of 2 Setup Certificate Authority.

Setup Certificate Authority FAS

Under Certificate Authority, select your CA configured / created for FAS (e.g. DC01.deyda.local\CA-DEYDA) and click OK.

Setup certificate authority FAS Server

Upon successful setup, the frame 2 also appears in green.

Now click on Start at 3 Authorize this service.

Setup certificate authority FAS Server

Here select your CA and click OK.

FAS Server Authorize service Certificate Authority

Point 3 now appears in yellow, because the certificate request must be approved.

Waiting for Approval Pending Certificate

Reconnect to the server with the FAS CA and open the Server Manager. In Server Manager, click Tools > Certification Authority.

Server Manager CA Certification Authority

In the Certification Authority console, click on Pending Requests.

certsrv Certification Authority Local FAS

There you right click on the request of your FAS server (e.g. DEYDA \ CTX01) and click on All Tasks > Issue.

Pending Requests Issue All Tasks

Thereafter, the certificate appears under Issued Certificates.

Certification Authority Issued Certificates FAS Server

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.

Deauthorize this Service Citrix Federated Authentication Service

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.

Citrix FAS Administration BETA FAS SERVER

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)
Citrix Federated Authentication Service Configuration User Rules

At the bottom of Security Access Control Lists, click Edit next to List of Storefront servers that can use this rule.

Citrix Federated Authentication Service Configuration Security Access Control Lists

In the following window you delete the default group Domain Computers.

Citrix Federated Authentication Service Configuration Security Access Control Lists Permission for Storefront Servers

Then add your StoreFront servers and give them the Assert Identity (Allow) right. Confirm this with OK.

Citrix Federated Authentication Service Configuration Security Access Control Lists Permission for Storefront Servers FAS

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.

Citrix Federated Authentication Service Configuration Security Access Control Lists Permission for VDAs FAS

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.

Citrix Federated Authentication Service Configuration Security Access Control Lists Permission for Allowed Users FAS

After everything is defined click on Apply and close the FAS console.

Citrix Federated Authentication Service Configuration Rule updated successfully

StoreFront

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).

StoreFront Stores FAS PowerShell

Starts PowerShell as administrator on a StoreFront server.

Windows PowerShell Run as administrator StoreFront FAS

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"

Windows Power Shell FAS Get-STFAuthenticationService 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.

Manage Authentication Methods StoreFront Citrix

Enable Pass-through from Citrix Gateway if it is not enabled.

Citrix StoreFront Manage Authentication Methods Pass-through from Citrix Gateway

Then click on the gear on Pass-through from Citrix Gateway and on Configure Delegated Authentication.

Citrix StoreFront Manage Authentication Methods Pass-through from Citrix Gateway 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.

Citrix StoreFront Manage Authentication Methods Pass-through from Citrix Gateway Configure Delegated Authentication Fully delegate credential validation to Citrix Gateway

Click, back in the main window of the StoreFront console, on Manage Citrix Gateways.

Manage Authentication Methods StoreFront Citrix 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.

Manage Citrix Gateways ADD EDIT FAS

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.

StoreFront Authentication Settings Callback URL

Important here is that also in the internal DNS the callback address citrix.deyda.net is deposited.

DNS Lookup Fallback URL

In the main menu of the StoreFront console, click on Configure Remote Access Settings and check that the item … (No VPN tunnel) is activated.

Configure Remote Access Settings - Store Service Enable Remote Access

Delivery Controller

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.

Deliver Controller Citrix PowerShell Run as administrator

Now run the following command.

asnp citrix.*
Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true

Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true FAS Delivery Controller

Azure-AD

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.

portal.azure.com logon Microsoft Azure

In the Azure Navigation Panel, we click on Azure Active Directory.

Microsoft Azure Navigation Panel Azure Active Directory

In the Azure Active Directory window, click on Enterprise Applications.

Azure Active Directory Enterprise Application

Now click New Application.

Enterprise Application New Application Azure

And then on Non-gallery application.

Non-Gallery Application Enterprise Application Azure

In the Add my application window configure the name of the application for the end user, e.g. Citrix FAS and click Add.

Non-Gallery Application Enterprise Application Azure Name SAML based

Wait for the application to be created. Information is obtained via the Notifications item at the top.

Notifications New Application

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)

Enterprise Application All Application Citrix FAS

In the enterprise application click on Single sign-on.

Add Application Configure Single Signon

Under SSO method click on SAML.

SSO_Methode SAML Single-Signon Citrix FAS

The following window configure the communication between the Identity Provider and Service Provider.

Single-Signon SSO SAML Application

Click on the pencil icon in the upper area with the number 1 to edit the Basic SAML Configuration.

Basic SAML Configuration Application Single-Signon

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.

Basic SAML Configuration Entity ID Assertion URL

The settings under point 2 User attributes and claims can remain in the existing standard.

User Atribute Unique User ID

Under SAML Signing Certificate (Item 3), download the Certificate (Base 64) for the Service Provider (Citrix ADC).

SAML Signing Certificate Certificate (Base64) Download
Certificate Base64 Signature Identity Provider

From area 4 (Set up Citrix FAS), copy the displayed URLs (Login URL, Azure AD Identifier & Logout URL) to a local file.

SAML SSO Login URL Azure AD Identifier Logout URL

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.

Azure AD Application Users and Groups

Now click on Add user.

Add Users to Application

Now select from the list the users who should be granted access (or select all users) and confirm this with Assign.

Assign User or Group to Application

I only authorized one test user (user01) for this.

Assign User or Group to Application

Citrix ADC

Finally, the Citrix ADC must be configured to communicate with the Identity Provider (Azure-AD).

Citrix ADC Logon Mask

To do this, we log in to the Admin web interface of the Citrix ADC and navigate to Traffic Management > SSL > Certificates > Server Certificates.

Traffic Management SSL Certificates Server Certificats SAML

There, click Install to import the previously downloaded certificate from Azure Portal.

Server Certificates Install Azure Portal Signature Certificate

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)
Install Server Certificate NetScaler ADC

The installed certificate can not be found under Server or Client Certificates, but under Unknown Certificates.

Traffic Management SSL SSL Certificates Unknown Certificates SAML FAS

Then we navigate to Security > AAA – Application Traffic > Virtual Servers to create the SAML Authentication Policy and Authentication vServer.

NetScaler ADC SAML Security AAA - Application Traffic Virtual Servers

Under Authentication Virtual Servers, click Add to create a new vServer.

Authentication Virtual Servers AAA - Application Traffic FAS SAML

Now enter the following:

  • Name (Name of the vServer, e.g. Azure-AD_auth_VS
  • IP Address Type (Non Addressable)

Click on OK.

Authentication Virtual Server Basic Settings Non Addressable

In the following wizard click on No Server Certificate to connect your server certificate (not the IdP certificate).

No Server Certificate SAML Authentication Virtual Server

Click in the Click to select area.

Server Certificate Binding Wildcard

Select your Citrix ADC Server certificate (my wildcard certificate, for example) and click Select.

Server Certificate Binding Server Certificates Wildcard

Click on Bind.

Server Certificate Binding Server Certificates Wildcard Bind

If the certificate is attached (1 Server Certificate) click Continue.

Server Certificate SAML Authentication Virtual Server

Under the menu item Advanced Authentication Policies click on No Authentication Policy.

Server Certificate SAML Authentication Virtual Server Advanced Authentication Policies Authentication Policy

Click on the + symbol under Select Policy.

Policy Binding SAML Authentication Virtual Server Advanced Authentication Policies Authentication 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.

SAML Authentication Virtual Server Advanced Authentication Policies Authentication Policy Create

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.

SAML Authentication SAML Server Advanced Authentication Policies Authentication Action IDP Certificate Redirect URL Single Logout URL Signing Certificate

Check the entries again and click Create.

SAML Authentication SAML Server Advanced Authentication Policies Authentication Action

Under Policy Binding controls the inputs and changes the following:

  • Goto Expression (END)

Confirm this with Bind.

SAML Authentication SAML Server Advanced Authentication Policies Authentication Action END

If the Authentication Policy is connected click on Continue and Done.

SAML Authentication SAML Server Advanced Authentication Policies
SAML Authentication SAML Server

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.

Citrix ADC Gateway 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.

NetScaler Gateway Virtual Servers Edit

Resolves all connected LDAP or RADIUS authentication policy from the vServer. Click on the policies (1 LDAP Policy).

NetScaler Gateway Virtual Servers LDAP Policy

Select the policies and click Unbind.

Unbind LDAP Policy VPN Virtual Server Authentication

Confirm the window with Yes.

Confirm Pop Up Do you want to unbind the selected entitiy

Checks that neither a policy is connected in Basic Authentication nor in Advanced Authentication.

NetScaler Gateway Virtual Servers Basic Authentication Advanced Authentication SAML IDP Policy

On the right side, click Authentication Profile under Advanced Settings.

NetScaler Gateway Virtual Servers Basic Authentication Advanced Authentication SAML IDP Policy Authentication Profile

Click on the + symbol under Authentication Profile.

NetScaler Gateway Virtual Servers Basic Authentication Advanced Authentication Profile

Enter a name (e.g. saml_auth_profile) under Create Authentication Profile and click on Click to select under Authentication Virtual Server.

NetScaler Gateway Virtual Servers Basic Authentication Advanced Authentication SAML Authentication Profile

Select the previously created Authentication Virtual Server (Azure-AD_auth_VS) and click Select.

NetScaler Gateway Virtual Servers Basic Authentication Advanced Authentication SAML Authentication Profile Authentication Virtual Servers

Confirm the entry by clicking on Create.

NetScaler Gateway Virtual Servers Basic Authentication Advanced Authentication SAML Authentication Profile Authentication Virtual Servers

Click on OK and on Done.

NetScaler Gateway Virtual Servers Basic Authentication Advanced Authentication SAML Authentication Profile Authentication Virtual Servers

Navigate to NetScaler Gateway > Global Settings to delete the single sign-on domain.

NetScaler Gateway Global Settings

Click on Change Global Settings.

NetScaler Gateway Global Settings Change Global Settings

Deletes the possible entry under Single Sign-on Domain.

NetScaler Gateway Global Settings Change Global Settings Single Sign-on Domain

If necessary, the policies of the Gateway vServer must also be adjusted for Single Sign-on Domain.

NetScaler Gateway Polices Session Cache
NetScaler Gateway Polices Session Cache

Result

If we now open the FQDN of the gateway (https://citrix.deyda.net) via browser.

NetScaler with Unified Gateway

We will be forwarded directly to Azure-AD and can authenticate ourselves there.

Microsoft Login

We get our Citrix resources listed and can start them.

Citrix StoreFront
Successfull Logon

Leave a Reply

Your email address will not be published. Required fields are marked *

I consent to having this website store my submitted information so they can respond to my inquiry.