Citrix Federated Authentication Service (SAML) 2311

Last Modified: Mar 14, 2024 @ 3:07 pm

Navigation

This article applies to Federated Authentication Service (FAS) versions 2311, 2203 LTSR CU4, 1912 LTSR CU8, 7.15.9000 (LTSR), and all other versions 7.9 and newer.

Change Log

Overview

Citrix Federated Authentication Service (FAS) enables users to log in to Citrix Gateway and Citrix StoreFront using SAML authentication.

With SAML, Citrix Gateway and StoreFront do not have access to the user’s password and thus cannot perform single sign-on to the VDA. FAS works around this limitation by using issuing certificates that can be used to logon to the VDA.

  • StoreFront asks Citrix Federated Authentication Service (FAS) to use a Microsoft Certificate Authority to issue Smart Card certificates on behalf of users.
  • The certificates are stored on the FAS server.
  • The VDA requests the user’s certificate from FAS so it can complete the VDA Windows logon process.

FAS can be used for any authentication scenario where the user’s password is not provided.

Requirements:

  • Microsoft Certification Authority (CA) in Enterprise mode.
    • When configuring FAS, you tell it what CA server to use.
    • You can build a new CA server just for FAS.
    • You can install CA on the FAS server.
  • Domain Controllers must have Domain Controller certificates. See CTX218941 FAS – Request not supported.
    • The certificates on the Domain Controllers must support smart card authentication. Certificates created using the Microsoft CA certificate template named Domain Controller Authentication supports smart cards. Manually created Domain Controller certificates might not work. See CTX270737 for the Domain Controller certificate requirements.

  • Citrix Virtual Apps and Desktops or XenApp/XenDesktop 7.9 or newer
  • StoreFront 3.6 or newer
  • Citrix Gateway.
    • StoreFront 3.9 and newer also support SAML authentication natively without Citrix ADC.
  • SAML is web-based authentication and thus requires a browser.
    • SAML authentication might work in the newest builds of Workspace app and Citrix ADC 12.1 (and newer) if you configure nFactor. However, nFactor (Authentication Virtual Server aka AAA) requires ADC Advanced Edition or ADC Premium Edition.
  • For multiple domains, see Deployment Guide: Multi-Domain FAS Architecture at Citrix Tech Zone.

Configuration overview:

  1. Build one or more FAS servers.
    • For security reasons, FAS should be its own server and not installed on a Delivery Controller.
  2. Upload Certificate Templates to Active Directory and configure a CA server to issue certificates using the new templates.
    • Enterprise Admin permissions are needed to upload the Certificate Templates.
    • One of the Certificate Templates is for Smart Card logon to Citrix VDA.
    • The other two Certificate Templates are to authorize FAS as a certificate registration authority.
    • The registration authority certificate does not renew automatically so be prepared to renew it manually every two years. See Renew registration authority certificates at Citrix Docs.
  3. Install the Citrix FAS group policy .admx template into PolicyDefinitions.
  4. Create a group policy object (GPO) and configure the GPO with the addresses of the FAS servers.
    • The GPO must apply to FAS servers, StoreFront servers, and every VDA. It does not need to apply to Delivery Controllers, but there’s no harm in applying it to the Delivery Controllers.
  5. Authorize FAS to request certificates from a Microsoft CA server.
  6. Configure FAS Rules to permit StoreFront servers to request FAS to generate certificates for users and permit VDA machines to retrieve the certificates from FAS.
  7. Configure StoreFront to use FAS for VDA single sign-on.

Links:

From Citrix CTX225721 Federated Authentication Service High Availability and Scalability: you can build multiple FAS servers. Enter all FAS server FQDNs in the Group Policy. StoreFront will then use a hashing algorithm on the username to select a FAS server.

  1. If you have less than 10K users, one FAS server with 4 vCPUs (2.5Ghz) should be sufficient.
  2. You will require a minimum of one FAS server (with 8 vCPUs) per 25,000 users if all users expect to be able to logon under cold start conditions (no keys or certificates cached) within 60-90 minutes.
  3. A single FAS server can handle greater than 50K users under warm start conditions (keys and certificates pre-cached)
  4. One reserve FAS server for every four FAS servers for “Day 1” cold start (Users get new keys/certificates) & disaster recovery scenarios
  5. Split the FAS Certificate Authority from Certificate Authority that performs other tasks for both security and scalability purposes.

Michael Shuster explains the Group Policy configuration for FAS in multiple datacenters at HowTo: Active-Active Multi-Datacenter Citrix FAS.

Also see the Citrix Federated Authentication Service Scalability whitepaper.

Federated Authentication Service Versions

The most recent Federated Authentication Service Current Release is version 2308.

For LTSR versions of Citrix Virtual Apps and Desktops (CVAD) and StoreFront, install the version of FAS that comes with the CVAD LTSR version.

Install/Upgrade Federated Authentication Service

The service should be installed on a secure, standalone server that does not have any other Citrix components installed. The FAS server stores user authentication keys, and thus security is paramount.

  1. On the Federated Authentication Service server, go to the Citrix Virtual Apps and Desktops, or XenDesktop 7.9, or newer ISO, and run AutoSelect.exe. Or you can download the standalone installer and run that.
  2. In the lower half of the window, click Federated Authentication Service.
  3. In the Licensing Agreement page, select I have read, understand, and accept the terms of the license agreement, and click Next.
  4. In the Core Components page, click Next.
  5. In the Firewall page, click Next.
  6. In the Summary page, click Install.
  7. The installer will probably ask for a restart.

    1. After the reboot, and after logging in again, you might see a Locate ‘Citrix Virtual Apps and Desktops 7’ installation media window. Don’t click anything yet.
    2. Go to the Citrix_Virtual_Apps_and_Desktops_7_2308.iso file and mount it.
    3. Go back to the Locate ‘Citrix Virtual Apps and Desktops 7’ installation media window.
    4. On the left, expand This PC, and click the DVD Drive.
    5. Click Select Folder.

FAS Group Policy

Configure a Group Policy that instructs StoreFront servers and VDAs on how to locate the FAS servers.

  1. On the Federated Authentication Service server, browse to C:\Program Files\Citrix\Federated Authentication Service\PolicyDefinitions. Copy the files and folder.
  2. Go to \\domain.com\SYSVOL\domain.com\Policies\PolicyDefinitions and paste the files and folder. If PolicyDefinitions doesn’t exist in SYSVOL, then copy them to C:\Windows\PolicyDefinitions instead.
  3. Edit a GPO that applies to all StoreFront servers, all Federated Authentication Service servers, and all VDAs.
  4. Navigate to Computer Configuration > Policies > Administrative Templates > Citrix Components > Authentication.
  5. Edit the setting Federated Authentication Service.
  6. Enable the setting and click Show.
  7. Enter the FQDN of the Federated Authentication Service server. You can add more than one Federated Authentication Service server.
  8. Click OK twice.
  9. On the Federated Authentication Service server, and VDAs, run gpupdate.
  10. On the FAS server, and on VDAs, look in the registry at HKLM\Software\Policies\Citrix\Authentication\UserCredentialService\Addresses. Make sure this key and value exists. The number one cause why FAS doesn’t work is because this key is missing from VDAs. The FAS Address GPO must apply to VDAs too.
  11. If the VDAs and Users are in different domains, see CTX220497 Users from one AD Domain not able to get FAS user certificates from another trusted domain: add the Citrix StoreFront Servers, FAS server and VDA servers to the Windows Authorization Access Group in the users’ domain. Also see Deployment Guide: Multi-Domain FAS Architecture at Citrix Tech Zone.
  12. By default, the VDAs will verify the certificates aren’t revoked by downloading the Certificate Revocation List. You can disable CRL checking by configuring HKEY_Local_Machine\System\CurrentControlSet\Control\LSA\Kerberos\Parameters\UseCachedCRLOnlyAndIgnoreRevocationUnknownErrors (DWORD) = 1 as detailed at CTX217150 Unable to login using the FAS Authentication – Getting Stuck on Please wait for local session manager.
  13. If your VDAs have third party credential providers (e.g., Duo), then it might interfere with FAS Single Sign-on.

FAS 1909+ Configuration

If you prefer to script the FAS configuration, then see Citrix Blog Post Automating the Citrix Federated Authentication Service with PowerShell.

FAS 1909 and newer have a different configuration GUI than FAS 1906 and older.

