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

    I have deployed another set of Citrix storefront and failed to run couple of commands:
    $auth = Get-STFAuthenticationService -StoreService $store
    Set-STFClaimsFactoryNames -AuthenticationService $auth -ClaimsFactoryName “FASClaimsFactory”
    Set-STFStoreLaunchOptions -StoreService $store -VdaLogonDataProvider “FASLogonDataProvider”

    Please advise where i am doing wrong

      1. it was my bad.I have used wrong Store path.

        Now, i am stuck when we are trying to authenticate using SAML authentication ,facing an issue “cannot complete your request” while accessing receiver web URL

        1. What do you see in StoreFront Server > Event Viewer > Applications and Services > Citrix Delivery Services?

          1. Log Name: Citrix Delivery Services
            Source: Citrix Receiver for Web
            Date: 2/3/2020 4:38:10 PM
            Event ID: 17
            Task Category: (3002)
            Level: Error
            Keywords: Classic
            User: N/A
            Computer: clt-citrix.sfntnoi.com
            Description:
            Failed to run discovery
            Citrix.Web.DeliveryServicesProxy.ConfigLoader.DiscoveryServiceException, ReceiverWebConfigLoader, Version=3.21.0.0, Culture=neutral, PublicKeyToken=null
            An error occurred while contacting the Discovery Service
            at Citrix.Web.DeliveryServicesProxy.ConfigLoader.Discovery.AppendConfigurationFromDiscoveryService(WebReceiverConfigSection section, DiscoveryClient client)
            at Citrix.Web.DeliveryServicesProxy.ConfigLoader.Discovery.RunDiscovery(WebReceiverConfigSection configSection, DiscoveryClient discoClient, EndpointsClient endpointsClient)
            at Citrix.Web.Proxy.Filters.DiscoveryComplete.OnAuthorization(AuthorizationContext filterContext)

            System.Net.WebException, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089
            The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel.
            Url: https://127.0.0.1/Citrix/test3/discovery
            ExceptionStatus: TrustFailure
            at System.Net.HttpWebRequest.GetResponse()
            at Citrix.DeliveryServicesClients.Utilities.HttpHelpers.ReceiveResponse(HttpWebRequest req)
            at Citrix.DeliveryServicesClients.Utilities.HttpHelpers.ReceiveResponse(String url, String token, HttpRequestParameters options, Object requestData, CookieContainer cookieContainer, Boolean overrideLoopback)
            at Citrix.DeliveryServicesClients.Discovery.RequestHandler.DiscoveryHttpRequestHandler.GetDocument(String url)
            at Citrix.DeliveryServicesClients.Discovery.DiscoveryClient.GetDocument(String url)
            at Citrix.Web.DeliveryServicesProxy.ConfigLoader.Discovery.AppendConfigurationFromDiscoveryService(WebReceiverConfigSection section, DiscoveryClient client)

            System.Security.Authentication.AuthenticationException, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089
            The remote certificate is invalid according to the validation procedure.
            at System.Net.Security.SslState.StartSendAuthResetSignal(ProtocolToken message, AsyncProtocolRequest asyncRequest, Exception exception)
            at System.Net.Security.SslState.CheckCompletionBeforeNextReceive(ProtocolToken message, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.ProcessReceivedBlob(Byte[] buffer, Int32 count, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.StartReceiveBlob(Byte[] buffer, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.CheckCompletionBeforeNextReceive(ProtocolToken message, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.ProcessReceivedBlob(Byte[] buffer, Int32 count, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.StartReceiveBlob(Byte[] buffer, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.CheckCompletionBeforeNextReceive(ProtocolToken message, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.ProcessReceivedBlob(Byte[] buffer, Int32 count, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.StartReceiveBlob(Byte[] buffer, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.CheckCompletionBeforeNextReceive(ProtocolToken message, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.ForceAuthentication(Boolean receiveFirst, Byte[] buffer, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.ProcessAuthentication(LazyAsyncResult lazyResult)
            at System.Threading.ExecutionContext.RunInternal(ExecutionContext executionContext, ContextCallback callback, Object state, Boolean preserveSyncCtx)
            at System.Threading.ExecutionContext.Run(ExecutionContext executionContext, ContextCallback callback, Object state, Boolean preserveSyncCtx)
            at System.Threading.ExecutionContext.Run(ExecutionContext executionContext, ContextCallback callback, Object state)
            at System.Net.TlsStream.ProcessAuthentication(LazyAsyncResult result)
            at System.Net.TlsStream.Write(Byte[] buffer, Int32 offset, Int32 size)
            at System.Net.ConnectStream.WriteHeaders(Boolean async)

            Event Xml:

            17
            2
            3002
            0x80000000000000

            772
            Citrix Delivery Services
            clt-citrix.sfntnoi.com

            Failed to run discovery
            Citrix.Web.DeliveryServicesProxy.ConfigLoader.DiscoveryServiceException, ReceiverWebConfigLoader, Version=3.21.0.0, Culture=neutral, PublicKeyToken=null
            An error occurred while contacting the Discovery Service
            at Citrix.Web.DeliveryServicesProxy.ConfigLoader.Discovery.AppendConfigurationFromDiscoveryService(WebReceiverConfigSection section, DiscoveryClient client)
            at Citrix.Web.DeliveryServicesProxy.ConfigLoader.Discovery.RunDiscovery(WebReceiverConfigSection configSection, DiscoveryClient discoClient, EndpointsClient endpointsClient)
            at Citrix.Web.Proxy.Filters.DiscoveryComplete.OnAuthorization(AuthorizationContext filterContext)

            System.Net.WebException, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089
            The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel.
            Url: https://127.0.0.1/Citrix/test3/discovery
            ExceptionStatus: TrustFailure
            at System.Net.HttpWebRequest.GetResponse()
            at Citrix.DeliveryServicesClients.Utilities.HttpHelpers.ReceiveResponse(HttpWebRequest req)
            at Citrix.DeliveryServicesClients.Utilities.HttpHelpers.ReceiveResponse(String url, String token, HttpRequestParameters options, Object requestData, CookieContainer cookieContainer, Boolean overrideLoopback)
            at Citrix.DeliveryServicesClients.Discovery.RequestHandler.DiscoveryHttpRequestHandler.GetDocument(String url)
            at Citrix.DeliveryServicesClients.Discovery.DiscoveryClient.GetDocument(String url)
            at Citrix.Web.DeliveryServicesProxy.ConfigLoader.Discovery.AppendConfigurationFromDiscoveryService(WebReceiverConfigSection section, DiscoveryClient client)

            System.Security.Authentication.AuthenticationException, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089
            The remote certificate is invalid according to the validation procedure.
            at System.Net.Security.SslState.StartSendAuthResetSignal(ProtocolToken message, AsyncProtocolRequest asyncRequest, Exception exception)
            at System.Net.Security.SslState.CheckCompletionBeforeNextReceive(ProtocolToken message, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.ProcessReceivedBlob(Byte[] buffer, Int32 count, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.StartReceiveBlob(Byte[] buffer, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.CheckCompletionBeforeNextReceive(ProtocolToken message, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.ProcessReceivedBlob(Byte[] buffer, Int32 count, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.StartReceiveBlob(Byte[] buffer, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.CheckCompletionBeforeNextReceive(ProtocolToken message, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.ProcessReceivedBlob(Byte[] buffer, Int32 count, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.StartReceiveBlob(Byte[] buffer, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.CheckCompletionBeforeNextReceive(ProtocolToken message, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.ForceAuthentication(Boolean receiveFirst, Byte[] buffer, AsyncProtocolRequest asyncRequest)
            at System.Net.Security.SslState.ProcessAuthentication(LazyAsyncResult lazyResult)
            at System.Threading.ExecutionContext.RunInternal(ExecutionContext executionContext, ContextCallback callback, Object state, Boolean preserveSyncCtx)
            at System.Threading.ExecutionContext.Run(ExecutionContext executionContext, ContextCallback callback, Object state, Boolean preserveSyncCtx)
            at System.Threading.ExecutionContext.Run(ExecutionContext executionContext, ContextCallback callback, Object state)
            at System.Net.TlsStream.ProcessAuthentication(LazyAsyncResult result)
            at System.Net.TlsStream.Write(Byte[] buffer, Int32 offset, Int32 size)
            at System.Net.ConnectStream.WriteHeaders(Boolean async)

          2. Go to StoreFront Console > Stores > your store > Manage Receiver for Web Sites > Configure > Advanced Settings and change the third line for Loopback from On to OnUsingHttp.

          3. I have updated Onusing http settings
            But i have server certificate from DC and using same in client , because of which changed the base url to fqdn of DC. On accessing receiver URL facing issue:Secure Connection Failed

            An error occurred during a connection to citrix-01.sfntnoi.com. PR_CONNECT_RESET_ERROR

          4. Hi carl,
            I am able to configure Xenapp in my enviornment with your great help .

            Now i am doing saml authenticaton it fails by showing “There was a failure with an mapped account”.

            Please ignore my last mails

  2. Hi Carl,

    We were able to configure Okta and Citrix StoreFront . SP Init flow works fine. But when trying to launch StoreFront app from Okta portal , it fails with Null pointer exception.

    If a Relay state id .is hard-coded then it works fine. But the relay-state would change for each login. So does not sound to be a right approach.

    Does Citrix StoreFront supports IDP init flow ?

  3. Hy Carl, you wrote “For security reasons, FAS should be its own server and not installed on a Delivery Controller.” Could you explain the security impact to me? Or did you mean domain controller?

    1. FAS server is a Certificate Registration Authority that could potentially create authentication certificates for anybody on the domain. Ideally the server should be owned by the Identity Management team or whatever team owns the Domain Controllers.

  4. Hi Carl

    I was trying to achieve SAML SSO with External IDP and Storefront.
    Using FAS, i have configured all the SAML related settings in IDP and Storefront.
    In the event Viewer i am receiving the error below
    The security token failed validation.
    System.IdentityModel.SignatureVerificationFailedException, System.IdentityModel, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089
    ID4037: The key needed to verify the signature could not be resolved from the following security key identifier ‘SecurityKeyIdentifier
    (
    IsReadOnly = False,
    Count = 3,
    Clause[0] = KeyNameIdentifierClause(KeyName = ‘AX8E08J2h7eO1uKbbuXXpbQH4eq7RSxT80px7d30iP8′),
    Clause[1] = X509RawDataKeyIdentifierClause(RawData = MIICqzCCAZMCBgFtcaMRtjANBgkqhkiG9w0BAQsFADAZMRcwFQYDVQQDDA5CUFNJTEYzNEZBLVNUQTAeFw0xOTA5MjcwNzMxMTVaFw0yOTA5MjcwNzMyNTVaMBkxFzAVBgNVBAMMDkJQU0lMRjM0RkEtU1RBMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAiYYoT8u1gdXKs+v7T6kuwfEVZBXfqkZNwV/LGO7PKUB0jiCIXA1PqpEQ37Qx3iemu6vHS3ahc/jcSBwjxMsT94rEGs30/I/jwY1xQxLpACfD6HIGf6d6I/IXvU6g4t6Ewxc6TCDA9n4K9TDmOhfujWLdlXdIftV5nMviePrTttinO4vfbIvgShC4UvzGWr8qEyvu2PfcrpqIpNyEMvev6y15Q3gWIiSpBrnCFHYdNkxn6eLA9+7PeVFNco891msH5Y6pj87Vn01SQeTdYATwNPXTxbEMLfRlf0xgoy4rZroWck7EiUDP/v4E//qTRzQDHDtQMQea0qwKddEKjQo61QIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQAEfyqqUZaOWeTu61oZ3TTxTcp5HX4vXDPL5vzYDBQr02NKDx9MM5LfoaJbeJfpvmwl9mehBKKCQwXHj252mD56iq4Abbe8yxCkYLRt3dq4d/pEf3XOX7rsZwl8YtnMncXOc9+0CP7qMmDRh+mB9YIuxnxN/FZixGYlbtJkbvsOZCMN+dJucY/MObfw0k/B/u/+r1KqNvfV5LH71d0Pp7OFnWdfCq…’. Ensure that the SecurityTokenResolver is populated with the required key.
    at System.IdentityModel.EnvelopedSignatureReader.ResolveSigningCredentials()
    at System.IdentityModel.EnvelopedSignatureReader.OnEndOfRootElement()
    at System.IdentityModel.EnvelopedSignatureReader.Read()
    at System.Xml.XmlReader.ReadEndElement()
    at System.IdentityModel.Tokens.Saml2SecurityTokenHandler.ReadAssertion(XmlReader reader)
    at System.IdentityModel.Tokens.Saml2SecurityTokenHandler.ReadToken(XmlReader reader)
    at System.IdentityModel.Tokens.SecurityTokenHandlerCollection.ReadToken(XmlReader reader)
    at Citrix.DeliveryServices.Authentication.Saml20.SamlExtensions.GetSecurityToken(String assertion, SecurityTokenHandlerCollection securityTokenHandlers)
    at Citrix.DeliveryServices.Authentication.Saml20.SamlManager.ProcessSamlResponse(String base64EncodedResponse, Boolean compressed)

    whereas While access Store Web URL, received the SAML request and after response ,we are getting “There was a failure with the mapped account”.
    <samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    Destination="http://Citrix/store1Auth/SamlForms/AssertionConsumerService
    ID=”ID_44b653d3-8931-46c9-87c0-4d63930c7115″
    InResponseTo=”id-b25fe854-29e8-41c3-8b6e-421afa82cff9″
    IssueInstant=”2019-11-22T07:40:58.053Z”
    Version=”2.0″
    >

    /KLxoIvhOxH/24QjqZw2AuM3qAnVA35EuPcpHK93mnI=

    TJ0GryJj51VcnUy0ruISw1YUVYmxxsZinnL67R/up8O0AnGMTaoNARePiN12+UsVMTDZp54L/VLYe6PbNboW3E00lk6O+j/yyuT1J/8NHkV+Ih5MPs8wQPc8MmKgI9W+tXaiPKnrmyBmGes6U3ExJUM94JSbuJAX/eWmziS/UaUFFwLMPSJzxW0jjhA1oM5j7H0xDBrZWdzQmovbGKfhi0ekLlmnLj+61AZtDzMGQD3RmISP5LaCgWLZ9plevRoVKC+Flsj9jl8X93EWIG4W1xSfVVP7QX/fQnJcP4jGhhVXaI+/AcWs+N+4/CMpgI1GsNAYAJ3fcNfreIoDdTAG3Q==

    AX8E08J2h7eO1uKbbuXXpbQH4eq7RSxT80px7d30iP8

    certificate

    iYYoT8u1gdXKs+v7T6kuwfEVZBXfqkZNwV/LGO7PKUB0jiCIXA1PqpEQ37Qx3iemu6vHS3ahc/jcSBwjxMsT94rEGs30/I/jwY1xQxLpACfD6HIGf6d6I/IXvU6g4t6Ewxc6TCDA9n4K9TDmOhfujWLdlXdIftV5nMviePrTttinO4vfbIvgShC4UvzGWr8qEyvu2PfcrpqIpNyEMvev6y15Q3gWIiSpBrnCFHYdNkxn6eLA9+7PeVFNco891msH5Y6pj87Vn01SQeTdYATwNPXTxbEMLfRlf0xgoy4rZroWck7EiUDP/v4E//qTRzQDHDtQMQea0qwKddEKjQo61Q==
    AQAB

    entity ID

    Kt2SPE4kFqmFQvwb2n3kwOHLbOvHhvFqVczeCVJK4t4=

    MUJ2As3x56x7h5tp9Mg479DemZspr0dB1Zth7eua93qHsqoGOWfEXfjzjJ6euHc6Q7R5HVb2Fncb2bPBVjnfdemA+KNwhyAnXkL67o0H8ttErZqRq+HjjTQNB6u4miK1VjrnRKYTF1SmZZSgXou9LFnrwoNPCOIVxSvztPF00SvpHW2xkNRohkNeavtR0f+016fmgejdb+IjVvuJ9kwT7zr114unYs4iuVu4h2pw8JZllMNO9/UBNkB6zF6pkMe/5xkVPE5BICKRWIfOk422H+bYU3HEFxdBqCrZ4EfHz93BxobfcVVUYyKo0IGLEj7t3z9Av/sSp8MeaaIZXojaOQ==

    AX8E08J2h7eO1uKbbuXXpbQH4eq7RSxT80px7d30iP8

    certificate

    iYYoT8u1gdXKs+v7T6kuwfEVZBXfqkZNwV/LGO7PKUB0jiCIXA1PqpEQ37Qx3iemu6vHS3ahc/jcSBwjxMsT94rEGs30/I/jwY1xQxLpACfD6HIGf6d6I/IXvU6g4t6Ewxc6TCDA9n4K9TDmOhfujWLdlXdIftV5nMviePrTttinO4vfbIvgShC4UvzGWr8qEyvu2PfcrpqIpNyEMvev6y15Q3gWIiSpBrnCFHYdNkxn6eLA9+7PeVFNco891msH5Y6pj87Vn01SQeTdYATwNPXTxbEMLfRlf0xgoy4rZroWck7EiUDP/v4E//qTRzQDHDtQMQea0qwKddEKjQo61Q==
    AQAB

    administrator@sfntnoi.com

    http://hostname/Citrix/store1Auth

    urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified

    I have checked the query above ,one of the person has same issue but i am sure my IDP certificate is correct.
    I tried to upload in .cer and.crt format.
    Can you please help me how can i resolve this issue?

    1. I’ve had difficulty getting some SAML IdPs to work directly with StoreFront. It always works with NetScaler.

  5. Hi Carl,
    Love your site, thanks for always sharing great content over the years.
    Woking with OKTA as the IDP and on prem NS and Citrix.
    Do you know if its possible to create deep links from Okta that will open a Citrix application without opening the Storefront user interface ?
    many thanks Chris

  6. nice article.

    will this work with a multi-tenant environment? i.e. multiple customers with different ADFS servers?
    Or will mixing authentication methods in a multi-tenant environment work? i.e. one way trust with one customer, FAS with SAML ADFS for another?

    1. You can certainly have multiple SAML IdPs. However, you must have local accounts with UPNs that match the email addresses returned by each IdP. This means you might have to configure several UPN suffixes in your local forest. Authorization to Citrix resources is based on your local accounts, not the federated IdPs.

  7. Hi Carl,

    Thanks for your work, i follow all step and configured FAS with OKTA.
    But the receiver web has a very short timeout (message : user can’t logon with sart card if refresh after timeout ) and user must open new session, i don’t understand because on receiver for web it’s 20min

    Thanks for your help

  8. I have configures Azure AD (SAML) on the Netscaler. This works fine as it authenticates and loads the applications and desktops. I have also configured FAS server and have it working on the StoreFront servers. When I launch applications via Netscaler I have to provide credentials instead of SSO taking over.
    When running the Script
    ($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”)

    Launching the applications and desktops stops working. I get the typical “Cannot start desktop”. In logs on StoreFront it shows XML error 28 and Access Denied.

    Is this because I need to setup ADFS and SAML for StoreFront authentication for this to work as seamlessly as I wanted? Or am I missing something else?

    1. It usually means the GPO containing the FAS server addresses is not applied to the StoreFront servers and VDAs.

    1. StoreFront Event Viewer should indicate if a FAS server could not generate a certificate for the user. StoreFront should then fail over to a different FAS server.

      Watch disk space on the CA servers if the CA server is logging all new certificates created by the FAS servers.

      Monitor the expiration date of the FAS Authorization certificate.

      https://support.citrix.com/article/CTX225721 has some FAS scalability information.

  9. Has anyone used the Import-STFSamlSigningCertificate PS to import the SAML signing cert. We are trying to use it in a couple ways but after import the site breaks complaining that it cannot find the private key, though it appears fine in the Computer’s Citrix Directory Services cert store. Even if you export Citrix’s self signed cert and reimport it breaks…

  10. Hi Carl,

    Thank you very much for Great write up. I have quick question.
    We are trying to configure F5 WebTop with APM (SMAL) on Azure MFA direct connection with XenDesktop Delivery controller (we wanted to remove Citrix Storefront layer) but SSO is not working
    Can we make use of FAS to carry this SSO to make this work or do you have any option?

    1. FAS performs SSO when the user’s password is not available, which is typical for SAML. However, FAS requires Citrix StoreFront.

  11. I have a domain trust between multiple domains. Certificates are being issued but when logging into a VDA I get two different error messages depending on the domain the user is in.

    A certification chain processed correctly, but one of the CA certificates is not trusted by the policy provider.

    and

    A certificate chain could not be built to a trusted root authority.

    When checking the user certificate that has been issued on the VDA using certutil -urlfetch -verify certname.cer there are no errors.

    The CA issuing the CitrixSmartCardLogon certificates is in domainA, the FAS server is also here.

    The intermediate and root certificates are installed on the VDA.

    The users from domain B and C have been added to the FAS rule ACL and the servers have been added to the other domains Windows Authorization Access Group

  12. Hi Carl

    Many thanks for another superb write up. I’m working on a Netscaler/Okta setup with Okta being the IDP. Citrix FAS server has been setup. All AD user accounts are all configured for the external FQDN (UPN) that’s going to be used for the Okta configuration. Will shadow AD user accounts still need to be created for all users that will be accessing via Okta ? .

    Many Thanks

    1. You need a local AD account with UPN that matches the Name ID (or other attribute) that Okta sends back. If you don’t have a matching local AD account, then you’ll need to create them. You then authorize Citrix resources to the local AD accounts.

      1. Carl, thanks for the clarification. I initially thought shadow accounts were a pre-req but upon checking all the user AD accounts found that the upn attribute were already configured as domain.com.

        Many thanks

      2. Carl,

        Thanks for all your help and the guide .. deployment went really smoothly and no need to create the shadow accounts.

  13. Hi Carl,
    Do we need to have SAML plugin installed on Storefront in-case we use ADFS and FAS? currently Netscaler is doing authencation part. we have a setup which has ADFS, Citrix 7.15, FAS with multiple Claims provider and Netscaler is the relaying party trust for us.
    Kindly Help.

    Regards
    Reehan

  14. Hi Carl,
    Great site. I’ve got a quick question. I installed FAS 1906 and along with Federated Authentication Service, it comes with a New Beta Admin console. I had added a second CA server for HA/LB via PowerShell and its working well.. The Beta console allows you to see both CA’s where as original Console showed empty config under rules when you added second CA via PowerShell. When i run Powershell command get-FasMsCertificateAuthority i see that second CA is Default. Is there a way to change the default MS-CA authority?
    Thanks
    John

  15. Hi, First of all, thank you for a great article. How can I get SSO inside the Citrix Session? Example: Open Outlook inside the Windows Desktop with SSO to Azure tenant

    1. If your SSO option supports Kerberos or NTLM, then it should just work. Is ADFS or Azure Active Directory Seamless Single Sign-On configured?

      1. We have setup a multi tenant solution that works great using URL Responder Policy and the SAML Reply URL to chose the correct SAML Policy in Netscaler Gateway.
        We haven’t setup Azure AD Seamless SSO since it requires AD Connect, which isn’t multi tenant friendly. Do you have any tips?

        1. When your customers log into the VDA, they are authenticating using your local Active Directory credentials and not their original credentials.

          Do your customers authenticate to Outlook using their original credentials? Or do they use your credentials? If the former, then there is no SSO because the VDA credentials are different than the original credentials.

          1. The customers have Office 365 (Exchange in 365), but the default installation of Office is using Modern Authentication. Is it possible to use the certificate/smart-card as SSO inside the VDA/windows desktop to pass on to Office, Edge etc?

  16. Hi Carl,

    I just configured SAML on Netscaler, getting the following error, could you please check and advise

    “Invalid time in the Message sent by the Peer. Please ensure time synchronization between Netscaler and the Peer”

    Thanks & Regards
    Aditya Kumar Pagadala

    1. SSH to your NetScaler. Run “shell”. Run “date”. Is it correct? If not, make sure NTP is configured. You can also run “ntpdate” to update the time from NTP.

      1. Hi Carl,

        This is what the date command shows
        Tue Jul 2 01:22:13 EST 2019

        Configured North America NTP server IP’s (2) on NetScaler and synchronized.

        Do I need to check with Azure AD team about their time zone settings ?

        Please advise.

        Thanks & Regards
        Aditya

        1. Run “ntpdate” to update your time from an NTP server. It it complains about socket in use, then disable NTP sync, run “ntpdate”, then re-enable NTP sync.

      2. Hi Carl,

        After setting proper date and time, we were able to login, I am able to see the desktop but when i click on it cannot start desktop error getting, any help please

          1. Error was cannot start desktop…its fixed after setting broker value to true.

            Thanks alot Carl for your help always…

  17. Hi. carl.

    I have configured the NetScaler Gateway for SSLVPN only.
    And I want to implement SSO functionality for the customer’s Groupware website.
    Is it possible to SSO a third party website rather than a web page provided by Citrix?

    Thank you ^^

    1. What kind of authentication? If SAML, then your NetScaler would need to be an IdP for the website. NetScaler can certainly generate SAML tokens and send them to any SAML-enabled website.

  18. I have SAML with FAS working perfectly, thanks to this article and a few others. Now, I’m moving to nFactor, I have nFactor rolling through multiple factors and the getting MFA from Azure. The issue I have is that on a non-domina joined workstation or mobile device the ${HTTP.REQ.USER.NAME} does not carry through to the SAML assertion. any thoughts?

  19. Hi, Carl… We’re having an issue getting SAML on SF to work correctly with ADFS. We get the assertion and application enumeration, however the launch fails. The environment has users in a separate forest with a two-way selective authentication trust between them. We setup a test DDC in the users domain to see what it should look like and the issue appears to be with the LDAP user search. For some reason SF/DDC appears to perform the LDAP search against its own root domain instead of the users forest/domain (so it gets a “null” return). FYI.. everything works fine if un/pwd is used so it appears that the backend process has another dependency when SAML is used. Any insight would be appreciated. Thank you

  20. Is it a good idea to install 2 FAS dedicated subordinated Enterprise CAs to have CA Failover? Is this too much hazzle for a midsized environment and maybe easier to use the CA which is in place as it is and have a good DR management (backup/restore) and live with the Single point of failure for this component ? Is it worth the effort and in relation to the benefit ?

    PS: in case of double post please delete (there was an error before after posting the comment)

    1. You might have to test what happens when the CA is not available and the user’s certificate has expired (7 days default I think) or a new user.

  21. Dear Carl,

    Citrix FAS or SAML authentication will support multi domain forest (without trust between domains ) is it possible to configure SSO?

    1. FAS will generate certificates based on the user’s userPrincipalName that the CA server can get from Active Directory.

      Then the VDA will send the certificate to a domain controller, which matches the UPN in the certificate with an Active Directory account.

      As long as your CA and Domain Controllers used by the VDA can reach every account, then it might work.

  22. Dear Carl,
    Your blog is amazing and I succeeded to apply SAML, storefront and FAS. But I have a problem with Citrix Password Manager which prompt to enter my password. Do you know if this product is compatible with this method ? Thank your in advance.

  23. Good morning Carl. does citrix support single sign on for multi forest domain (external domain without trust) environment? ex: domain ABC and Domin ZXY both are different domains they dont have trust between the domains. user are logging their pc using ZXY domain and accessing xenapp application from website from ABC.com. in this scenario is it possible to configure sso for both the domains without any trust using FAS /ADFS ?

  24. Hi Carl,
    I have configured Azure MFA with Citrix FAS server and seems to be working in our test environment.
    Now I am planning to move to prod and I have a question regarding GSLB setup.
    Could you give me some pointers on what is the proper way to configure it with GSLB.
    so far the only way I am thinking of is to:
    1. assign DNS names to Access Gateway VIPs on each datacentre e.g.

    workspace-dc1.company.com
    workspace-dc2.company.com

    2 . create 2 Azure apps
    using following reply URLs
    https://workspace-dc1.company.com/cgi/samlauth
    https://workspace-dc1.company.com/cgi/samlauth

    is there any other way to configure it.

    Regards,
    Vadim

    1. With GSLB, your typical goal is one DNS name, not two.

      If both Gateways are configured with the same IdP certificate, then both Gateways can accept the same SAML Assertions.

  25. Hi Carl, thank you very much for the grear article! This really helped us getting started.

    One question: we experience very slow app launch, where the app icon shows a spinning wheel for about 15+ seconds after clicking it (probably during authentication). Then the progress window appears and the actual app launch starts.

    We can see on the PKI CA that the certificate gets issued after 2-3 seconds, so it is unclear what happens after that time. Is that behaviour normal?

    After having received a certificate for the first app, launching another app only takes 2-3 seconds before the progress bar appears.

    Is that perhaps normal or any ideas what could cause this?

    1. Is anyone able to confirm that 15+ seconds for authentication are normal for FAS please?

      Otherwise we would try to resolve this with our supplier / Citrix support. User experience is very bad with 15+ seconds where nothing happens.

      1. Where in the process is this delay occurring? Is the delay when StoreFront creates the .ica file? Or is the delay after Receiver connects to the VDA machine and uses the certificate to authenticate with Active Directory? If the latter, are the CRLs reachable by the VDA machine?

        1. We have a setup with two loadbalanced StoreFront server and two FAS server (no NetScaler). ADFS authentication from StoreFront is super fast. The delay is directly when starting an application from StoreFront Portal probably during connection / authentication to the VDA including certificate retrieval. We can see that the certificate gets issued within the first 2-3 seconds. CRL check should work with all servers being on the same network (verified from StoreFront and FAS servers).

  26. Hello Carl, 

    I have a Virtual Apps and Desktops deployment (version 7 1811) which is published via Citrix ADC. All Citrix servers are running Windows Server 2019. Users are authenticated via AD latest domain functional level. I need to use an external LDAP server to authenticate users to the existing Virtual Apps and Desktops deployment. The external LDAP server has different user identities. Besides using Citrix Federated Authentication service with Windows Federation services, is there any other way to accomplish this via Citrix ADC (e.g. AAA policies) ?

    1. You could ask the users to login twice, once at ADC, and again at VDA.

      To login to a VDA, the user must have an account in the same domain (or trusted domain) as the VDA. Usually there’s a way to translate a SAML attribute to the username in the local domain, which then lets you use FAS to SSON to the VDA.

  27. Hi Carl, thanks for all the great content. We have had a Netscaler to Storefront / SAML to FAS authentication system setup for a couple years now, works great. OpenID is now our standard and we’re hoping to keep everything the same and just swap out the SAML authentication provider for an OpenID one. Do you have any documentation, thoughts, notes to consider as we attempt this?

    Thanks again

      1. Not in particular, that part is probably pretty easy. Just confirming that this process can basically work the same way but through openid instead of SAML. And to that end, all we have to do is change the auth provider in the NetScaler to openid and we are done. I will test later and confirm, but was wondering if you had any experience with that.

  28. Hi Carl,
    Do you know there is any way to configure SAML authentication with Azure AD for a gateway virtual server that it’s only internal (URL not accessible over the internet).

    The tutorial at https://docs.microsoft.com/en-us/azure/active-directory/saas-apps/citrix-netscaler-tutorial states that the url SHOULD be accessible from the internet to Azure AD can post the token but was wondering if there is any alternative.

    From the tutorial:
    “In order to get SSO working, these URLs should be accessible from public sites. You need to enable the firewall or other security settings on Netscaler side to enble Azure AD to post the token on the configured ACS URL”

    1. The user’s browser needs to be able to connect to both the IdP and the SP. Internal Browsers should be able to access internal URLs. The IdP and SP don’t normally communicate directly with each other.

  29. Hi Carl,
    I completed the setup of our Citrix Federation for the VDA SSO according to your article and works great, Thanks!

    But, i noticed that our Enterprise CA has lots of “Failed Requests”. Possibly one failed request for each computer on the domain with the request status code of “The permission on the certificate template does not allow the current user to enroll for this type of certificate” and this is for the certificate template “Citrix_RegistrationAuthority_ManualAuthorization”.

    I double checked the certificate template for “Citrix_RegistrationAuthority_ManualAuthorization” and confirm that Domain computers group was removed and that only only the FAS server has enroll enabled as per article.

    Any ideas? I am using 7.15 CU3.

  30. Hi Carl,
    just wondering if you can help here.
    we have some certificate issues on our test environment after switching to FAS.
    I tried pre-generate user certificates directly from the FAS server bypassing Storefront , using “new-fasusercertificate” cmdlet from the Citrix article below
    https://docs.citrix.com/en-us/xenapp-and-xendesktop/7-15-ltsr/secure/federated-authentication-service/fas-config-manage/fas-ca-configuration.html
    however we still have certificate failures on the issuing CA

    event 22 Certification authority
    Active Directory Certificate Services could not process request 11739 due to an error: A certification chain processed correctly, but one of the CA certificates is not trusted by the policy provider. 0x800b0112 (-2146762478 CERT_E_UNTRUSTEDCA). The request was for CN=CORP\testuser01. Additional information: Error Verifying Request Signature or Signing Certificate
    there are no certificates listed when you check with
    Get-FasUserCertificate -address sy4ctxfas01.corp.xxx.ad

    Our infrastructure guys did not like the idea of pushing certificate templates from the FAS server so they have copied template files from the FAS server “C:\Program Files\Citrix\Federated Authentication Service\CertificateTemplates” and published them manually. Not sure if that is somehow related and any certificate template reconfiguration is required. (e.g. compatibility , request handling, issuance requirement etc)

    any pointers on this one?

    Kind regards,
    Vadim

      1. Thank you, Carl.
        Looking into cert chain we found 2 outdated Issuing CA certificates in ntauth container.
        Currently looking into all certificates issued with these CA certificates to replace them and then delete outdated issuing CA certs. Hopefully that’s the root cause and not just another hoop to jump through.

        Kind regards,
        Vadim

        1. Issue has been fixed after removing expired CA certificates from NTauth container.
          There was a bit of delay though. We have removed old certs from AD in 3 PM and FAS was able to generate certificates but logon to VDAs were failing with “the user name or password is incorrect” or “the request is not supported” till 10 PM. Domain controllers were rejecting client certificates with Kerberos-Key-Distribution-Center event IDs 19 and 21.
          Next day all Domain Controllers were OK and started accepting client certificates logons.

  31. Hi Carl, Great article but I could not figure out it the FAS is required when I want use Azure MFA on the netscaler gateway.
    The Citrix ariclte below doesn’t mention the FAS.

    https://www.citrix.com/content/dam/citrix/en_us/documents/products-solutions/integrating-netscaler-with-microsoft-azure-active-directory.pdf

    I have not tested it myself. You need the FAS to pass credentials from netscaler gateway to the storefront if I understand correctly from the article/replies here. No other option?

    No really related to this post but we have the situation where we want to migrate users in batches to MFA.
    Must admit my knowledge in netscaler I limited but hope to improve on it fast:
    What would be the best approach according to you without impacting or requiring a lot of interaction from the user. Currenly NS gateway is LDAPS only. We tried NFACTOR but you need the workspace app to work on older receivers this does’ work.
    Any insight on this and above question would be great.
    Tnx already for posting such great artilcles.

    1. FAS has nothing to do with Gateway or StoreFront. FAS is only needed to perform Single Sign-on the the VDA when your SAML IdP does not provide the user’s password. StoreFront and Gateway should work with fine with SAML without FAS. But without FAS, launching icons will cause the VDA to prompt the user to enter a password.

      If you want a single FQDN, then nFactor is how you do it. Otherwise, you could create a separate Gateway with different authentication and instruct migrated users to use the new Gateway.

      1. I have implemented SAML via azure MFA . Does this mean I do not need a FAS server for SSO since my password is known?

        1. With SAML, user enters password, but the password is transmitted to the SAML IdP, not your NetScaler. After SAML IdP is done, it sends to your NetScaler a SAML Assertion that usually only contains the user’s email address and does not normally contain the user’s password. In other words, NetScaler does not have access to the user’s password.

  32. Hi Carl,

    We have newly built FAS in environment. While verifying the configuration, I found that for “Get-FasAuthorizationCerticate -address fas.domain.com” status is showing “MaintenanceDue”. Please let us know how it can be resolved and make sure everything is OK.

  33. Hi Carl,

    Do you know if it’s possible to do this same setup (inbound SAML from an IdP) with the cloud based Citrix Gateway Service acting as a SAML SP? I looked through all the online documentation I could find, but there is no mention of supporting this use case.

    Thank!

  34. Hi Carl,

    I have a FAS environment setup recently. While I was going through my FAS configuration I found that for “Get-FasAuthorizationCerticate -address fas.domain.com” status is showing “MaintenanceDue”. I have no clue what it is please let me know how it can be brought back to status “OK”

      1. Hi Carl,

        The setup was built very recently just couple of weeks ago.Do I still need to renew the Authorization certificate and take FAS out. It states Maintenance Due but still FAS is able to generate certificates.

        1. From CTP George Spiers: “That may mean that the FAS server originally enrolled for a certificate using the ManualAuthorization certificate template, but auto-enrollment using the Authorization certificate template failed. Check ADCS for failed requests”

  35. Hi Carl, this is a very interesting topic and great article !
    We are planning to use our ADC as saml idp (not sp) for our web services, office 365 and other external partners/services. is there any reason or cons why you don’t describe this possibility here ?
    We believe ADC to be the best choice as an saml idp and as a replacement to our heavy adfs infrastructure. (More options, scalabitliy, security…)
    Thanks a lot

    1. ADC as saml idp is commonly used in Citrix XenMobile and ShareFile deployments.

      I think other IdPs are easier to configure, especially for multiple SPs authenticating against one IdP. Common IdPs include Okta, Azure AD, SecureAuth, etc.

      1. Thanks for your reply. In case of ADC as IDP, i understand that FAS is not mandatory, as Netscaler is able to send the password for SSO to VDA session. Is that right ?

        1. I assume Citrix Gateway is still the SP even though it might be using another Citrix ADC object as the IdP. I’m not sure if the Gateway would have access to the user’s password.

  36. Hi Carl,

    Really dumb question I expect…….I see above someone says “I have SAML setup to ADFS just internally”. I would like to set this (again just internally). Do I have to set up a “Citrix” FAS server, or will SAML talk directly to our ADFS server?

    Sonia.

    1. SAML and FAS are two different things. After SAML happens, the user still needs to be authenticated to the VDA. If SAML does not provide the user’s password to StoreFront, then the user will see another authentication prompt on the VDA. FAS eliminates that second prompt.

      1. I wasn’t able to get logged into StoreFront without FAS. Now that FAS is configured, I can launch the published applications but I’m getting the Windows prompt. Can you point me in the right area to look to fix this. This article has been the most helpful for setting up FAS

        1. Usually either the group policy with FAS servers is not applied to the VDAs, or there’s a problem with the Domain Controller certificates. Event Viewer on the VDA might help. For Kerberos issues, you might have to enable Kerberos logging.

    1. If the SAML IdP does not send back the user’s password, and if you want SSON to the VDA, then yes you need FAS. Otherwise, users will be prompted to logon again at the VDA.

  37. Hello Carl,

    Thanks for the detailed article.I am using the latest version of netscaler GW (NetScaler 12.0) Following through your steps from Citrix ADC SAML Configuration, while creating the a new Authentication SAML server i do not see any option to use SAML IDP Metadata URL. Can you confirm if this is available in NS 12 or should we use the manual options. Currently i am testing this with manual options and keep getting “cannot complete request” after signing. Any suggestions would be appreciated.

    Regards,
    DM

    1. “Cannot Complete Request” usually comes from StoreFront, which means your SAML is working. Check StoreFront Server > Event Viewer > Applications and Services > Citrix Delivery Services.

  38. Hi Carl! I have SAML setup to ADFS just internally. The funny thing is it works fine to my PVS machines, but any standalone server it fails with “the user name or password is incorrect”. Citrix says it is a MS issue with the saml auth and so far MS hasn’t come up with anything, but it is a slow moving case. Do you have any ideas what to look for. Thanks!

    1. We are having the same thing Trvis. It is infuriating! We have several machines it works on and several it doesn’t no rhyme or reason to it. Two servers can be built at the same time, they may both work, 1 work or none works! troubleshooting the issue it appears to be a kerb error but just cant work it out.

    2. Just to clarify on my question. I have FAS setup, and according to some of your comments, FAS is what sends the authentication to the VDA. So, if I am getting “the user name or password is incorrect”, does that mean that FAS is not working correctly? Cause authentication to the storefront via SAML is working.

      1. Is StoreFront configured to use FAS?

        On the VDA, do you see any errors in Event Viewer, especially for Kerberos?

        Is the FAS group policy applied to both StoreFront and VDAs?

        1. Yes, storefront is configured to use FAS and the FAS GP is applied to all VDA’s and storefront. We do get some Kerberos errors when doing a wireshark capture on the VDA, but the event viewer doesn’t seem to show anything specific. It only works on our PVS servers for some reason, but I can’t find anything different between those.

    3. Found a solution to my problem. Per a MS security recommendation, we had enabled LSASS.exe auditing. This broke the authentication process. So enabling the auditing of LSA or enabling LSA protection will break this. After disabling, all is well.

      1. Just came across a similar issue with an updated version of the Bitdefender AV client. Their new ‘Advanced Anti-Exploit’ setting for “LSASS memory access from unknown process” defaults to “Block Process” which breaks the FAS login. Setting this to “Report Only” is the workaround we have for this so far.

        The event log reports the error (ID 5) “An error occurred while retrieving a digital certificate from the inserted smart card. Provider DLL failed to initialize correctly”

  39. Hi Carl. Are you familiar with any incompatibilities with Azure AD idp/FAS/Hybrid Join with AAD Conditional Access? I have a CA policy requiring Hybrid AAD Joined devices but the Win10/Server 2016 machines will not properly Hybrid Join. MS is looking at the issue but I figured I would ask here too. Thanks in advance.

      1. Yes. As well as my Server 2016 RDS VDAs. Azure AD shows that they are joined, but dsregcmd /status /debug tells a different story.

  40. Carl. Great work. My AAD/FAS/NSG 11.1 has been working fine for some time. All of a sudden, I am in an endless loop between: login.microsoftonline.com, /cgi/samauth, /cgi/setclient?wica, storeURL, /vpn/index.html. These 4 keep looping. FAS is issuing certificates. Any tips? Thanks.

    1. I assume you meant /cgi/samlauth instead of /cgi/samauth

      So StoreFront is logging you off immediately? Any errors in the StoreFront Event Log?

      FAS doesn’t occur until after the user clicks an icon.

      1. Nothing. I created a duplicate VIP with the same settings and it works. Odd. Not sure if it’s related, but now that I am able to login to NSG, I cannot access any applications. The ica launches and sits there for ever. It works from SF directly. I do not see any ica connections on the VDA while waiting for the desktop to launch. When it rains, it pours.

  41. Carl, Netscaler SAML policy have different fields and field names. It’s hard to understand how to configure it.

  42. Hi Carl,
    I need some expert Advice on User Access.
    Environment:- Citrix XD7.15 on Azure Cloud not using Citrix cloud services.
    Stand Alone AD server (xyz.com)in Azure not using azure ad services.
    Two types of user:-
    1. User account exist in xyz.com
    2. User account doesn’t exist in xyz.com (abc.com)
    There is no trust between two domains.
    There is no ADFS services in xyz.com

    We need two factor authentication for both users.
    we are proposing Azure MFA for xyz.com
    what we need for user from abc.com to get two factor authentication and get access to citrix vdi.
    will Citrix FAS will do the needful or we need third part product for abc.com.
    can azure mfa and cfas working in coordination.

    1. For the non-trusted domain, you need SAML to offload authentication to another service, and then FAS to perform SSON after authentication is complete. Don’t forget you’ll need shadow accounts in the local domain for the untrusted users.

  43. Hi Carl,

    I am getting S104 error . I am getting “the request is not supported” in VDA.I am pasting the error message below. Do you have any thoughts?.

    [S104] Identity Assertion Logon failed. Failed to connect to Federated Authentication Service: UserCredentialService [Address:XXXX.XXX>XX][Index: 0] [Error: Access Denied
    Server stack trace:
    at System.ServiceModel.Channels.ServiceChannel.HandleReply(ProxyOperationRuntime operation, ProxyRpc& rpc)
    at System.ServiceModel.Channels.ServiceChannel.Call(String action, Boolean oneway, ProxyOperationRuntime operation, Object[] ins, Object[] outs, TimeSpan timeout)
    at System.ServiceModel.Channels.ServiceChannelProxy.InvokeService(IMethodCallMessage methodCall, ProxyOperationRuntime operation)
    at System.ServiceModel.Channels.ServiceChannelProxy.Invoke(IMessage message)

    Exception rethrown at [0]:
    at System.Runtime.Remoting.Proxies.RealProxy.HandleReturnMessage(IMessage reqMsg, IMessage retMsg)
    at System.Runtime.Remoting.Proxies.RealProxy.PrivateInvoke(MessageData& msgData, Int32 type)
    at Citrix.Authentication.UserCredentialServices.IConvertCredentials.CheckAvailableCredentials(String cookie, String& upn, String& userSid)
    at Citrix.Authentication.IdentityAssertion.HdxCredentialSelector.c__DisplayClass8.b__7()]

    1. The FAS server has a User Rules configuration. One of the fields is permitted VDAs. Was that changed from the default of Domain Computers?

  44. Carl,

    Do you know of a way to see when the validity period of the FAS RA cert ends? I don’t see it in any of the PS commands.

    1. It’s under HKEY_USERS\S-1-5-20\SOFTWARE\Citrix\TrustFabric\TrustAreas\79b05e78-33f3-494b-8ae4-3ede6cb2eaa7\Software\Microsoft\SystemCertificates\My\Certificates. To view it, I exported it from here, and imported it to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SystemCertificates\MY\Certificates and then viewed it in certlm.msc.

  45. We’re getting a strange error when utilizing Okta and Citrix FAS. It passes through and we can get to the storefront. After clicking on an app, it looks like it opens but then a Windows Server 2008 logon screen with “Other User” is displayed. What are we missing?

      1. I am having this same problem on an internal storefront. We recently enabled Hello for Business which breaks single sign-on. So we are testing FAS, but get the same problem described where the logon prompt appears after launching an app. I have verified the GP is assigned to the VDA and that a certificate is issued for my user account on the FAS server.

    1. Hi, I’m getting the exact same issue as you(minus the use of Okta). Did you resolve this issue? I’ve been scratching my head for a several days now.

      1. Not Okta related, as we use Azure MFA for SAML. But, we had the same issue with our old 2008 XenApp servers. SChannel alert 40/70 thrown on the VDA when trying to logon. The user cert was being presented though. I exported my user cert from FAS (get-fasusercertificate) and ran “certutil -verify -urlfetch nick.cer” on the VDA in question. this threw back messages about the CRL being offline. Which it wasn’t because the same thing worked fine on our 2016 VDAs. Turned out for some reason one of the CAs behind the CA CDP URL (load balanced by Kemp) wasn’t issuing the delta CRL for whatever reason even the base CRL was issued fine. customer has not got to the bottom of it. For now that CA has been removed from the LB and all working on the 2008 VDAs.

        To test this you could disable CRL checking with:
        HKEY_Local_Machine\System\CurrentControlSet\Control\LSA\Kerberos\Parameters\UseCachedCRLOnlyAndIgnoreRevocationUnknownErrors
        DWORD: 1

        Might not even be related, but just sharing.

        Nick

  46. I’ve set up an acceptance environment, where the SF and DDC are on one server in Forest A, and the CA and FAS are on another server in Forest B (with the users). Handoff to the IDP works, assertion is received and applications enumerate. However at launch I receive “Cannot start…” on the SF server, I also receive the error Event 28: Failed to launch the resource “Application Name” using the Citrix XML service at address”??”. If I create a second store with explicit credentials on the same account the app launches..It appears that with SAML enabled the SF server is unable to fully query the user’s AD. Any suggestions?

      1. yes, XML is trusted…the above is the only Citrix error recorded. no other obvious failures or errors during this period

  47. Morning Carl, Can you explain why we need to leave the Single Sign On box uncheck under the Published Applications tab on the Netscaler? Thx

    1. You mean the SSON Domain? The SAML token contains the user’s userPrincipalName, which is fully sufficient for StoreFront to identify the user’s domain. No need for Gateway to send the domain info to StoreFront.

      1. I kind of thought as much just making sure. We have SAML w/ Azure AD working on our gateway for web, still waiting for Citrix to give us an answer about SAML working for workspace via the gateway. White papers dont say it wont work, but i’ve seen people say it is only supported on the mac version of workspace.

      2. Hi Carl, I’ve set this up with an admin account and works perfectly, don’t know if something’s cached somewhere because it still works even when I clear the cert from SF – but a user account can’t get to the Store “Cannot Complete Your Request” – SF events show failed with UPN and blank domain, 403 forbidden. – Cert templates have permissions for all. Bit lost… Any ideas? 🙂

        1. Hi Carl,

          Like we are going to configure FAS for SAML authentication.

          Can we also install the new CA authority server role on Fas server as well or we have to use the existing one ???

Leave a Reply to Brian Cancel reply

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