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. Hello, we use FAS in Citrix Cloud Workspace. We would like to add our cloud vm’s to our on-prem StoreFront and start it through Netscaler. We added the azure cloud connectors to our on-prem StoreFront servers. When we test locally on the storefront server we can start the cloud vm. Through netscaler we get see the cloud connectors down. We bind certificates on the cloud connectors so 443 is correct. In Azure firewall we don’t see any blocking issues (reason we can start from local storefront), but servers aren’t show status up. What could be the reason?

    1. Update. We found out that we had to use our on-prem cloud connectors in netscaler and after that the status was ‘up’. Then we noticed that the trustxmlport in Citrix cloud had value false which we changed to true. Then we needed to open port 1494 and 2598 for TCP and UDP on the cloud vm (we thought it was automatically opened). After this we could start the cloud vm through our company url configured through netscaler. But before the actually login screen shows the connection breaks with error socket 10057 or client error 0. Who knows what to do?

  2. Carl, thanks for this great document! I am working on a situation now with nfactor that is working well.

    The work flow is this
    1.) User adds their user id into the user name only logonschema and selects Logon and a group extraction takes place
    2.) If the user is part of the MFA group it redirects them to the Azure Login page
    3.) If the user is part of the LDAP group it prompts them for their password on the ADC
    4.) if the user isnt in either group it errors out and tells them there is no policy applied for them.

    Everything is working great, but there has been a request for the mfa users that their user id passthrough to the Azure page. I have looked and do not see where that is possible but wanted to ask if you knew of a way to possibly configure that?

  3. We’ve configured Azure SAML authentication with Netscaler to SF and it works fine. We are using an OnPrem AD group that is synced to Azure AD to grant access to the Azure SAML app. If we switch to use an Azure AD Only group to grant access,then after successfully authenticating to Azure we are dumped at StoreFront with a “CitrixAGBasic single sign-on failed because the credentials failed verification with reason Failed”. Is it a requirement that the group be OnPrem and how does StoreFront even know about that group if the Netscaler is passing the authentication through?

    1. There should be another event in StoreFront Event Viewer showing you user ID and domain. Domain should be blank. User ID should be userPrincipalName and it should match somebody in your local domain.

      1. The UPN is correct but it does show domain: ourdomain.org and the additional error is “An authentication attempt was made for user: me@ourdomain.org with realm context that resulted in: Failed (Windows Error code: -1073741715)

        1. Do you have a session policy that is setting the SSON Domain? If so, remove the SSON Domain from the Session Profile.

  4. If I need to create a separate Certificate Authority for FAS on the FAS server in an environment that already has a Root CA. Do I still configure as a Root CA instead of Subordinate so it is not tied to the other existing Certificate Authority?

  5. Hi Carl,

    great article and I was able to get it working. The only thing I don’t understand, when we use Azure AD as IdP, we often use provisioning of the users, and not only authentication.
    This setup is using shadow users and certificates to authenticate on the local Citrix environment, but is there no way to also use provisioning of the users?

    Regards,

    Gijs

    1. There’s nothing built into Citrix to do it for you. There’s probably an Identity Management tool that can sync accounts.

  6. Hi Carl,

    I have an SSO problem similar to Kai (January 5, 2022), but my environment is a little different.

    I do not have an ADC. StoreFront and Delivery Controller are on the same server. VDA is on a second server.
    StoreFront is configured with SAML to Azure AAD (with MFA). The initial login works fine with Azure AAD/MFA.

    However, users are prompted for credentials with every App/Desktop they open.

    I installed FAS on the same server as StoreFront. FAS config is authorized with CA but it doesn’t seem to be creating user certificates (Verify FAS at the end of your article). The VDA isn’t getting the certificates either, because it continues to prompt for credentials to open Apps/Desktop.

    I’m probably missing something in the config, but I can’t find the key info. Citrix Desktops and Applications v2012.

    1. Is the FAS GPO applied to StoreFront and VDA?

      Did you run the PowerShell commands to enable FAS on the StoreFront Store?

      1. I have it working!

        It turns out that I had more moving pieces than I thought. I had to install a separate StoreFront on a third server for testing, so that I wouldn’t impact the Prod environment. FAS was installed on the third server. GPO was applied, but it was not correct. We use a DNS alias (ica.company.com) instead of the server FQDN (server.company.com), and that caused problems with SAML until we changed the base URL. My FAS GPO referenced the alias, but it needs to reference the server name. For consistency, I would prefer to have the FAS GPO match the DNS alias, but I haven’t found a good way to do that.

        You were also correct that I forgot the PowerShell commands to enable FAS on the (test) StoreFront server. I actually figured that out within an hour of posting yesterday. There is a lot of great content in this article, but less than half applies to me, so it is easy to scroll past that section.

        My extra problem was that I was using a named rule in my FAS config. When I need to do customization, I use custom rules. Customizing the permissions of the StoreFront Server and User Restrictions based on group membership lead me to a custom rule (didn’t even create the default rule). After figuring out GPO and PowerShell to enable FAS on the StoreFront (thanks for the suggestions), I started to think about the fact the custom rule name was never referenced anywhere. I found the setting for it in the GPO, but decided to implement the Default rule for now in my test environment.

        SAML (Azure IdP with MFA), and SSO via FAS is working in my test environment. A FAS custom rule is my next set of testing.

        Thanks Carl!

  7. Anyone missing Non-gallery application view today in Azure? Used to have to enable legacy view to see now that option is gone.

  8. According to Citrix, “Starting from release 13.0 build 67.x, nfactor authentication is supported with Standard license only for Gateway/VPN virtual server.” I’m trying to get this straight – I have an ADC 13.0 build 83.29 with a VPX 50 Standard license, when enabling Authentication,Authorization,and Auditing it indicates – Feature not licensed. This should be allowed to be enabled now with Standard correct in order to use nFactor?

    1. It’s not intuitive. Go to Citrix Gateway and edit a Virtual Server. Add the Authentication Profile section. Select one or click Add. In the Authentication Virtual Server field, click Add.

  9. Very useful Article. Followed the configuration for Ctrix ADC version 12.1 build 63 and Backend is WebUI. Every think worked for SAML authentication with Azure. But it fails in the end with the error HTTP Error 401 This page s not working. This happens at XenApp login Citrix/Xenapp/Auth/agesso.jsp. If we remove SAML, we do not see any issues loging in without SAML.

  10. Thanks for the great info Carl.

    We have setup FAS with Citrix Gateway Service, works great until we install our Cisco Duo agent, Then the user is prompted for Windows username and password when launching the desktop.

    We’d like to have an HDX connection not prompt for credentials a second time but still protect Remote Desktop with Duo MFA.

  11. Hello Carl,

    I’m doing a fresh build here with ADC 12.1 integrated with Azure and I’ve gotten most of the redirection up and running thanks to your documentation. The problem I’m seeing now is once we redirect the user to login using their Microsoft credentials for Azure and it kicks us back to “https://mycompanydomain.com/cgi/samlauth” we’re receiving the following: Http/1.1 Internal Server Error 43531.

    I was able to check the logs on the ADC and nothing stands out and I noticed that nothing in these steps seems to mention having to do anything on the ADC side of things. Any suggestions you have would be much appreciated.

    1. Is this a Gateway? Does the Gateway Session Policy have a valid StoreFront Web Interface address? Is the ADC able to reach that StoreFront address? If you entered a FQDN, change it to IP address.

      1. This is a gateway, the session policy for the storefront web interface address is valid and the ADC is showing up for both Storefront servers. I changed the FQDN of the Storefront server to the IP and still received that same error when being redirected to the /cgi/samlauth directory.

  12. Citrix workspace stopped working after enabling FAS. I’m using AAA as recommended. this is the error “Your account cannot be added using this server address. Make sure you entered it correctly. You may need to enter your email address instead”. citrix workspace works fine with FAS enabled. Any idea what I missed?

    Thank you so much for sharing, you are always helpful.

  13. Hi Carl, I have a store with with different URLs, but I can only bind one authentication profile to the gateway, as of now, both urls are going to the same service provider. I want each url to be standalone with its own rewrite url.

  14. Do you have plans to make instructions how to configure FAS for Citrix Cloud Gateway Service? (Without ADC and StoreFront). I assume that it should be possible nowadays

    1. It’s pretty much the same FAS configuration except that in the FAS console you register it with Citrix Cloud instead of enabling it with StoreFront.

      1. Yes, that part is almost same, but in Citrix Cloud there’s quite a lot of fields e.g. Attribute name for AD Object Identifier (OID), Attribute name for AD Fores and Attribute name for AD Domain

          1. No, I mean things you need to configure on Citrix Cloud Identity and Access Management for SAML 2.0. Same place where you can download SAML Metadata, configure Entity ID and so on.

  15. Hi Carl, thanks a lot for all the articles you’ve wrote in the past years!!!

    I do not have much experiences with ADC nor Azure, but we need to setup a MFA solution with the use of Azure MFA, where users are able to enter username, pw and secure code provided via text message/phone call. I am not able to implement it together with FAS, because of a very complex setup of the service responsibility.

    So my questions are:
    – Is it possible to setup ADC with SAML and Azure AD, without building up a FAS and CA? My understanding would be, that the user will authenticate to the ADC via Azure MFA and SAML, afterwards the user need to enter the credential again at the store front. Would this work?

    – Much more better would be a solution without FAS/CA, where SSO is working and the users are able to use the existing Azure MFA… any chance?

    Best regards and thank you
    Kai

    1. You can add Azure MFA Plugin to Microsoft Network Policy Server and use RADIUS for authentication.

      Otherwise, if you’re doing SAML and if you don’t do FAS then the VDA will prompt the user to enter credentials.

      1. Unbelievable, such a fast reply to my post. You are awesome. Thank you very much.

        NPS is also not an option in our environment, because we would like to avoid setting up additional Services, if possible.

        So Users need to enter their credentials everytime when they Open a PA? Workspace App is Not Used… Only ADC + Storefront.

        1. Correct. Internally, you could use Pass-through authentication in Workspace app. Externally that’s not an option so users will be prompted at each VDA they connect to.

  16. Setting a new SAML with FAS configuration. Cannot start desktop, get Access Denied event logs on StoreFront and Failed to issue a certificate for [upn: ….] exception: CSR response status was TryAgain. Citrix Support have checked the configuration and taken CDF traces and Wireshark captures from SF,FAS and CA. Waiting on a response. Any ideas on what to check? Have checked permissions on Cert templates.

  17. Usefull article. I came accross with an issue in logout url. When I logout, it shows 404 error. have you seen this error before?

    1. It’s not obvious how to confiugre it. You go to the Gateway. Add Authentication Profile. From there you can create an Authentication Virtual Server.

      The initial release had some issues where the config would disappear after a reboot. I assume that’s been fixed.

  18. Hi Carl,

    After the configuration with ADC 13.1 we have Azure configured as IdP and running Azure MFA. For users who are accessing the Citrix environment it’s working as a charm!

    But, users who are using the Citrix Workspace app on iOS or Windows they cannot add their accounts. They receive on Windows the error message: ‘Your apps are not currently available. Please try again in a few minutes or provide this information to the help desk: cannot connect to .’ On iOS users are receiving the message: “Cannot add account. All stores in the discovery document have been loaded”

    On Windows and iOS the users are using the latest version of Citrix Workspace.

    In the Storefront we receive this message in the Event Viewer:
    EventID: 23
    Source: Citrix Store Service
    Message: Gateway data from the request and the authentication token are not matching. Request was made to store .

    What I already have done:
    – Configured the external beacons.
    – Disabled ‘Require token consistency’ in the store settings, but then users cannot logon through the portal anymore. So I enabled this option again.

    Do you have any suggestions?

    Thanks in advance!

    1. On StoreFront, for the Gateway object, did you configure the Virtual IP field?

      Are you testing this internally? Is your StoreFront Base URL the same as the Gateway URL? If so, make sure your client machine is resolving the Gateway URL to the Gateway VIP and not the StoreFront Load Balancing VIP.

      1. Thanks for the quick response!

        Yes, we have configured the Virtual IP field and we are testing this externally, internally everything works fine. The Storefront base URL is the same URL as the Gateway URL. Also, the Gateway URL is resolving to the Gateway VIP.

        1. Do you have multiple ADC appliances doing SAML authentication? Is that why you configured the Virtual IP field? If you only have one ADC appliance doing SAML authentication for the store then remove the Virtual IP field.

          1. Thanks again for your quick response! Currently, we have one ADC appliance with SAML. We have removed the Virtual IP from the configuration in Storefront and tested the Citrix Workspace app externally on Windows and iOS, but we have still the same error message in the event viewer on Storefront:

            Gateway data from the request and the authentication token are not matching. Request was made to store .

            Do you have more suggestions?

            We really appreciate your effort!

          2. Hi Carl, first thanks for this great article. I am having the same issue.Web works well but Workspace App on iOS or Windows do not. iOS could add the account but not start an app or desktop and windows won’t add an account.

          3. Thanks for the fast response. Yes, I did. I configured an authentication profile with an advanced authentication policy

          4. The StoreFront Base URL is https, not http? You can check the logs on the Workspace app.

  19. Hi Carl,

    Thank you for the wonderful article (as always). is there any way to check the existing certificate validity for Citrix Federation services?

  20. Hi Carl!

    Thanks for the detailed guide. After the configuration we get this error on the FAS in the Event Viewer:

    [S101] Server [] is not authorized to assert identities in role [Default].

    We can confirm that no certificated are issued to the user, so the VDA cannot start the desktop. We have configured the Assert Identity to “Allow” for the Storefront, but we have still this error message. Also, the Citrix Storefront and FAS are already rebooted.

    What can go wring in this scenario?

    Thanks!

    Dutch

    1. We have fixed the problem. In the Access Control on the FAS Rule ‘Default’ we had configured the Storefront server on Allow but the Domain Controllers was still configured on Deny. Because ‘Deny’ takes precedence over ‘Allow’ and we have changed the entry for Domain Computers to ‘Allow’ from ‘Deny’ and the problem is fixed.

      Thanks for the great guide!

  21. Hi Carl,

    is there an option to import samal metdata from xml file?

    Also how we can give our details to them as xml file?

    Many Thanks
    Saju

  22. Hello Carl,

    We have a problem when we disable the option Force Authentication the user wil automatically authenticate without MFA.
    When we check the Force Authentication we need to manually enter the UPN and password. After entering those credentials MFA is working, is there also a way to automatically enter the credentials?

    Best regards,

    Marco

  23. netscaler multiplexing issue in latest version NetScaler NS13.0: Build 82.42.nc. We use OWA externally for our users via CSW Vip and sympton was that jumping in to anothers mail boxes.We disable multiplexing working fine now.

  24. Hi Carl,
    Is there any document that lists the minimum hardware requirements? I know this article says if less than 10k users 4 VCPUs is enough. Any idea what the RAM and HD sizes should be? Ill be grateful if you point me in the right direction please.
    Thanks.

  25. Hi Carl,

    Really appreciate your guides.
    I’m having trouble implementing this.
    I have MFA via AAA nFactor enabled and functioning but when a user gets handed off to the Storefront it fails giving the user “Cannot Complete your Request” error.
    Users authenticate with their UPN which matches on-prem AD and pulls the appropriate username but it errors out saying invalid credentials were given.
    Storefront has Full Delegated Credentials to Gateway enabled, Callback URL is set and reachable from Storefront and I have FAS setup but if I understand everything correctly FAS doesnt play a role in Netscaler to Storefront authentication.
    Checking event viewer on the StoreFront shows the following errors associated with the attempted Storefront login

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

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

    AND

    “CitrixAGBasic single sign-on failed because the credentials failed verification with reason: Failed.

    The credentials supplied were;
    user: $Username
    domain: $Domain”

    Occasionally I will see this error occur too:

    “An authentication attempt was made for user: $Domain>\$Username with realm context that resulted in: Failed (Windows Error code: -1073741715)”

    What’s maddening is it works for a very small group of users without issue.
    I’ve reviewed the AD accounts for both functioning and non-functioning users and cannot see any differences…
    Is there something I am missing or somewhere you can point me that may help track down the source of this issue?

    Many thanks for any assistance you or anyone here can provide.

    1. In your Gateway Session Policy/Profile, make sure SSON Domain is not configured. The SAML Assertion should include UPN and StoreFront uses the UPN suffix to find the user’s domain so there’s no need for Gateway to also send a domain.

      1. Thanks for the quick response and the suggestion.
        If I remove the SSON Domain from the Session Policy the few users that can get into Storefront can longer connect.
        Instead the second error no longer includes a domain listed

        “CitrixAGBasic single sign-on failed because the credentials failed verification with reason: Failed.

        The credentials supplied were;
        user: $Username
        domain:”

        It correctly pulls the username from the given UPN/SAML Assertion but does not seem to acknowledge the domain it pulled from or atleast leaves that field blank in the error given on the Storefront.
        I have Storefront set to trust any domain, so Im not sure where the breakdown is occurring.
        The UPN suffix is different from our the domain but should be trusted…
        To clarify UPN Suffix is something akin to “NewCompanyName.com” and the domain is “OldCompanyName\”

        Could this be the root of my problem and if so how would I correct it?

        Again, really appreciate your assistance and all that you do for the Citrix Community.

        1. StoreFront needs to be able to find an account in its local AD or trusted domain/forest that matches the UPN in the SAML Assertion. I’m not sure if UPN suffixes work across external trusts but it should work across forest trusts or trust in same forest as local domain.

  26. Hi Carl, Thank you for the write up. We are a service provider of Citrix and only have a small subset of customers that require Azure for MFA. These customers already have their own Azure tenant that we are not managing. Would we only need to apply the FAS GPO to those specific VDAs where this is required? I do understand that we’ll likely need a new storefront and a separate gateway VIP and URL for the clients.

    Cheers,
    Hardy

    1. If you enable FAS on a StoreFront store, then all users of that store use FAS. You could create a new StoreFront store just for your SAML users.

      1. Thanks for the quick reply Carl. Assuming I setup a new Storefront and new Gateway VIP with a new URL, am I still able to utilize the same underlying Active Directory and Delivery controllers that I use for my non SAML users?

        Thanks Again

          1. Thanks again Carl. I am in the process of building out new storefront servers, a new ADC version 13 as well as the addition of a FAS for my existing environment. I will be running both new and old in parallel and will be switching customers over gradually. Seeing as how we are a service provider with only a single domain for all our customers, although each customer does have their own UPN suffix, is there anything else you would recommend for the new build?

            I am planning on creating a new base URL and giving some of our larger customers their own gateway vip as well as their own URL, ex: customer1.baseurl.com

            Cheers,
            Hardy

  27. Hi Carl, thanks for this article, God send! One thing we’ve noticed is that enabling SAML replaces our heavily customised logon page where we have added helpdesk phone numbers, disclaimers etc. Is there a way to use SAML but still retain the main logon page?

  28. With the SAML Server configuration adding the syntax via gui to the Relay State Rule expression box, receiving error at Azure authentication: RelayState in Response does not match with rule in Action. Please contact your administrator.

  29. Hi Carl, apologies if this has been asked before. We have the Netscaler Azure SAML SSO config working as expected. However for the Wyse terminals we have limitation where they don’t have an open internet connection to MS 365 login page. Do you know if this can be proxied through the Netscaler so there is no client internet requirement.
    Many thanks

  30. Hi Carl, Is the relay state rule option only available after the upgrade per CTX297155 ? I am trying to edit my existing SAML Server but I don’t see the option to add the relay state expression.

  31. Hi Carl,

    Great article (again), very helpfull! I was wondering if you already configured it in a multi-tenant environment?
    https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-convert-app-to-be-multi-tenant#update-your-code-to-send-requests-to-common
    I’m not sure what to fill in on the SAML server in the netscaler, i tried to fill in https://login.microsoftonline.com/common under Redirect URL but that’s not working, it says page not found.

  32. Hi Carl,

    I have setup FAS with azure MFA. It is going through microsoft for login and able to see the published desktop. when I launch the desktop. it gives “Cannot start desktop message”. and found event id 123 at FAS server. Any ideas whats wrong here?

    [S123] Failed to issue a certificate for [upn: xxx@test.com role: Default] [exception: The CSR failed at all configured certificate authorities]

    Thanks

    1. Any error in the Certificate Authority’s logs? Maybe the Failed Requests node in the CA console will give you some info.

      1. Unfortunately no logs recorded on the CA. But when I check the CA console, I can see all the certificate requests are struck in the pending request where the CA is not issuing the cert automatically for each login. Moreover, there is no event on the failed request node.

          1. I have tried this, but no luck. I am getting a new error as below on the CA failed requests.

            Active Directory Certificate Services denied request 110 because One or more signatures did not include the required application or issuance policies. The request is missing one or more required valid signatures. 0x8009480b (-2146875381 CERTSRV_E_SIGNATURE_REJECTED). The request was for CN=Domain\User Name. Additional information: Denied by Policy Module 0x8009480b, The Citrix_SmartcardLogon Certificate Template requires 1 signatures, but only 0 were accepted.

    2. You able to solve the problem ” Active Directory Certificate Services denied request 110 because One or more signatures did not include the required application or issuance policies. The request is missing one or more required valid signatures. 0x8009480b (-2146875381 CERTSRV_E_SIGNATURE_REJECTED). The request was for CN=Domain\User Name. Additional information: Denied by Policy Module 0x8009480b, The Citrix_SmartcardLogon Certificate Template requires 1 signatures, but only 0 were accepted.” I have the same problem.

  33. Hi Carl.

    I enabled Nfactor SAML authentication – and it works – I am authenticated, get empty page ( No icons due to no group extraction yet)

    Once I add Group Extraction” in N-Factor I get “You are not allowed to login. Please contact your administrator” in https://gateway_address/cgi/samlaut page.

    I have not made changes to storefront yet

    LDAP server setting:
    Server Logon Name Attribute is set userPrincipalName
    but, SSO Name Atribue to samAccountName

    So is this error due to Storefront not configured yet or due to LDAP server settings?
    Or something else?

    Thank you very much for your help

    Azer

      1. The only session policy within unified gateway for ALL is standard one for RDP proxy – UG_VPNSact_IP adress
        Other session policies with link to Storefront are coming from AAA Group, based on Group membership.
        Works fine with basic authentication
        Once I enable SAML with “Group extraction” in second factor, I get this error

        1. I’m guessing one of your AAA bound session policies has the setting “Groups Allowed to Login”. If you look at the session policies/profiles in the Running Config (under System > Diagnostics), it should be more obvious.

          1. Thank you for quick response, Carl!

            Checked the session which gets invoked

            add vpn sessionAction NAME_of_POLICY -sessTimeout 120 -transparentInterception ON -defaultAuthorizationAction ALLOW -SSO ON -ssoCredential PRIMARY -wihome “https:/address goes here” -ClientChoices OFF -ntDomain WB -clientlessVpnMode ON

            I do not see allowedLoginGroups parameter here.

            Any ideas which direction I should look at?

            Regards

  34. Hi Carl,
    Is it possible to enable FAS but not use ADFS. We are using Password Hash Syncing.

    All documentation seems to point to using ADFS, but when you enable FAS and not use ADFS. I don’t appear to get a PRT when I’m automatically signed in to make use of SSO to modern apps.

    1. Did you ever get anywhere with this? Seeing the same thing. PRT eventually shows up, but not at logon.

  35. Hi Carl,

    I am trying to use users email address for SAML authentication from Microsoft Azure to on premises Netscaler gateway. I am using user.mail attribute in Azure portal as Source attribute and have specified emailaddress in user field during configuration for SAML authentication server on netscaler. But, even if the email address on the on premises AD is blank or incorrect, I am able to login to netscaler gateway. Not sure what might be missing.

    Will you be able to provide some guidance on this please?

    1. NetScaler will accept any SAML Assertion that is signed by the IdP. After SAML, NetScaler then needs to extract the Name ID from the SAML Assertion and send it to the back-end server (StoreFront). StoreFront will look in its local Active Directory for a user account that has a User Principal Name that matches the SAML NameID.

      1. Hi Carl, Dilip,

        I’m also using emailaddress in user field but I don’t know how Netscaler Gateway send this information to the StoreFront because I don’t see any response from the Gateway to the StoreFront with the mail address. I have got traffic capture with wireshark, and I’ve even deciphered the traffic, and I don’t see how the Gateway send email address to the STF.

        Does Gateway send via HTTP Headers or via POST method to STF?

        I see they are using CitrixAGBasic method but It doesn’t work with SSO

        Thanks!

      2. I realize this is a fairly old post, but I am trying to accomplish exactly this.. I Took a test storefront setup in my netscaler that was using LDAP. I created the SAML (Microsoft MFA) connection, applied it to the storefront server. Now, MFA works, but I don’t seem to pe passing the creds to the storefront server. Do I pass the SMAL creds to LDAP? Or should they be passed to the storefront system? Also, we are not using FAS if that makes a difference.

  36. QQ: have you seen it where a single user has their account renamed, and then their old certificate is named differently and causing inaccessibility? The answer we originally were told from other support was to recreate the user’s ID, but that’s not feasible. Is there are a known way to find and remove that user authentication cert and have the SmartCardLogon template re-issue with his new UPN?

  37. We have setup FAS en if we log in we can start Applications and/or a VDI. We have an issue that if we start a VDI we (most of the time) aren’t able to start a published app (for example, the application starts directly from the FAS portal, but not within the VDI). We noticed that after login a prelaunch session is started ( we have enabled it on some delivery groups) but the username isn’t displayed, only a ” – “. When we do it without FAS and just through Netscaler and username/password/tokenid we never see the issue. When we see the ” – ” we aren’t able to start any other application, in the portal or within the VDI. Did we forget something or do we have to set other settings?

    1. Does the Workspace app in VDI point to a different store? Is FAS enabled on that store?

      With FAS, when you log into a VDI, there’s no password for Workspace app to capture so it’s not able to send the password to the next hop.

      1. The scenario is that we have a new StoreFront environment which will be our production environment. We log in through MFA and then it comes through our gateway to the new url When we start a VDI the installed workspace app has stores from our current storefront environment, thus another storefront url. On url 1 and url 2 we have identically stores, but the base is different as you said.

        1. We enabled FAS on the other store, edited the registry and changed the url, started a VDI and we were able to start an application with FAS. So great!

          We now want to enable FAS on the stores that are configured with the Workspace App. My question is if there is any impact on the current environment because we are in a transitional phase. So for a x time we have to let our employees work through FAS and Username/PW/token. We think that there will be no impact, but just to be sure.

          Who can answer this last puzzlepiece?

  38. Hi,
    I am looking to configure certificate-based authentication on the application so that it can use FAS in-session certificate for SSO. Do you’ve any guidelines for such configuration required on the application side?

    Regards,
    Sourabh

    1. What application? It depends on the application and the web hosting technology (e.g. IIS) that it is using.

      1. This is a installed application on VDA and not a web app. Application support AD authentication. We want to make changes in this application to use certificate based authentication.

  39. Carl,

    First off, thank you again for all you have done for the community of the years. Your knowledge and guidance as been much appreciated by myself.

    Now, we have a strange issue where when users will launch a published app they are getting server login, as if the SSO is not working. Our current setup is:

    Azure MFA
    ADFS 2019
    NS 12.1 55NC / Unified Gateway
    Storefront 1912.0.0.40

    Azure MFA and ADFS integration has no issues it seems. In fact, the whole process of a user getting challenged works with out issues all the way down to seeing their publishes apps, only when they launch does it not pass through. If you enter your creds, then of course it launches. My suspicion is in the session profile, but I have played with settings under Client Experience and Published Apps, but no conclusive fix.. Was wondering if you had an idea or maybe point me in the right direction?

    Only odd item we had to turn on was: “Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true” as we started getting:

    “The Citrix servers do not trust the server. This message was reported from the XML Service at address http://localhost/scripts/wpnbr.dll [com.citrix.xml.NFuseProtocol.RequestAddress].”

    Thanks

    1. Verify that the GPO applied to the VDA machines. Look in regedit > HKLM > Software > Policies > Citrix > Authentication.

      You can also enable the CAPI2 log on the VDA and check it for certificate errors (e.g. domain controllers don’t trust the certificate).

      1. Yep, so I am seeing “A certificate chain processed, but terminated in a root certificate which is not trusted by the trust provider”… so would that be the Token-Signing cert of the ADFS server, that’s the same cert used on the ADC for ADP Certificate Name.

        1. It’s the root or intermediate certificate for the Certificate Authority that FAS is using. Your Domain Controllers probably don’t trust it. If you just built the CA, then run gpupdate /force on the Domain Controllers so they get the new CA certs.

          1. ok, I think I have been barking up the wrong tree.. looking at another test server, there are no errors under the CAPI2 logs, but get the exact some response with the server login pop up.. if I bypass FAS and hit our Citrix GW on the NS, we get pass through without issue.. I know I missing something, but just can’t put my finger on it.

          2. One last question, the GPO settings only apply to using Citrix FAS correct not, ADFS?

          3. FAS is only invoked when the user clicks a published icon. The user only sees icons after SAML has already been completed. In other words, SAML and FAS are completely separate processes.

            The GPO for FAS tells StoreFront and VDAs the addresses of your FAS servers. This has nothing to do with SAML.

        2. Were you able to resolve this issue? I’m running into the same issue where I can get all the way from SAML authentication at the Netscaler through to Storefront, however when launching VDAs we get “incorrect username or password”

  40. Hi Carl,

    Great article as always.

    An addition to the article is that you also need to configure the logout url in your Enterprise Application in Azure AD when you use Azure AD as your identity provider; https://gateway5.corp.com/cgi/logout

    Without specifying the logout url if you choose logoff in the Citrix Gateway portal and go back to https://gateway5.corp.com the session remains active on the Netscaler.

    see also the discussion: https://discussions.citrix.com/topic/398513-saml-logout-issue-with-netscaler-gateway-and-azure/

    1. Hello colleagues,

      I am having a problem with logout. I tried everything mentioned in article shared by Robert. None of them works. SAML logs out, Netscaler session stays active.
      If I choose “Force Authentication” SAML
      Have a open case with CITRIX – escalated to the highest level possible – unfortunately no solution yet. CITRIX now suggest that I switch all my expressions to Advanced one – as N-factor seems to have a problem with that.
      I use 12.1 on MPX.
      ADC is SP
      AzureAD is IDP
      Did you experience it? does moving to to advanced policy actually helps? It is large task – I would like to hear from you if indeed Classic policy is a real culprit here
      Thank you

  41. Hi Carl

    Great article and thank you for this amazing shared resource – we’re in a unique position where we would like to enable SAML auth for Storefront access via the NetScaler gateway without FAS – fully understanding users will need authenticate a 2nd time on the StoreFront logon screen. When we try and achieve this by removing the “Single Sign On Domain” option from the session profile, after successful SAML auth and navigating past the “Detect Receiver” screen from StoreFront, instead of getting presented with a StoreFront logon screen, we just see a “Cannot complete your request” error.

    The Citrix Delivery Services event log shows an error EvenID 10 in correlation to this occurring – “A CitrixAGBasic Login request has failed.
    Citrix.DeliveryServicesClients.Authentication.AG.AGAuthenticatorException, Citrix.DeliveryServicesClients.Authentication, Version=3.12.0.0, Culture=neutral, PublicKeyToken=null
    Authenticate encountered an exception.
    at Citrix.DeliveryServicesClients.Authentication.AG.AGAuthenticator.Authenticate(HttpRequestBase clientRequest, Boolean& passwordSupplied)
    at Citrix.Web.AuthControllers.Controllers.GatewayAuthController.Login()”

    Thank you and kind regards

    1. Did you configure the Callback URL and enable Full Delegate Credentials to Gateway?

      I’m guessing there’s another event in StoreFront event viewer that shows the actual problem.

      1. Hi Carl

        Thanks for the response.

        I have tried with and without the Callback URL and enabling/disabling Full Delegate Credentials to Gateway with no success – BUT I don’t think I need either of these settings as we’re not using FAS – we want users to be prompted for authentication by Storefront after completing Azure AD SAML auth (I know this is sounds a bit crazy and poor UX – long story as to why)

        So it should be
        1) User access https://sf.company.com
        2) Redirect to Azure AD for SAML Auth
        3) Redirect back to NetScaler and perform an additional auth on the Storefront login page
        4) Access granted

        SAML seems to be all good – we get directed back and see Storefront’s “Detect Receiver” screen, however after this we don’t get a prompt, just the “Cannot complete your request” error.

        Its like its trying to perform SSO to StoreFront, even though we don’t have that configured on the NetScaler.

        There are no surrounding errors or messages in the event log, just the Event ID 10 error.

        Appreciate any guidance

        1. You need to do all of the StoreFront config for SAML on NetScaler except FAS. You need callback plus Fully delegate credentials plus SSON enabled in your Session Profile. That way StoreFront can sign in using the user’s UPN without needing the user’s password.

          1. Hi Carl

            I’m not sure I understand why I’d want “Fully Delegate Credentials” on SF and SSO enabled on the NS Session Profile – I don’t want the NetScaler to pass any credentials to StoreFront, just present the StoreFront login screen after successful SAML authentication.

            Once again thank you for your responses – it is greatly appreciated.

  42. I’ve succesfully implemented Citrix FAS but have one issue. When i’m logged in through Citrix ADC and storefront with Citrix FAS on the published desktop my published applications in the startmenu on other VDA’s don’t work anymore. The’re getting stuck at ‘Please wait for local session manager’. The applications are published from another storefront store and published into the startmenu with WEM. When I manual login in the store from a browser then I can choose to use the already signed-in account. When I do this I get the same result. When I choose to login with username and password then I can start an application succesfully.

    I cannot find any related eventviewer notifications. What am I missing?

    1. Is FAS also enabled for that store? You’ll probably need FAS because Windows doesn’t have the user’s password.

      1. Hi Carl, thanx for your reply. But I don’t think we need to enable FAS on that store. Because we’ve already an user certificate in the session, so you should be able to use that same certificate to authenticate against other applications/sites etc….

        I think I’m a little further but not quite there yet. It’s still not working. But I configured the FAS gpo to allow ‘in-session certificates’. Something what also is mentioned in this article: https://citrixguyblog.com/2020/01/25/citrix-fas-notes-from-the-field/

        But I don’t no how to configure this correctly to work. I did a gpupdate on all servers but maybe I need to reissue the certificate for this or something else.

        1. FAS needs to be enabled on that other store. We want into the same issue. The in-session cert option doesn’t help.

  43. Hi Carl,
    Thanks for this article. I apologize, I am not a Citrix, nor an Azure AD specialist.
    But I am looking for a solution that would enables me to use my company Azure AD to log into Citrix NetScaler. I don’t expect the on-premise (Citrix) AD to synchronize with the company Azure AD (in the cloud). Our IT consultant tells us that if we want to use Azure AD authentication to log into Citrix NetScaler, AD Connect would be required and the synchronization would be from the on-premise AD to the company Azure AD, and not the other way around. Which would be a problem because I want to keep Azure AD (in the cloud) as my main AD.
    I feel like your article does exactly what I expect, and AD connect doesn’t seem to be required. What do you think?

    Thanks and regards

    1. Users must have accounts in local AD that the VDAs are joined to. Ultimately VDA authentication is performed in local AD, not Azure AD.

      SAML sends an assertion containing the user’s userPrincipalName or email address. StoreFront and FAS then need to find an account in local AD that has a userPrincipalName that matches the SAML Assertion Name ID.

          1. Thank you so much Carl. That would mean the authentication process is fully handled by Azure AD, then the access is granted when a UPN or an email address of the local AD is matched. That is exactly what I need.

            Have a great day!
            Thanks and regards

  44. Hi Carl. Thanks for your blog. I dont know what would we do without it. We currently have a nfactor setup on the NS Gateway with Symantec VIP. we are moving to Okta and would like to know if there is any reference document for Okta SAML Authentication on the Citrix Gateway.

    1. Hi Braz,

      We also have similar requirement , please let me know if you completed the nFactor from symantec VIP to OKTA SAML

  45. Is it possible to use the Workspace app on iOS to authenticate through ADC and Storefront without using Radius? Looking to only use Azure AD/SAML for authentication. Thanks.

      1. Every piece of documentation that I find has the user authenticating through a browser, including that one. With the lack of examples I continue to question to the feasibility of this type of auth through Workspace.

        1. The newest ADC builds with the newest Workspace app versions support SAML if you configure it on ADC using nFactor (Authentication Virtual Server). SAML is a web-based authentication protocol so Workspace app had to be developed to use an internal web browser.

          1. I get the redirect to SAML auth, aaad.debug shows auth and ldap lookup for AD groups. I see the session profile for Citrix Receiver log a policy hit, yet Workspace hangs at Please wait….

  46. I had to reach out to Citrix for support. They created a private fix, which resolved the issue. We were using CVAD 7.15 LTSR CU4 at the time. I believe this fix has been incorporated into the latest LTSR and subsequent CR’s.

  47. Hi Carl,

    With your detail articles and feedbacks, we successfully setup our ADC as SP with SP initiated workflow via one URL; https://sso.abc.com

    We would like to support new additional IDPs via the same SP SAML entity ID (https://sso.abc.com) and ACS URL. Is it possible? Currently, anyone accessing https://sso.abc.com is redirecting to the existing IDP’s URL.

    If not, can we add new IDPs without adding new SP entity ID by using IDP initiated workflow?

    Thank you very much as always.

    Sunny

Leave a Reply to Sahultry Cancel reply

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