Here are 1909 and newer GUI configuration instructions:

  1. Log into the FAS server as an Enterprise Administrator that can upload certificate templates to Active Directory.
  2. On the FAS server, from the Start Menu, run Citrix Federated Authentication Service as administrator. Make sure you run it elevated.
  3. In the tab named Initial Setup, in the row named Deploy certificate templates, click Deploy.
  4. Click OK to deploy the templates to Active Directory.
  5. In the row named Set up a certificate authority, click Publish.
  6. Select an Enterprise Certificate Authority that will be issue the FAS certificates and click OK.
  7. In the row named Authorize this service, click Authorize.
  8. Select a CA that will issue this FAS server a Registration Authority certificate. Later, you will need to open the Certificate Authority console on the chosen server. Click OK.
  9. The row named Authorize this service has a new icon indicating it is waiting on the registration authority certificate to be approved.
  10. Open the Certification Authority console and point it to the CA server. In the Pending Requests node, find the certificate request for the FAS server and Issue it.
  11. Back in the FAS Administration Console, on the top right, click Refresh.
  12. The row named Authorize this service should now have a green check mark.
  13. In the row named Create a rule, click Create.
  14. In the Rule name page, leave it set to Create the default rule and click Next.
  15. In the Template page, click Next.
  16. In the Certificate authority page, select the CA that has the issuing templates configured and click Next. You can select more than one CA server.
  17. In the In-session use page, click Next.
  18. In the Access control page, click the link to Manage StoreFront access permissions.
  19. In the Permission for StoreFront Servers page, add your StoreFront servers and give them the permission Assert Identity. Click OK.
  20. Back in the Create Rule wizard, click Next.
  21. In the Restrictions page, you can optionally reduce the VDAs that are authorized to use FAS. Click Next.
  22. In the Summary page, click Create.
  23. The FAS Registration Authority certificate expires in two years. You’ll need to manually renew the FAS Registration Authority certificate before it expires. Put a notification on your calendar. For details, see Renew registration authority certificates at Citrix Docs.
    • In the row named Authorize this service, you can click the link for authorization certificate to see when it expires. Before expiration, use the Reauthorize button on the right of the same row.
  24. Jump ahead to Certificate Templates.

FAS 1906 and older Configuration

If you prefer to script the FAS configuration, then see Citrix Blog Post Automating the Citrix Federated Authentication Service with PowerShell.

Here are GUI configuration instructions for FAS 1906 and older:

  1. Log into the FAS server as a Domain Administrator or Enterprise Administrator that can upload certificate templates to Active Directory.
  2. On the FAS server, from the Start Menu, run Citrix Federated Authentication Service as administrator. Make sure you run it elevated.
  3. The Federated Authentication Service FQDN should already be in the list (from group policy). Click OK.
  4. In Step 1: Deploy certificate templates, click Start.
  5. Click OK to add certificate templates to Active Directory. Sufficient permission is required.
  6. In Step 2: Setup Certificate Authority, click Start.
  7. Select a Certificate Authority to issue the certificates, and click Ok.
  8. In Step 3: Authorize this Service, click Start.

    • Step 3 automatically submits an online request for the Registration Authority certificate to the CA and stores the non-exportable private key in the standard Microsoft Enhanced RSA and AES Cryptographic Provider.
    • Alternatively, you can submit the certificate request manually, and store the private key in TPM or HSM as detailed at Federated Authentication Service private key protection at Citrix Docs. When running New-FasAuthorizationCertificateRequest, the -UseTPM switch is optional.
  9. Select the issuing Certificate Authority, and click OK.

    • Authorize this Service only lets you select one Certificate Authority. If you want to load balance certificate requests against multiple Certificate Authorities, then see Set up multiple CA servers for use in FAS at Citrix Docs.
      Set-FasCertificateDefinition -Name default_Definition -CertificateAuthorities @("ca1.corp.local\CA1.corp.local", "ca2.corp.local\ca2.corp.local")
  10. Step 3 is now yellow.
  11. On the Microsoft CA server, go to the Certification Authority Console > Pending Requests. Find the pending request, and Issue it.
  12. In a minute or two, Federated Authentication Service will recognize the issued certificate and Step 3 will turn green.
  13. After FAS authorization with the CA, in the FAS Configuration tool, switch to the User Rules tab.
  14. Use the Certificate Authority drop-down to select the issuing Certificate Authority.
  15. Use the Certificate Template drop-down to select the Citrix_SmartcardLogon template.
  16. Click Edit next to List of StoreFront servers that can use this rule.
  17. Remove Domain Computers from the top half, and instead add your StoreFront servers. You could add an Active Directory security group instead of individual StoreFront servers.
  18. On the bottom half, make sure Assert Identity is Allowed. Click OK.
  19. By default, all users and all VDAs are allowed. You can click the other two Edit boxes to change this.
  20. When done, click Apply.
  21. Click OK when you see Rule updated successfully.
  22. The FAS Registration Authority certificate expires in two years. You’ll need to manually renew the FAS Registration Authority certificate before it expires. Put a notification on your calendar. For details, see Renew registration authority certificates at Citrix Docs.
    • To see the expiration date of the authorization certificate, run the following PowerShell command after running add-pssnapin Citrix.Authentication.FederatedAuthenticationService.V1:
      Get-FasAuthorizationCertificate -FullCertInfo -address myFASServer

Certificate Templates

The deployed FAS Certificate Templates from older versions of FAS have Autoenroll enabled. Newer versions of FAS (e.g., 2203) no longer have Autoenroll enabled.

  1. Open the Certificate Templates console. One option is to open the Certification Authority console, right-click Certificate Templates, and then click Manage.
  2. There should be three templates with names starting with Citrix_. Open the properties on each one.
  3. On the Security tab, highlight each group assigned to the template.
  4. On the bottom half, uncheck the box in the Autoenroll row but leave Enroll checked. Perform this step for every group assigned to this template. Then click OK.
  5. Repeat disabling autoenroll for the other two templates.

The Registration Authority certificate templates are permitted to all Domain Computers. You might want to change that.

  1. Open the Properties of one of the Citrix_RegistrationAuthority certificate templates.
  2. On the Security tab, remove Domain Computers.
  3. Add your FAS servers and enable the Enroll permission.
  4. Repeat for the other Registration Authority certificate.

To further restrict who can be issued certificates, go to your Certificate Authority’s Properties and use the Enrollment Agents tab to restrict enrollment agents.

StoreFront Configuration

Once FAS is enabled on a StoreFront store, it applies to all connections through that store, including password-based authentications. One option is to create a new store just for FAS users.

  1. Check the registry at at HKLM\Software\Policies\Citrix\Authentication\UserCredentialService\Addresses to confirm that the group policy with FAS addresses has been applied to the StoreFront servers.
  2. On the StoreFront 3.6 or newer server, run the following elevated PowerShell command:
    & "$Env:PROGRAMFILES\Citrix\Receiver StoreFront\Scripts\ImportModules.ps1"
  3. Run the following commands. Adjust the store name as required.
    $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"
  4. If you have multiple StoreFront servers, Propagate Changes.
  5. In Web Studio (CVAD 2212 and newer), go to Settings and Enable XML Trust.

    • Or on a Citrix Delivery Controller, run the following commands:
      asnp citrix.*
      Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true

If you ever need to disable FAS on StoreFront, run the following commands. Adjust the store name as required.

$StoreVirtualPath = "/Citrix/Store"
$store = Get-STFStoreService -VirtualPath $StoreVirtualPath
$auth = Get-STFAuthenticationService -StoreService $store
Set-STFClaimsFactoryNames -AuthenticationService $auth -ClaimsFactoryName "standardClaimsFactory"
Set-STFStoreLaunchOptions -StoreService $store -VdaLogonDataProvider ""

SAML Configuration

SAML Flow

SAML flows like this:

  1. (Optional) User goes to the web application aka Service Provider (e.g. Citrix Gateway).
    • The Service Provider (SP) redirects the user’s browser to the Identity Provider’s (IdP) SAML Single Sign-on (SSO) URL and includes an authentication request in the Redirect. The IdP SSO URL might be different for each Service Provider.
    • The Authentication Request from the Service Provider includes a Service Provider Entity ID. The IdP matches the SP Entity ID with an entry in its database so it knows which SP is making the authentication request. The Entity ID must match on both the SP and the IdP.
    • If the Authentication Request is signed by the Service Provider’s certificate private key, then the IdP will verify the signature using the Service Provider’s certificate public key. In this scenario, the Service Provider’s certificate (without private key) must be loaded into the IdP.
  2. The user authenticates to the IdP, typically using Multi-factor Authentication.
    • If the user was redirected from the SP, then the IdP already knows which SP to authenticate with.
    • If the user went directly to the IdP, then the user typically needs to click an icon representing the web application (Service Provider).
  3. IdP generates a SAML Assertion containing the user’s userPrincipalName or email address.
    • Configure the IdP to include the user’s UPN or email address in the NameID field of the assertion. SAMAccountName won’t work with Citrix FAS.
    • The SAML Assertion also includes the Service Provider’s Entity ID. The ID in the Assertion must match the ID configured on the SP.
    • IdP signs the SAML Assertion using an IdP certificate private key.
    • IdP has a configuration for the SP that includes a SAML Assertion Consumer Service (ACS) URL. IdP redirects the user’s browser to the SP’s ACS URL and POST’s the SAML Assertion.
      • The ACS URL on Citrix Gateway ends in /cgi/samlauth
  4. SP uses the IdP certificate’s public key to verify the signature on the SAML Assertion.
    • The IdP’s certificate (without private key) is installed on the Citrix ADC so it can verify the Assertion’s signature.
  5. SP extracts the user’s userPrincipalName from the Assertion and uses the UPN for Single Sign-on to StoreFront and the rest of the Citrix components.
    • Note that the SP does not have access to the user’s password and thus that’s why we need Citrix FAS to generate certificates for each user.

Configure the SAML IdP

You typically start the configuration on the Identity Provider (IdP). Every IdP has unique instructions. Search Google for your IdP and Citrix ADC and you might find a IdP-specific guide. After IdP configuration, you download the IdP’s certificate and copy the IdP’s SSO URL so you can configure them on Citrix ADC.

Azure AD as SAML IdP

  1. In Azure Portal, go to Azure Active Directory.
  2. On the left, click Enterprise applications.
  3. In the new blade that appears, on the All applications page, on the right, click New application.
  4. In the All Categories view of the gallery, on the top right, click Non-gallery application.
  5. Give the application a descriptive name. Azure AD shows this name in the myapps portal. Click Add.
  6. After the application is created, on the left, in the Manage section, click Single sign-on.
  7. On the right, click the big button for SAML.
  8. In section 1 labelled Basic SAML Configuration, click the pencil icon.
  9. In the Identifier (Entity ID) field, enter an identifier in URI format. Usually it matches the FQDN of the Citrix Gateway and can be entered in https://gateway.corp.com format. You’ll later need to specify the exact same Identifier on the Citrix ADC.
  10. In the Reply URL (Assertion Consumer Service URL) field, enter a URL similar to https://mygateway.company.com/cgi/samlauth. The path must be /cgi/samlauth. The scheme should be https. And the FQDN is your Citrix Gateway’s FQDN.
  11. Click Save. Then you might have to click the x on the top right to make it go away.
  12. In section 2 labelled User Attributes & Claims, notice that it defaults to sending the userprincipalname. You can click the pencil to change the attribute used for the Name identifier value. Whatever value you send will need to match the userPrincipalNames of local Active Directory accounts (aka shadow accounts).


  13. In section 3 labelled SAML Signing Certificate, click the Download link in the Certificate (Base64) line.
  14. Citrix ADC 12.1 and newer support SAML metadata so feel free to copy the App Federation Metadata Url field.
  15. If you are running NetScaler 12.0 or older, then you will need to copy the Login URL field from section 4 labelled Set up gateway5.corp.com
  16. On the left, under Manage, click Users and groups.
  17. Use the normal process to assign Azure AD users and groups to this application. Click Assign.
  18. Jump to the section named Citrix ADC SAML Configuration.

ADFS as SAML IdP

The screenshots in this section use ADFS as an example IdP. Your IdP will be different.

  1. In your SAML IdP, create a Relying Party Trust (aka service provider trust) or new Application.
  2. Since we’re configuring the IdP before we configure Citrix ADC and thus don’t have access to the SP metadata, select the option to Enter data about the relying party manually.
  3. For the Assertion Consumer Service URL (aka relying party service URL), enter the URL to your Citrix Gateway with /cgi/samlauth appended to the end (e.g. https://gateway.corp.com/cgi/samlauth)
  4. Enter a Relying party trust identifier in URI format. You must specify the same identifier (Issuer Name) on the Citrix ADC as detailed in the next section.
  5. Configure the SAML IdP to send email address or User-Principal-name as Name ID. Citrix ADC receives the Name ID and sends it to StoreFront. StoreFront will look in Active Directory for an account with userPrincipalName that matches the Name ID.
  6. Citrix ADC will sign the authentication requests it sends to the IdP. On the Citrix ADC, you will soon configure the Citrix ADC SAML SP signing certificate with private key that signs the authentication requests that are sent to the IdP. In your SAML IdP, import the same Citrix ADC SAML SP signing certificate but without the private key.
  7. Copy the SAML authentication URL (aka Token Issuance URL) from your SAML IdP. You’ll need to enter this same URL on your Citrix ADC later.
  8. Export the IdP Token-signing certificate from your SAML IdP. The IdP could be ADFS, Okta, Ping, etc.

Citrix ADC SAML Configuration

SAML Server/Action

  1. Instructions for Citrix ADC 13.0, Citrix ADC 12.1, NetScaler 12.0, and NetScaler 11.1 are essentially the same.
    • Citrix ADC 12.1 and newer support SAML Metadata while older versions of NetScaler do not support SAML Metadata.
    • NetScaler 11 is very similar, except Certificates are in a different place in the NetScaler menu tree.
  2. Workspace app support – If you bind a SAML Authentication Policy directly to the Gateway Virtual Server (no nFactor/AAA), then Workspace app and Gateway VPN plug-in won’t work. To support SAML with Workspace app and Gateway VPN plug-in, configure nFactor (Authentication Virtual Server with Authentication Profile) instead of directly on the Gateway Virtual Server. Note: nFactor authentication is only available with ADC Advanced Edition and ADC Premium Edition.
  3. IdP Signing Certificate – On Citrix ADC, if you are not importing IdP metadata, then manually import the IdP SAML token-signing certificate (without private key) under Traffic Management > SSL > Certificates > CA Certificates. Citrix ADC uses this certificate to verify the signature of the SAML assertion from the IdP.
    Note: when you later create the SAML Action on Citrix ADC, there’s a place to add a SAML certificate. Unfortunately, the SAML Action is trying to import the wrong type of certificate since it wants the private key, which you don’t have access to. If you import the certificate here under CA Certificates, then there’s no prompt for private key.


    • SAML IdP certificates are shown in the Unknown Certificates node.
  4. If you want ADC to sign the authentication requests it sends to the IdP, then do the following:
    1. Move up two nodes to Server Certificates and Import or create a SP SAML signing certificate with private key. This can be the same certificate used on Citrix Gateway. Or a more common practice is to create a self-signed certificate.

    2. You’ll also need to import this SAML SP signing certificate (without private key) to your SAML IdP so it can verify the SAML authentication request signature from the Citrix ADC.
  5. Go to Citrix Gateway > Policies > Authentication > SAML. The quickest way to get here is to enter SAML in the search box on top of the menu.
  6. On the right, switch to the tab labelled Servers, and click Add.
  7. In the Name field, give the SAML Action a name that indicates the IdP’s name.
  8. If your Citrix ADC is 12.1 or newer, then get the SAML Metadata URL (or file) from the IdP.

    1. In the SAML Server on Citrix ADC, in the SAML IDP Metadata URL field, paste in the URL. ADC should be able to extract the IdP’s certificate from the Metadata URL.
    2. In the Issuer Name field, enter the ID that the SAML IdP is expecting for the Relying Party.  This Issuer Name must match the name you configured on the IdP’s Relying Party (Service Provider) Trust. Azure AD calls this the Identifier or Entity ID.
    3. Near the bottom, configure a Relay State Rule to prevent session hijack. It should check the Relay State field to make sure it matches the URL that users using to reach the Gateway Virtual Server. Make sure you include the forward slash at the end of the URL. Sample expression below. Pattern set is also possible. See CTX316577 for details. To avoid relay state “does not match” error, make sure users enter the Gateway URL instead of using a bookmark. 💡
      AAA.LOGIN.RELAYSTATE.EQ("https://gateway5.corp.com/")

    4. Scroll down and click Create.
    5. Edit the SAML Server again.
    6. If you uncheck the box next to Import Metadata, you can see the fields that it filled in for you. Unfortunately, other fields must be configured manually as detailed soon.
  9. Configure the SAML Server based on the data provided by your IdP. If you imported Metadata, then some of the fields might already be populated.
    1. For IDP Certificate Name, select the SAML IdP’s certificate that was exported from the SAML IdP and imported to Citrix ADC. Citrix ADC will use this IdP certificate to verify SAML assertions from the IdP.
      Note: the Add button here does not work correctly. Instead, if you need to import the SAML IDP certificate, then do it at the CA Certificates node as detailed earlier in this section.
    2. For Redirect URL, enter the URL to the SAML IdP’s authentication page. Citrix Gateway will redirect users to this URL. For ADFS, enter your ADFS URL appended with /adfs/ls (e.g. https://adfs.corp.com/adfs/ls). For other IdP’s, get the URL from your IdP.
    3. For User Field, enter the name of the SAML Claim from the IdP that contains the value that matches the userPrincipalName of your local Active Directory users (aka shadow accounts). This defaults to the NameID field, but you might have to use a different claim, like emailaddress.
    4. In the Issuer Name field, enter the ID that the SAML IdP is expecting for the Relying Party.  This Issuer Name must match the name you configured on the IdP’s Relying Party (Service Provider) Trust. Azure AD calls this the Identifier or Entity ID.
    5. Near the bottom, configure a Relay State Rule to prevent session hijack. It should check the Relay State field to make sure it matches the URL that users using to reach the Gateway Virtual Server. Make sure you include the forward slash at the end of the URL. Sample expression below. Pattern set is also possible. See CTX316577 for details. 💡
    6. Optionally, for Signing Certificate Name, select the SAML SP certificate (with private key) that Citrix ADC will use to sign authentication requests to the IdP. This same certificate (without private key) must be imported to the IdP, so the IdP can verify the authentication request signature. This field usually isn’t needed by most IdPs.
    7. Scroll down and click More.
    8. Citrix ADC defaults to SHA1. You might have to change the Signature Algorithm and Digest Method to SHA256.
    9. Review the other settings as needed by your IdP. Click Create when done.

SAML Policy – Advanced (nFactor) Method

Workspace app and Gateway Plugin (i.e. VPN plugin) require nFactor (Advanced Authentication Policies) to support SAML authentication.

Licensing – nFactor requires NetScaler ADC Advanced Edition or NetScaler ADC Premium Edition. The newest builds of NetScaler ADC 13 have added nFactor support for NetScaler ADC Standard Edition, but the configuration of an Authentication Virtual Server is not directly accessible from the main menu. If you only have Standard Edition, then do the following to get to the Authentication Virtual Server:

  1. Go to Citrix Gateway > Virtual Servers and edit one.
  2. On the right, add the Authentication Profile section.
  3. On the left, in the Authentication Profile section, click Add to create an Authentication Profile.
  4. In the Authentication Virtual Server row, click Add to create an Authentication Virtual Server.
  5. The rest of the nFactor configuration is similar to what’s detailed below.

If you prefer to configure the older Classic Method, which doesn’t work with Workspace app, then skip to the Classic Method.

Do the following to create an Advanced Authentication Policy, an Authentication Virtual Server, and bind it to the Gateway Virtual Server:

  1. In the left menu, expand Security, expand AAA – Application Traffic, expand Policies, expand Authentication, expand Advanced Policies, and then click Policy.
  2. On the right, click the button labelled Add.

    1. Change the drop-down for Action Type to SAML.
    2. Change the drop-down for Action to the SAML Action you created earlier.
    3. In the box labelled Expression, enter true.
    4. Give the policy a name and click Create.
  3. In the left menu, expand Security, expand AAA – Application Traffic and then click Virtual Servers.
  4. On the right, click the button labelled Add.

    1. Change the drop-down named IP Address Type to Non Addressable and then click OK.
  5. You can optionally bind a Server Certificate. If you don’t bind a certificate, then the AAA vServer will be down but it will still work. It doesn’t matter what certificate you choose. Click Continue when done.
  6. On the left, in the section named Advanced Authentication Policies, click the row that says No Authentication Policy.

    1. Click where it says Click to select.
    2. Click the small circle to the left of the SAML Policy that you created earlier. Then click the blue button labelled Select at the top of the screen.
    3. There’s no need to configure Select Next Factor unless you want to bind an LDAP Policy with Authentication Disabled so you can extract groups from Active Directory and use those groups for Gateway authorization. This configuration procedure is detailed in the next section.
    4. Click the blue button labelled Bind at the bottom of the window.
  7. Click Continue,
  8. At the bottom of the page, click Done to finish creating the AAA vServer.
  9. In the left menu, expand Citrix Gateway and click Virtual Servers.
  10. On the right, edit your existing Gateway Virtual Server.
  11. On the right side of the screen, in the Advanced Settings column, click Authentication Profile.
  12. On the left side of the screen, find the Authentication Profile section and then click the button labelled Add.
  13. Click where it says Click to Select and then select your AAA vServer.
  14. Give the Authentication Profile a name and then click the blue button named Create.
  15. Make sure you click the blue OK button before you click Done. If you don’t click OK then your changes won’t be saved.

Here are some sample CLI commands for this nFactor SAML configuration.

# SAML Actions
# ------------
add authentication samlAction "Azure AD" -samlIdPCertName AzureADSAML -samlSigningCertName WildcardCorpCom -samlRedirectUrl "https://login.microsoftonline.com/815e26a9-4a9b/saml2" -samlIssuerName gateway5.corp.com -Attribute1 emailaddress -logoutURL "https://login.microsoftonline.com/815e26a9/saml2" -logoutBinding REDIRECT -relaystateRule "aaa.LOGIN.RELAYSTATE.EQ(\"https://gateway5.corp.com/\")"

# SAML Authentication Policies
# ----------------------------
add authentication samlPolicy "Azure AD" ns_true "Azure AD"

# Advanced Authentication Policies
# --------------------------------
add authentication Policy "Azure AD Advanced" -rule true -action "Azure AD"

# Authentication Virtual Servers
# ------------------------------
add authentication vserver nFactor-AzureAD-SAML SSL 0.0.0.0
bind authentication vserver nFactor-AzureAD-SAML -policy "Azure AD Advanced" -priority 100 -gotoPriorityExpression NEXT

# Authentication Profiles
# -----------------------
add authentication authnProfile nFactor-AzureAD-SAML -authnVsName nFactor-AzureAD-SAML

# Citrix Gateway Virtual Servers
# ------------------------------
set vpn vserver gateway5.corp.com -authnProfile nFactor-AzureAD-SAML

SAML nFactor LDAP Group Extraction

If you use AAA Groups with Citrix Gateway, then be aware that SAML usually does not provide the user’s group membership. Instead, configure a LDAP Policy to get the user’s groups from Active Directory so the groups can be later used by Citrix Gateway.

If you don’t need LDAP Group Extraction, then skip ahead to the StoreFront section.

Do the following to configure LDAP Group Extraction.

  1. Create a new LDAP Action.
    1. Use the Search in Menu to find LDAP then pick any of the results.
    2. Check the box next to an existing LDAP policy and click Add to copy its configuration. Or create a new one.
    3. Change the name of the LDAP Action.
    4. On the top right, uncheck the box next to Authentication.
    5. Scroll down a bit and in the right side re-enter the Administrator Password. Copying an existing LDAP Action does not copy the Bind password.
    6. Scroll down to the Other Settings section.
    7. On the left, change Server Logon Name Attribute to –<< New >>–.
    8. Enter userPrincipalName. The UPN is extracted from the SAML Assertion.
    9. Scroll down and click Create.
  2. On the left, go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > Policy and click Add to create a new Policy.

    1. Change Action Type to LDAP.
    2. Expression = true.
    3. Click Create.
  3. On the left, go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > Policy Label. On the right, click Add.

    1. Give the Policy Label a name and click Continue. The Login Schema should be LSCHEMA_INT.
    2. Select your LDAP Group Extract policy and then on the bottom click Bind.
    3. Click Done to close the Policy Label.
  4. On the left, go to Security > AAA – Application Traffic > Virtual Servers. On the right, edit your SAML AAA vServer.

    1. Click where it says 1 Authentication Policy.
    2. Right-click the Authentication Policy and then click Edit Binding.
    3. In the Select Next Factor field, click where it says Click to select.
    4. Select your LDAP Group Extract Policy Label and then click Bind.
  5. Skip ahead to the StoreFront section.

Here are some sample CLI commands for this nFactor SAML LDAP Group Extract configuration.

# LDAP Actions
# ------------
add authentication ldapAction LDAP-GroupExtract -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn ctxsvc@corp.local -ldapBindDnPassword ****** -ldapLoginName userPrincipalName -groupAttrName memberOf -subAttributeName cn -secType SSL -authentication DISABLED

# LDAP Policies
# -------------
add authentication ldapPolicy LDAP-Corp ns_true LDAP-Corp

# Authentication Policy Labels
# ----------------------------
add authentication policylabel LDAP-GroupExtract -loginSchema LSCHEMA_INT
bind authentication policylabel LDAP-GroupExtract -policyName LDAP-GroupExtract -priority 100 -gotoPriorityExpression NEXT

# Authentication Virtual Servers
# ------------------------------
bind authentication vserver nFactor-AzureAD-SAML -policy "Azure AD Advanced" -priority 100 -nextFactor LDAP-GroupExtract -gotoPriorityExpression NEXT

SAML Policy – Classic Method

Classic Policies are deprecated and will be removed in a future release of Citrix ADC. Only use this method if you are not licensed for ADC Advanced Edition or ADC Premium Edition. Recent builds of ADC 13.0 added nFactor in ADC Standard Edition but its configuration is not ideal.

  1. In the menu on the left, expand Citrix Gateway, expand Policies, expand Authentication, expand SAML.
  2. On the right, switch to the tab labelled Policies, and click Add.

    1. Give the policy a name, select the SAML Server, and enter ns_true for the expression. Click Create.
  3. Create Citrix Gateway Session Polices if you haven’t already.
  4. Edit your Session Policy/Profile.

    1. On the tab labelled Published Applications, make sure Single Sign-on Domain is not configured. Repeat this for your other Session Policies/Profiles.
  5. Create a Citrix Gateway Virtual Server if you haven’t already.
  6. Edit your Citrix Gateway Virtual Server.
  7. Scroll down to the Basic Authentication section, and add a policy by clicking the plus icon.
  8. Change the type to SAML and click Continue.
  9. Select your SAML policy and bind it. This is the only authentication policy you need. You can remove all other authentication policies.
  10. Next step: configure StoreFront for SAML Citrix Gateway.

Configure StoreFront for SAML Citrix Gateway

  1. In StoreFront 3.6 or newer, in the StoreFront Console, go to Stores, right-click the store, and click Manage Authentication Methods.
  2. Make sure Pass-through from Citrix Gateway is selected.
  3. Click the bottom gear icon on the right, and click Configure Delegated Authentication.
  4. Check the box next to Fully delegate credential validation to Citrix Gateway and click OK twice.
  5. In StoreFront, add a Citrix Gateway object that matches the FQDN of the Citrix Gateway Virtual Server that has SAML enabled.
  6. On the Authentication Settings page, make sure you configure a Callback URL. It won’t work without it.
  7. Then assign (Configure Remote Access Settings) the Gateway to your Store.

  8. Next step: create Active Directory Shadow Accounts

Native SAML on StoreFront without Citrix ADC

StoreFront 3.9 and newer have native support for SAML Authentication without Citrix ADC. Notes:

  • SAML overrides Explicit and Pass-through authentication.
  • SAML in StoreFront without Citrix ADC seems to work in Workspace app and Receiver Self-Service for Windows.

For an example configuration using StoreFront PowerShell commands and SAML metadata, see CTX232042 Configure StoreFront with OKTA.

To configure native SAML in StoreFront 3.9 or newer:

  1. Export the signing certificate from your SAML IdP. The IdP could be ADFS, Okta, Ping Identity, etc.
  2. In StoreFront 3.9 or newer console, right-click a Store, and click Manage Authentication Methods.
  3. Check the box next to SAML Authentication. If you don’t see this option (because you upgraded from an older version), click the Advanced button on the bottom of the window, and install the authentication method.
  4. On the right, click the gear icon for SAML, and click Identity Provider.
  5. Change the SAML Binding to the method your IdP expects.
  6. Enter the IdP token issuance endpoint URL. For example, in ADFS, the path is /adfs/ls.
  7.  Click Import.
  8. Browse to the signing certificate exported from your IdP, and click Open.
  9. Then click OK to close the Identity Provider window.
  10. On the right, in the SAML Authentication row, click the gear icon, and then click Service Provider.
  11. Click the first Browse button.
  12. Give the Signing certificate a name, and save it somewhere.
  13. Click the second Browse button.
  14. Give the Encryption certificate a name, and save it somewhere.
  15. Copy the Service Provider Identifier. Or you can change it to your desired value. Then click OK.
  16. In your IdP (e.g. ADFS), create a Relying Party Trust.
  17. Import the Encryption certificate that you exported from StoreFront.
  18. Enable SAML 2.0.
  19. For the Assertion Consumer Service (ACS) path, enter something similar to https://storefront.corp.com/Citrix/StoreAuth/SamlForms/AssertionConsumerService. The hostname portion of the URL is equivalent to your StoreFront Base URL. /Citrix/StoreAuth matches your Store name with Auth on the end. The rest of the path must be /SamlForms/AssertionConsumerService. You can get this ACS value by looking in the SAML metadata at the bottom of https://<storefront host>/Citrix/StoreAuth/SamlForms/ServiceProvider/Metadata.

  20. For the Relying party trust identifier, enter the identifier you copied from the Service Provider window in StoreFront.
  21. Configure the Claim Rules to send the user’s email address or userPrincipalName as Name ID.
  22. Edit the Relying Party Trust. Import the Signing certificate that you exported from StoreFront.

  23. Create Active Directory Shadow Accounts. Federated users must be userPrincipalName mapped to local Active Directory accounts.
  24. If you point your browser to https://<storefront-host>/Citrix/<storename>Auth/SamlTest, it should perform a SAML Login, and then show you the assertion that was returned from the IdP. See Citrix CTX220639 How to configure SAML Authentication-Test Configuration.
  25. See Citrix CTX220682 Storefront SAML Troubleshooting Guide for event logs, SAML Metadata, Active Directory account mapping, Trust XML, etc.
  26. When you go to your Receiver for Web page, it should automatically redirect you to your IdP. After authentication, it should redirect you back to StoreFront and show you your icons.
  27. ADFS also works in Receiver 4.6 and newer, and Workspace app.
  28. When you logoff, it won’t let you log on again unless you close your browser and reopen it.

  29. To fix this problem, see CTP Sacha Thomet StoreFront – Allow relogin without browser close. Edit the file C:\inetpub\wwwroot\Citrix\StoreWeb\custom\script.js, and add the following line:
    CTXS.allowReloginWithoutBrowserClose = true

  30. Now when you logoff, you’re given an option to log on again.

Active Directory Shadow Accounts

To login to Windows (Citrix VDA), every user must have an Active Directory account in a domain trusted by the VDA. For Federated Users, you typically need to create shadow accounts for each Federated user in your local Active Directory. These Shadow accounts need a userPrincipalName that matches the SAML attribute (usually email address) provided by the SAML IdP.

If the email address provided by the SAML IdP does not match the UPN suffix for your domain, then do the following:

  1. Open Active Directory Domains and Trust.
  2. Right-click the top left node (not a domain node), and click Properties.
  3. In the UPN Suffixes tab, add a UPN suffix that matches the email suffix provided by the SAML IdP.
  4. When creating a shadow account in your Active Directory, the new UPN suffix is available in the drop-down list. Note that the pre-Windows 2000 logon name can’t conflict with any other user in the domain.
  5. The password for these Shadow accounts can be any random complex password since the Federated users never need the Shadow account’s password.
  6. If the shadow account is already created, edit the account, and on the Account tab, use the drop-down to select the new UPN suffix.
  7. Create a shadow account for every federated user. There are third party Identity Management tools that can automate this. Or get an export from the IdP and use PowerShell scripting to create the acccounts.

Verify FAS

When FAS is enabled on StoreFront, every user that logs into StoreFront (local or remote) causes a user certificate to be created on the FAS server. You can see these user certificates by running the following PowerShell commands:

Add-PSSnapin Citrix.Authentication.FederatedAuthenticationService.V1
Get-FasUserCertificate -address fas01.corp.local

Citrix uses these certificates to logon to the VDA as the user. No password needed.

1,036 thoughts on “Citrix Federated Authentication Service (SAML) 2311”

  1. Hey Carl,

    I just wanted to understand one situation, if we are using Citrix Gateway with SAML IDP authentication by configuring OAuth Idp policies and profile, within our Cloud workspace URL (custom domain URL), do we still need to use FAS. Based on the Citrix documentation, it says, if you are using Citrix Gateway for Authentication in the workspace configuration you would not need FAS. However, we have the option enabled for Federated Identity Providers, under preferences within workspace configuration. As currently on launching resources we are being prompted to enter credentials to sign in to VDA, in my perspective if I disable the Federated Identity provider option in workspace configuration, I should be able to achieve SSO on VDA from the workspace session.

    Let me know what your thoughts are on this…

    1. OAuth (OpenID Connect), like SAML, does not provide the user’s password, and thus FAS is needed to SSON to the VDA.

      1. But with Citrix Gateway being used as authentication within the workspace configuration as per Citrix documents – https://docs.citrix.com/en-us/citrix-workspace/optimize-cvad/workspace-federated-authentication.html
        it does not mention to use FAS. So is it because we are using SAML auth within the gateway virtual server ?

        From Citrix documentation –
        FAS isn’t needed for SSO to DaaS if you’re using Active Directory (AD), AD plus Token, or specific configurations of Citrix Gateway. For more information on configuring Citrix Gateway, visit Create an OAuth IdP policy on the on-premises Citrix Gateway.

        1. This refers to you building your own Citrix Gateway.

          Specific configurations of Citrix Gateway refers to authentication methods that capture the user’s password. SAML does not provide the user’s password.

          OAuth IdP policy is how you connect your Citrix Gateway to Citrix Cloud. It’s unrelated to user authentication.

          1. This is how we have configured in our environment – using the OAuth IDP – https://docs.netscaler.com/en-us/citrix-adc/current-release/aaa-tm/authentication-methods/oauth-authentication/citrix-adc-oauth-idp

            with the option to Send Password checked. So ideally this should allow SSO to the resources, however not working for us. I agree that OIDC, would not store user’s password but it does sends the token with specific lifetime, that could be used for authentication to enterprise wide web-apps. So specifically for sign on to the VDAs it might require FAS.
            Thanks for your feedback and suggestions on this. I will try to see if adding FAS would help in this scenario or not.

          2. Hi Uddave,

            as Carl already said, OAuth and SAML per default are not containing any password, so FAS will be required, also when you’re using your NetScaler as IdP via OAuth to DaaS.

            BUT it depends on how your Auth-Flow on the NetScaler side looks like. For example, you’re doing LDAP (+ RADIUS) on your NetScaler, than the Password will be transferred via OAuth to DaaS, resulting in no need for FAS. Here’s a simple example – not intended to be self-promotion – https://www.julianjakob.com/citrix-adc-an-identity-provider-idp-solution-with-mfa-for-onprem-services-and-citrix-daas/#Citrix_DaaS_with_OAuth and another example when you want to use Entra ID on your NetScaler side but also no FAS for DaaS: https://www.julianjakob.com/netscaler-how-to-get-rid-of-sso-missing-prt-issues-using-entra-id-phone-sign-in/#DaaS

          3. Hey Julian,
            Thanks a lot for your feedback on that. Yes it does make sense now. If we are not using SAML within the NetScaler Auth Flow then we could have SSO passed on from workspace session to the VDA.

            Once again appreciate you sharing additional information.
            Thanks again to Mr Carl for this useful insight on this topic.

  2. Thanks for this great document Carl. I’m currently prepping to deploy FAS with MS Entra into our environment (replacing RSA SecureID) and am hoping to use the same FAS servers for both our production and non-prod farms. They share NetScalers with separate Gateways, and have separate StoreFront servers. In the section on creating the FAS rule, it says that “StoreFront servers use the rule named “default” unless they are configured to sue a different rule name. I’ve not been able to find anywhere how to configure StoreFront to use a specific rule… where is this done? At this time I’m assuming I need to have separate rules for each set of StoreFront/DDC/VDAs.

    Thanks in advance!

  3. I find your guides to be most helpful, and was wondering if you could make one for the following. Duo SAML with Netscaler (I’d expect most of this guide would be used, just with some variation for the DUO part.)

    The More tricky part I’m interested in is in DUO the app for protecting a Netscaler doesn’t offer assertion signing and encryption but looks like the generic one does.

  4. Do I need to create a second enterprise app in azure to be able to use Citrix cloud as my gateway to point to a on Prem VDAs and the FAS server.

    The cloud logon already redirects me to azure for authentication. (Must have been set up during my cloud onboarding or service integrations)

    Is that enough for FAS or do i need a FAS specific enterprise app?

    1. FAS is not dependent on SAML. You can deploy FAS without configuring SAML. StoreFront (or Citrix Cloud Workspace) uses FAS to Single Sign-on to VDAs. This happens after authentication, which could be SAML.

      1. Thanks,

        I don’t quite understand what you mean but I am reading to learn more about it now, thanks.

        To answer my own question: It appears you dont need to follow the below azure settings if you are using citrix cloud with the azure ad integration set. You just need to enable the FAS button in the cloud under “workpsace configuration” This is at least when you FAS and VDAs are onpremise. Ill test the Daas setup later. Thanks

  5. Hi Carl, again what a uselfull page! I have a question and hope you can point me in the right direction. We use ADC with passthrough authentication with Citrix Cloud and several resource locations. All works fine if the user that logs on to the ADC is also the user that logs on to the VDA. My question is, is it possible to logon to the ADC have the resources based on that user (desktops) and then use another logon in the VDA session. Corrently we get event error like “[S101] Identity Assertion Logon failed. Unrecognised Federated Authentication Service [id: 1]” ” ICA Connection request denied because the current user …. is not the owner of the Session…..

    We would like to use different users then the initial SAML based authentication that was used on the ADC login.

  6. After completing all the configs, SAML via ADC, FAS setup, enable Storefront store for FAS, GPO config, Certification configs.. still while launching the VDA, we are seeing “incorrect username or password” and struggling to find the reason and fix. No errors in VDA, FAS or in CA server. Can you suggest?

    1. In FAS Server > Event Viewer > Windows Log > Application, do you see events from FAS showing that the VDA requested the cert?

          1. Hello Carl,

            Enabled the kerberos logging on the VDA and found 3 events with event ID# # listed as below:

            2 of the events with Error Code: 0x19 KDC_ERR_PREAUTH_REQUIRED
            1 event with Error Code: 0x6 KDC_ERR_C_PRINCIPAL_UNKNOWN

          2. Hello Carl,

            We are still stuck on that issue.. is there anything further that you can suggest.

            Hello Carl,

            Enabled the kerberos logging on the VDA and found 3 events with event ID# # listed as below:

            2 of the events with Error Code: 0x19 KDC_ERR_PREAUTH_REQUIRED
            1 event with Error Code: 0x6 KDC_ERR_C_PRINCIPAL_UNKNOWN

            And it’s only single domain environment!

  7. Puzzling over what I’m doing wrong here – I’m sure its something stupid!

    Have a new store where we need to get SAML working direct on the store not through ADC (SAML works fine from ADC to other stores). I can test the store using domain logon and its fine, but as soon as i configure it to use SAML it seems to take me through SAML auth corrrectly then dumps me at the /storeAuth page not the /storeWeb, so I have just a blank page 🙁
    I tried running /storeauth/samltest but that is also just a blank page presented for /storeauth…

    Any thoughts welcome!

    1. My experience with native SAML has not been positive. I normally use NetScaler for SAML even if I’m not using NetScaler for ICA Proxy.

      1. sadly we just cannot use NetScaler in this instance due to other technical constraints 🙁
        I would use basic ldap but as the users are all using MS Edge we cannot get that to work without always prompting for the client unless we disable the protocol handler in web.config – which in turn disables ldap sson 🙁
        So i was hoping to use SAML to avoid that mess. 🙁

        1. Just an update – in case anyone else finds themselves in this situation.
          We found the root cause of the issue, when we examined the metadata from the storefront server, and compared to the ADFS setup, we could see and an error in the responder URL in ADFS. as soon as that was corrected it all started working properly 🙂

  8. I just wanted to drop you a thank you for your guides here.

    I’m taking charge of our current multi-tenant environment by migrating our customers from on-premise MFA to Microsoft Entra MFA and your guides have been highly valuable to me.

    Find that the official guidance provided by Microsoft and Citrix are a bit lack-luster at times but your guides fill all the gaps!

  9. Hi Carl,

    We use Azure Active Directory Domain Services in conjunction with citrix cloud. Looking to implement FAS but have a feeling it might not be possible, as AADDS doesn’t allow Enterprise CA. Effectively dont believe you can deploy the certificate templates.

    Have you come across this and can confirm this is a limitation? Or offer a potential work around?

    Many thanks

  10. Hello,

    Bowser everything works fine but in the workspace app its not working. I always get a second login prompt (not in the VDA but to the workspace app itself)
    I see this on my storefront
    A request was sent to service ‘Authentication Service’ that was detected as passing through a gateway. This service is configured with the gateways [9fd064a5-1b25-4180-9934-f050823b4d35], but none of these matched the request. Request details:

    I tried:
    – Force saml authentication in netscaler anabling
    – Removed username and password from store
    – Changed beacon to fake one for internal …

    But there is also a 2nd store with username/password wich should stayworking …
    Any idea please ?

    1. The Event Log entry usually has headers indicating the FQDN of the Gateway that the request went through. Make sure your StoreFront console > your store > Configure Remote Access has a matching Gateway object selected.

      1. It has. Doublechecked that multiple times…

        A request was sent to service ‘Authentication Service’ that was detected as passing through a gateway. This service is configured with the gateways [9fd064a5-1b25-4180-9934-f050823b4d35], but none of these matched the request. Request details:
        X-Citrix-Gateway: ctxportal.climaxxxx.xxx
        X-Citrix-Via: ctxportal.climaxxxx.xxx
        X-Citrix-Via-VIP: 10.12.65.25
        Remote Address: 10.12.65.29
        X-Forwarded-For: 84.199.xxx.xxx

        1. In StoreFront console > Manage Citrix Gateways, edit the Gateway. On the third page, is the VIP field filled in? Does it match the VIP shown above? You can also remove the VIP field.

  11. Wondering if you can provide some advice on the following:
    On premises Citrix infrastructure (Citrix Virtual Apps Standard)
    Windows Server 2016 OS (Published Server Desktops)
    Windows based Storefront server / Citrix ADC VPX (Netscaler)
    Windows 10 Pro 22H2 – Azure AD Joined workstations
    AD Connect – Password Hash Sync and SSO

    Currently Windows Hello (PIN/fingerprint) can SSO to workspace however users get prompted for a username and password for the virtual desktop, once provided SSO works within session to Windows applications.

    Desired configuration would allow Windows Hello to log onto workstations with SSO through to workspace and virtual desktop session and applications within the session.

    I believe we will require a FAS with ADCS, AD Connect changed to ‘pass thru’ auth, then will need Windows 2022 session hosts to allow pass thru FIDO2 SSO?
    Or is there another method to achieve this? Azure AD CBA /SAML?

    1. FAS, yes.

      FAS should work on VDAs with older versions of Windows. Windows 2022 not required.

      FIDO2 is separate from the VDA login using FAS. Once logged into a VDA, then apps can use FIDO2.

      CBA might be needed to get a PRT after logged into the VDA using FAS.

  12. We integrated SAML with Azure MFA using your guide. Works as expected. However, when we click on “Logoff” from the storefront page we get a page from https://login.microsoftonline.com/539c611a-8032-457b-b371-a99…. with this message:

    Sign in
    Sorry, but we’re having trouble signing you in.

    AADSTS7500525: There was an XML error in the SAML message at line 1, position 368. Verify that the XML content of the SAML messages conforms to the SAML protocol specifications.

    Troubleshooting details
    If you contact your administrator, send this info to them.
    Copy info to clipboard
    Request Id: 232d1d68-d9a6-49a6-a2d8-9e4a349d2700
    Correlation Id: c06c13f9-0ac0-4f01-b20f-2655cf1f0e6a
    Timestamp: 2023-08-24T20:43:51Z
    Message: AADSTS7500525: There was an XML error in the SAML message at line 1, position 368. Verify that the XML content of the SAML messages conforms to the SAML protocol specifications.
    Flag sign-in errors for review: Enable flagging
    If you plan on getting help for this problem, enable flagging and try to reproduce the error within 20 minutes. Flagged events make diagnostics available and are raised to admin attention.

    Been diggin around the google heap for a few weeks now and nothing points to a solution, nor does it sound like anyone else is experiencing this.

    1. Did you use metadata in the NetScaler configuration? Or did you configure it manually, including the single sign-out URL?

      1. All celestial bodies must be aligned today because after opening a ticket with Citrix support I got a call back in under an hour and the first level engineer poked around and did exactly that: switched from use metadata to configure everything manually. He also did some tweaks on our IdP in Azure. We’re good now. Thanks!

        1. Hi Eric,

          Any chance you may remember what exactly they have changed on Azure and Netscaler? I am getting exactly the same error.
          Thanks in advance!

    1. Thanks. I removed the link since it’s probably the old way of renewing it from the CLI. The newer way lets you Reauthorize from the FAS console.

  13. Hi Carl,

    I’m trying to setup MFA on StoreFront, i don not care for SSO to the VDA. Is there a way to setup functional MFA without FAS servers? our identity provider is PING

    1. StoreFront has native support for SAML. Or you can put a Citrix Gateway in front of StoreFront and let Citrix Gateway do the authentication.

      FAS is optional. Without FAS, users will be prompted to login at the VDA.

      1. thank you, I was able to get SAML working with the behavior you mentioned.

        Can we use Citrix Gateway for the Authentication only and bypass ICA traffic for internal users?

        1. Yes. In StoreFront console, when you add a Gateway, there’s a drop-down to select Authentication only.

  14. Hi Carl,

    I have an issue with non-persistant VDIs using PVS provisioning. Users are getting prompt to authenticate in VDI window. The FAS servers only log event 105 but fail to log event 204. All MCS VDIs are good (persistant), both event IDs are logged in FAS servers. GPO is configured to use 2 FAS servers in all VDIs, MCS and PVS.
    By the way, the credentials prompt only happens about 50% of the time in PVS VDIs. The MCS VDIs are 100% good. Any help is appreciate it. Thanks.

    Jose

    1. Is it a timing issue after a reboot? Maybe GPOs are not yet applied when users try to connect. Make sure the registry keys exist on the PVS Targets.

      1. It was GPO update. I created a scheduled task to update GPO on PVS target PCs every 10 mins or so. Just the computer configuration so any active users won’t see any messages prompt to logoff. Thank you!!!

  15. Hi Carl,
    Fantastic post as usual.

    I am trying to setup nFactor with EULA accept followed by LDAP (username / password) auth followed by SAML for Azure MFA but I’m new to nFactor and still trying to figure out how it goes together.

    Can I ask, with LDAP auth as the second factor will I still need Citrix FAS with
    Azure MFA ?

    Thank you.

    1. If the NetScaler is collecting the user’s password, then you can forward that password to StoreFront for later SSON to the VDA. Otherwise, you’d need FAS to SSON to the VDA.

      1. Does forwarding the user credentials to Storefront require any additional configuration or will that happen anyway.

        1. Depends on how many passwords you collect. You might need to configure AAA Attributes and a Traffic Policy to send the correct password field.

  16. In a multi domain config do you know what kind of trust is required. Domain or Forest. We have a 2-way selective auth domain trust but this is failing.

    [S104] Identity Assertion Logon failed. Failed to connect to Federated Authentication Service: UserCredentialService

    0x7 KDC_ERR_S_PRINCIPAL_UNKNOWN

  17. Hi Carl. Our FAS is due to be re-authorised. Can you give me some pointers on what I can expect when doing so? We have 2 FAS servers and 1 CA. FAS 1909+ and at step 23.

      1. Thanks but the instructions are confusing. The GUI has a reauthorize button but then lists powershell. What happens if you use the GUI t reauthorize? Thanks

        1. The button will generate a new request that you then approve on your CA. After renewal, you might have to edit the user rule to choose the new cert. Only use the PowerShell commands if you’re more comfortable with PowerShell.

          1. Hi Carl, thanks for your response. When you say user rule, I have checked that and all I can see is the option to change the template in the rules tab, not the certificate. I assume this what might need a re-config?

            Looking at the documentation here https://docs.citrix.com/en-us/xenapp-and-xendesktop/7-15-ltsr/secure/federated-authentication-service/fas-config-manage/fas-ca-configuration.html it states that “Note: Although you can also use the GUI to deauthorize and reauthorize FAS, that has the effect of resetting FAS configuration options”. So I guess the rule is the option that may need to be re-setup?

            Do I also need to place the server in maintenance mode before doing this? We have 2 FAS servers. Thanks

          2. I usually just reauthorize without doing any maintenance mode. It’s usually a quick process.

    1. After renewing the authorization, you might have to edit the user rule to select the new authorization certificate.

  18. Hi Carl,
    I was wondering if you know a way to enable SHA-256 when using SAML Authentication in StoreFront without any Netscaler/Gateway.

    By default StoreFront seems to use the SHA1 algorithm which is not much used anymore.

  19. hi,

    currently i’m trying using Azure AD for login into our on-prem ADC
    i’ve followed this guide and there’s a few question i’d like to ask

    for the shadow account :
    “When creating a shadow account in your Active Directory, the new UPN suffix is available in the drop-down list. Note that the pre-Windows 2000 logon name can’t conflict with any other user in the domain.
    The password for these Shadow accounts can be any random complex password since the Federated users never need the Shadow account’s password.”

    currently i’m using local domain : corporate.local
    and login Azure AD using email with suffix : corporate.com

    for my user :
    local domain : ilyas.ft@corporate.local
    azure ad : ilyas.ft@corporate.com

    how can i create shadow account with the same username “ilyas.ft” ?

    or can i use my “email” field, since my “email” field in AD already the same as Azure AD login? how do i do this?

    Thank you for your great guide
    i’ve deployed Citrix XenApp from scratch using your guide!

    1. In Active Directory Domains and Trusts, right-click the top-left node and click Properties. Add your .com suffix. Then go to Active Directory Users and Computers, edit the user, on the Account tab select the new suffix.

      Email attribute is not a security identifier so modifying that attribute won’t make any difference.

      1. OMG! thank you for your speed response!

        i’ve added the corporate.com and changed my ID to the new suffix
        but there’s a problem with storefront after login

        “Cannot complete your request”

        and event viewer shows :
        A CitrixAGBasic Login request has failed.
        Citrix.DeliveryServicesClients.Authentication.AG.AGAuthenticatorException, Citrix.DeliveryServicesClients.Authentication, Version=3.23.0.0, Culture=neutral, PublicKeyToken=null
        Authenticate encountered an exception.
        at Citrix.DeliveryServicesClients.Authentication.AG.AGAuthenticator.Authenticate(HttpRequestBase clientRequest, Boolean& passwordSupplied)
        at Citrix.Web.AuthControllers.Controllers.GatewayAuthController.Login()

        System.Net.WebException, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089
        The remote server returned an error: (403) Forbidden.
        Url: https://127.0.0.1/Citrix/PDLAuth/CitrixAGBasic/Authenticate
        ExceptionStatus: ProtocolError
        ResponseStatus: Forbidden
        at System.Net.HttpWebRequest.GetResponse()
        at Citrix.DeliveryServicesClients.Utilities.HttpHelpers.ReceiveResponse(HttpWebRequest req)
        at Citrix.DeliveryServicesClients.Authentication.TokenIssuingClient.RequestToken(String url, RequestToken requestToken, String primaryToken, String languages, CookieContainer cookieContainer, IEnumerable`1 acceptedResponseTypes, IDictionary`2 additionalHeaders)
        at Citrix.DeliveryServicesClients.Authentication.AG.AGAuthenticator.Authenticate(HttpRequestBase clientRequest, Boolean& passwordSupplied)

        also on FAS server i ran “get-fasusercertificate -address fasserver.company.local” and shows no certificate generated

        please help, thank you

        1. There should be another event in event viewer showing the actual issue.

          Is your Citrix Gateway configured to send the domain name? If so, remove the domain name from the Gateway config.
          Make sure your StoreFront is configured to accept the domain suffix at Manage Authentication Methods > Configure Trusted Domains.

          1. “There should be another event in event viewer showing the actual issue.”

            Unfortunately no, event viewer didn’t log any other error

            “Is your Citrix Gateway configured to send the domain name? If so, remove the domain name from the Gateway config.”

            sorry, how can i do this?

            “Make sure your StoreFront is configured to accept the domain suffix at Manage Authentication Methods > Configure Trusted Domains.”

            i’ve added the corporate.com to the trusted domains
            so currently it shows
            1. “CORPORATE” (this is the default one, i’m using pre-Windows 2000) domain name)
            2. corporate.com which the one Azure AD use

            is this correct?

            Thank you

          2. Edit your Citrix Gateway Virtual Server. Scroll down to the Policies section and click Session Policies. Right-click a policy and click Edit Profile. On the Published Applications tab, remove the SSON Domain.

          3. i re-followed your guide from the beginning, i missed the part to configure “Callback URL” in this part.

            “Configure StoreFront for SAML Citrix Gateway”
            On the Authentication Settings page, make sure you configure a Callback URL. It won’t work without it.

            currently i can login using Azure AD from Website and Citrix Workspace
            although authentication from Citrix Workspace is a little “worry-ing” because the authentication process (to Azure AD) needs more than 10 times until the Workspace is loaded with Desktop/Apps icons (it even shows “error” before finally loaded)

        2. Hi so I have completed all the steps and FAS does work for my test account but not for the rest of the users as their pre windows 2000 username is different to their logon name. When we change the logon and 2000 username to match, users can log on but unfortunately this breaks custom built in house apps. Any suggestions to allow users to use FAS with a pre windows 2000 username not matching UPN?

          1. Maybe you can configure the IdP to send pre windows 2000 username instead of UPN and then configure NetScaler to combine it with a UPN suffix and send it to StoreFront so it matches your local AD UPN?

  20. Hi Carl,

    Firstly – thank you so much for putting together this post, it has been incredibly helpful.

    I was wondering if you could advise on the following scenario I find myself in:

    I’ve setup MFA as above, but once I authenticate through the ADC, the storefront loads and I can see applications. However, when I try to launch the application (the ica file downloads fine) I get the following error: The published resource is not available currently. Contact your system administrator for further assistance.

    I’m not seeing anything in the event log, and was wondering if you’ve come across this before?

    1. StoreFront Server > Event Viewer > Applications and Services > Citrix Delivery Services usually has errors. Probably a FAS issue.

      1. Really appreciate you getting back to me! That’s where I’m checking, but nothing unfortunately. Can’t see any blocks on the firewall either. I can see my authentication being logged in Event Viewer > Applications > (Source) Citrix.Authentication.FederatedAuthenticationService

        I did run a packet trace for traffic between the ADC and the Sf and after initial login, no further traffic came through…

        1. You’re looking on the FAS server? Sometimes there are events in the FAS server event viewer.

          1. From FAS I can see the identity assertion logs and also see the user certificate with the PS command, but otherwise no errors. The FAS is know to the SF through GPO.

        2. check your FAS rules, i had the same issue and needed to amend the rules on the FAS server to resolve.

          1. I decided to use a blank app from Azure, instead of the Citrix Gallery app, which helped to resolve the issue. There were some other issues too, such as a port missing on the firewall, but got there in the end.

  21. What is the guidance if you decide to deploy x2 FAS in an environment that has an Offline root CA with two online Subordinate CA’s? The GPO would clearly have both FAS severs but how would you execute the FAS Admin Console – 1 FAS server per SubCA?

    1. That’s an option. Each FAS server can also use multiple CAs. If CA is on separate servers, then I would probably configure FAS to use multiple CAs.

  22. Thank you for your reply. Your last line i never thought about. We have now created a new base url and loadbalancer url and at one point we would change the workspace app to the new url. The Store name is identical.
    So, we could test everthing with the new Base URL and loadbalanced URL and when its working we can change the base URL to the current one and add the StoreFront servers to the current loadbalanced URL so the workspace apps keep working.
    And adding the new StoreFront servers tot the FAS Admin Console can be done without affecting the production environment as far as i know

    1. Correct.

      If Favorites/Subscriptions are enabled, then the farm names in Manage Delivery Controllers must be identical (case sensitive) so you can export/import the Subscriptions.

  23. Hi Carl, i have a question about FAS. We have build 4 new StoreFront servers in a new Server Group. This environment must replace the current StoreFront environment and here is FAS enabled and is working as supposed.
    To ‘migrate’ to the new SF environment what are the steps that i have to take? In my opion I only have to Enable FAS on the new SF Store, add the SF servers to FAS console and apply the FAS GPO to the SF servers. Am i right?

    1. Correct. Also make sure the Base URL and Store name are identical to the old so the Workspace apps continue to work.

  24. Hi Carl,
    We are using SAML Azure Id with ADCs redirection which works fine.
    citrix FAS is setup and i can see event ids 105 and 204 but when try to launch publish app/desktop i get ‘the username or password is incorrect’ message
    VDA logs following error:
    The domain controller rejected the client certificate of user , used for smart card logon. The following error was returned from the certificate validation process: A certification chain processed correctly, but one of the CA certificates is not trusted by the policy provider. event ID 8 (security-kerberos).
    any ideas?

    thx in advance.

    1. Did you build a new CA and using it for FAS? If so, you might have to run gpupdate on the domain controllers to the new CA cert is deployed.

      Otherwise, Microsoft docs has info on how to verify the CA certs that domain controllers will accept for smart card authentication.

  25. I have citrix fas installed and my virtual desktop using the Netscaler and azure working fine, my issue is with citrix workspace connecting to my virtual apps.

    I get the user name and password is incorrect. The workspace is logged on with my user and the only log i can find on all the environment is on the app server that says unknown username or bad password in the security logs

    1. Is Workspace connecting to a store that has FAS enabled? Do you see events on FAS server that a cert is issued for the user?

Leave a Reply to Robert Webb Cancel reply

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