Citrix Federated Authentication Service (SAML) 2411

Last Modified: Dec 4, 2024 @ 2:28 am

Navigation

This article applies to Federated Authentication Service (FAS) versions 2411, 2402 LTSR CU1, 2203 LTSR CU5, 1912 LTSR CU9, 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 in an nFactor (Authentication Virtual Server) configuration works in both browsers and Workspace app.
  • 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 2411.

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_2411.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.
  8. Click Finish.

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 PowerShell command:
      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.
  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 More.
    5. You can optionally check Force Authentication to prevent users from doing SAML authentication using cached credentials. This prompts for MFA every time the user accesses Citrix Gateway.
    6. Scroll down and click Create.
    7. Edit the SAML Server again.
    8. 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

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,097 thoughts on “Citrix Federated Authentication Service (SAML) 2411”

  1. Really appreciate your work. They have helped me many, many times. Wonder if you have any idea on the following: I have a working NetScaler, SF and FAS environment. It works with Windows 2012 R2 and Windows 7. However I have a Windows 10 that will not authenticate. The error is documented at https://docs.citrix.com/en-us/xenapp-and-xendesktop/7-9/secure/federated-authentication-service.html. An error on the resource VDA of “[S101] Identity Assertion Logon failed. Unrecognised Federated Authentication Service [id: {0}]”. No corresponding error on the FAS server. I have checked and the resource VDA is allowed on the FAS.

    1. The group policy with Federated Authentication Services server names is applied to the VDA? Look for HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Policies\Citrix\Authentication\UserCredentialService\Addresses on the VDA.

      1. Thank you. I failed to understand that all VDA Resources need to be linked to the FAS policy. Once I corrected that, I could get into the desktop.

  2. Hey Carl,

    Running into an issue and was looking to see if anyone faced something similar or had an idea?

    We are using StoreFront 3.9 SAML without NetScaler (IDP SSOCircle) on XenApp 7.13. The redirects works and passes to the SSOCircle login page, after a successful login to SSOCirlce the connection is sent back to Citrix and it fails with the error blow on Storefront server.

    The security token failed validation.
    System.Security.Cryptography.CryptographicException, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089
    The signature verification failed.
    at System.IdentityModel.SignedXml.VerifySignature(HashAlgorithm hash, AsymmetricSignatureDeformatter deformatter, String signatureMethod)
    at System.IdentityModel.SignedXml.StartSignatureVerification(SecurityKey verificationKey)
    at System.IdentityModel.EnvelopedSignatureReader.OnEndOfRootElement()
    at System.IdentityModel.EnvelopedSignatureReader.Read()
    at System.Xml.XmlReader.ReadEndElement()
    at System.IdentityModel.Tokens.Saml2SecurityTokenHandler.ReadAssertion(XmlReader reader)
    at System.IdentityModel.Tokens.Saml2SecurityTokenHandler.ReadToken(XmlReader reader)
    at System.IdentityModel.Tokens.SecurityTokenHandlerCollection.ReadToken(XmlReader reader)
    at Citrix.DeliveryServices.Authentication.Saml20.SamlExtensions.GetSecurityToken(String assertion, SecurityTokenHandlerCollection securityTokenHandlers)
    at Citrix.DeliveryServices.Authentication.Saml20.SamlManager.ProcessSamlResponse(String base64EncodedResponse, Boolean compressed)

  3. hey Carl, step 28, the relogin without closing browser? you know a way to handle that on SF 3.6? i see the steps 28 and 29 appear to only work on 3.8, just curious

  4. Hi Carl,

    Is ADFS with SAML to StoreFront without NetScaler still the only supported iDP with for Citrix receiver?

    Currently, we use 2 factor authentication on the netscaler for external users coming thru the internet. Internally we use Citrix receiver to connect directly to storefront. Management would like to implement 2 factor authentication inside for some users.

    I am exploring options for implementing 2 factor authentication. I would not want to go the ADFS route. We are looking into Duo, SaasPass, and others solutions.

    I would prefer if I don’t have to get another set of netscaler to use internally know that I see that storefront supports SAML.

    What do you recommend?

      1. thanks carl.

        Do you still have to set up FAS even if you are using SAML authentication from storefront without netscaler with a third party iDP?

        Is FAS required for SAML authentication weather is set up at netscaler or storefront level?

  5. Hello Carl,
    This works just as you explained. Thanks.
    Now we have a few users in another domain. The domain is trusted. Citrix works without Federation Services. But as soon as we follow the steps to enable federation – the users NOT in the SF domain cannot launch Desktops. They can see the list of app, though.
    Here is the error message –
    [S104] Server [domain1\CTXDDC02$] failed to assert UPN [testctx@domain2.ad] (UPN not allowed by role [default]).

    Any idea where can I find info about this error code?

    1. In the Federated Authentication Service Console, on the User Rules tab, in the “List of users” button, is the other domain added?

      1. Thanks! That’s takes it a little further.
        Now the desktop tries to launch, the user certificate is issued but the windows logon screen says “User name or password is incorrect”.
        No event log on FAS or SF or VDA.

        1. “User name or password is incorrect” is usually caused by the machine not able to perform certificate revocation check (old, but still relevant):
          https://www.citrix.com/blogs/2012/06/05/slow-web-interfacemmc-console-crl-explained/

          What you can try to do is to create the following registry key:
          Path: HKLM\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters
          Key Name: UseCachedCRLOnlyAndIgnoreRevocationUnknownErrors
          Key Type: DWORD
          Key Value: 1

          Ideally test with an existing VM (not PVS\MCS). If this helps, you should try to check your CRL URL and get it fixed…

  6. Hi Carl,

    I am following your steps for setting up SAML on Storefront 3.9 without NetScaler, we are using SSOCircle as a test. Step 19 I can not locate metadata or any folders with AssertionConsumerService.

    1. Is Authentication integrated with your store (e.g. /Citrix/StoreAuth)? Or is it separate (/Citrix/Authentication)?

  7. Hi Carl,

    Thank You very much for your post! I got two questions tho regarding shadow users:

    We got all relevant user accounts of our partner company already in our companies AD. Since users do not want to update passwords for two accounts we were asked for a federation.

    Questions:
    – Can we edit the already existing user accounts and transform them to shadow users or do we need new ones?
    – How is the shadow user associated with the started Citrix App. We got a Citrix published Software which uses the Windows credentials to connect to a SQL DB. If we use shadow users now, this should not work anymore, correct? And would it help to do what I asked in the previous question?

    Thanks alot for your time and advice,
    regards
    drakefin

    1. All you need are AD accounts with UPNs that match the email addresses (Name ID) coming from your iDP. There’s nothing special about shadow accounts, other than the fact that the password is unknown.

      If the SQL database or application is authenticated using Kerberos, then there’s nothing to worry about. If the application needs the user’s AD password, then that might be an issue.

  8. Hi Carl:

    Do you know if Direct to Storefront(v3.9) SAML supports IDP-initiated SAML? SP-initiated works fine but IDP produces a Bad Response. SAML Response from the IDP is exactly the same as SP but, of course, the SP response includes a RelayState.
    I just want to make sure I am not chasing my tail if IDP is actually, not supported.

    Thanks in advance

    1. In version 3.9 do you still need the FAS. i configured the SAML without FAS. I get redirected to my IDP and then after authentication i can see the landing with all the applications configured for me. But when i launch the app it goes to desktop screen not launching the application.

  9. Hi Carl

    in the FAS in step 2 “Setup CA” no CA is shown, although I have a CA in the same network/domain. How is the search working? Or do I have to install FAS on the CA server?

    Thanks and regards
    Udo

    1. So the error was, that our CA was migrated to another server and the templates section showed up the error “not found”. That fixed I see the CA now in the dropdown list.

  10. Hi Carl

    What could be wrong, if I don’t see a CA in the second step “setup CA” although I have a CA in my network. How is the search working? Or do I have the FAS to install on the CA server itself?

    Regards
    Udo

  11. Hi Carl,

    fyi, I was able to fix it.
    There were two steps I’ve done.
    First step was to run the powershell cmdlets for Storefront and the DDC again and reboot the SF and DDC. After this was done, the error changed. I did not get the Windows logon screen like before, but I got a “Request Not Supported” on the logon screen.
    For this error there is a know solution in CTX218941 – Option B solved this issue.

    I’m now able to log on via SAML without any issue 🙂

    Kind regards
    Georg

  12. Hi Carl,

    thanks for your detailed instructions.
    anyway, I still have some trouble getting it up and running.
    I’m trying to implement the SAML authentication without a Netscaler with Storefront 3.9.
    I am able to logon to Storefront via SAML, but when I try to launch an application, I get the Windows Logon Screen.
    I can see, that FAS created the certificates, but it looks like they are not used to log on the user on the Terminalserver. The GPO gets applied and I also added the UseCachedCRLOnlyAndIgnoreRevocationUnknownErrors RegKey.
    Do you have an idea what might go wrong?

    Kind regards
    Georg

      1. Yes, the GPO is also applied to the VDA (it’s currently only a lab environment with one VDA to test the FAS feature).

        VDA Version is 7.13 on Server 2012R2.

        The only thing I can see in the Event Viewer on the VDA are audit Success events in the Security Log in this order:
        Event 4624 Logon: An account was successfully logged on
        Event 4648 Logon: A logon was attempted using explicit credentials
        Event 4624 Logon: An account was successfully logged on
        Event 4624 Logon: An account was successfully logged on
        Event 4672 Special Logon: Special Privileges assigned to new logon
        Event 4672 Special Logon: Special Privileges assigned to new logon

        and after a short time (if I don’t enter anything in the windows Logon Screen) three Logoff Events:
        Event 4634 Logoff: An account was logged off
        Event 4634 Logoff: An account was logged off
        Event 4634 Logoff: An account was logged off

        Also I checked what happens, if I disable SAML authentication on Storefront and log on explicitly with Username/Password of the VDA Domain. Then passthrough is working without any issue. So most probably it’s not a general configuration issue with my VDA environment/receiver.

        Kind regards
        Georg

        1. Then you might have to call Citrix Support so they can review your configuration. Let me know what they find out.

  13. Hi Carl,
    I was wondering if it is possible to use the netscaler as a SP for multiple IDPs.
    Right now we browse to our netscalerfqdn and get redirected to the IDP.
    We want to browse to our netscalerfqdn/someuniquepageperIDP to redirect to a specific IDP to be able to connect via user@example.com and user@anotherexample.com on the same netscaler.

    1. AAA? Or NetScaler Gateway?

      You might be able to do a Responder policy that redirects you to a iDP that can do an iDP Initiated Flow.

      Or I wonder if you can add an expression to the SAML Auth Policy that uses the URL to select the correct SAML Policy. However, NetScaler might strip off the URL path before evaluating auth policies.

      1. Hi Carl,
        I tried out a bit and I think I got a working solution for us based on your feedback about the URL based SAML policy. I created multiple policies based on the Host header since url only takes the /vpn/index.html part and querystrings apparently fail. So now we got customer1.somewhere.com and customer2.somewhere.com, each with their own saml policy.
        Thanks for all the feedback!

  14. Hi Carl,
    I followed your guide to configure SSO via netscaler 11.1 in POC.
    We can login to the netscaler via ADFS 3.0 but when starting an applications it failed.
    I get an error on the storefront server:
    Failed to launch the resource ‘Controllers.Notepad’ using the Citrix XML Service at address ‘??’. An unknown error occurred interacting with the Federated Authentication Service.
    And a bit further down in the eventdescription:
    Could not contact any Federated Authentication Servers
    Do you have any idea?

      1. Wow, I feel stupid now. I did apply the GPO to our vda’s and delivery controllers but didn’t check our storefront server. It wasn’t in the same OU.
        Thanks for the help and the great guide!

  15. Great article 🙂 I use OTP (safenet) instead of SAML to authenticate users on Netscaler and put in place FAS to get access to the virtual desktop with cert based auth. Despite the fact auth is successful on Netcaler (with no SSO on web resources similar as you asked for SAML), it fails on Storefront with eventid 7 (CitrixAGBasic single sign-on failed because the credentials failed verification with reason: Failed) and eventid 10 (A CitrixAGBasic Login request has failed) with the very common message “cannot complete your request”. Storefront is set with an auth method of “passthrough ffrom netscaler” with credential delegated to Netcaler and auth type of “security token”. I thought that, once auth was successful on Netscaler, it will be straightforward to deal with FAS, but I guess cert based auth is triggered only when you connect on a resource displayed on Storefront, not before right? I’m stuck: any idea of what I miss? Thanks.

  16. Hi!

    If we have an external iDP and use Netscaler as SP, do we need FAS to enable users to connect through the Netscaler to Storefront?

    Currently users get redirected from Netscaler to iDP and then to the Storefront which gives the “cannot complete request”, and the event log says the password for the user failed to meet complexity requirements.

    1. In StoreFront, you can select the option to completely delegate authentication to NetScaler Gateway. You also need Trust XML enabled on your Controllers. This should get you the list of icons, but you it won’t log you into the VDA automatically without FAS.

  17. Carl, I would like to limit the need for domain users connecting remotely to need to enter a username and password to connect. I was thinking Certificate Based Authentication would work in this Scenario. I would also be placing a 2nd factor authentication behind the first (duo security). Would this solution above allow me to do this or facilitate the rollout of it?

    1. As long as you can send the username to StoreFront then it should work. If doing NetScaler, NetScaler needs to send the username (UPN) to StoreFront. Can you get the username from your NetScaler authentication methods? Maybe extract the UPN from the certificate?

      StoreFront will then do the Callback to NetScaler Gateway and create a Federated Authentication Service certificate.

  18. hi carl. is there a way, to get FAS working with Citrix Receiver SelfService, so that i can start a published Application from a Win10 Client directly from startmenue? With Smartcard and FAS we have the problem that the Windows Logon Window from the published App will open, to ask again our credentials. Is there anything to get this use case to working?

    1. It should be possible to use Smart Card to log into the VDA. Is the Smart Card driver installed on the VDA? Do you have Pass-through auth configured on Receiver so it captures the pin? There are several Smart Card guides on the Internet. Smart Cards don’t need FAS.

      1. hi carl, yes smart card driver is on vda installed. the major goal is, that we must use the native receiver with FAS, and to open a published Application from the Client´s Startmenue without Prompt again for Credentials. i am not sure, if that is technical feasible. did you know that?

  19. Please share the link to setup NetScaler AAA and configure with XenApp\XenDesktop for app launch. It will help us to login into StoreFront via NetScaler AAA and launch apps.

    1. I just added a some links to other NetScaler articles for Session Policies and Gateway. Is that what you’re looking for?

  20. Hi Carl-

    A few questions regarding this deployment that I hope you can answer:

    * Can we limit how long those virtual smart cards are active for?

    * The CA creates a virtual smart card and passes it over to the FAS, is that correct? So both have a copy of the virtual smartcard. If so, what security risks are involved and how do we limit this?

    * Once a user a logs into the VDA (desktop) with the virtual smartcard , any other App requiring SSO inside the VDA should work or do they need to authenticate again? Is it using the in-session certificate of the same virtual smart card? Again, can we limit to have it deleted after log off?

    *Also, when we enable FAS on the storefront, users internally who login, would they have a virtual smart card created too? Can we limit this?

    Thanks,
    Bob

    1. By default, the smart cert certificate is only used for VDA logon. There’s a GPO setting to keep it past the logon so the certificate can be used for other cert-auth-based systems.

      Once logged into the VDA, the user should now have a Kerberos TGT, which can be used for Kerberos authentication to other systems.

      I think Federated Authentication Service is enabled for an entire store, no matter how connected. You could use different stores or different StoreFront servers.

      1. Thanks, Carl! Also, when it says XenDesktop 7.9 or newer is required, does that mean VDAs only, or does the delivery controllers have to be updated, as well?

        1. I think it’s StoreFront, VDAs, and Controllers. It’s Controllers that create the authentication ticket for the VDA. I suspect there’s something FAS specific in the VDA authentication mechanism from the Controllers.

      2. Fantastic article Carl, I used this guide to setup a test environment:

        Corporate SSO solution as a SAML IdP
        NetScaler as a SAML SP
        StoreFront configured to delegate authentication to NetScaler
        FAS to tie up the StoreFront / VDA single-sign-on

        I have only come across one issue which you seem to touch on above.

        We have published Remote Desktop as a launchable Citrix app (MSTSC.EXE)
        We have a GPO to allow default credential delegation for TERMSRV/*
        The user *definitely* has a Kerberos TGT – KLIST confirms it
        The TERMSRV/* GPO is applied to the registry of the VDA

        … but the published Remote Desktop app won’t allow the user to login without prompting for credentials.
        I presumed with a TGT the user could get any ticket for any service they want.

        If Kerberos delegation of default credentials isn’t an option, I wonder if there is anyway to use the FAS pseudo “smart card” certificate to allow single-sign-on to the Remote Desktop servers.

          1. Yes it is – assuming you mean the checkbox related to in-session settings within the FAS GPO?

            In-session Certificates = Enabled
            Prompt Scope = No Consent Required
            Consent timeout (seconds) = 300
            Disconnect on lock = Disabled

            This GPO is applied to the FAS and the VDA

            I presumed that, with this enabled, some sort of smartcard certificate would be visible in the MMC Certificates (Personal) snap-in, but there’s nothing there.

          2. Hey Carl, I’m having the same issue where SSO to remoteapps isn’t working after implementing FAS. I can see the FAS certificate inside the session, but am still unable to SSO into remoteapps. Just wondering if you’ve seen this working before? Using FAS and still being able to SSO to remoteapps.

          1. No – I only found reference to the Remote Desktop client requiring that the user logon with a real password, not a smartcard. Despite Kerberos delegation being in place, I think a password is still required for the client logon.

            From https://techcommunity.microsoft.com/t5/Enterprise-Mobility-Security/How-to-enable-Single-Sign-On-for-my-Terminal-Server-connections/ba-p/246523

            “What are the limitations when using Single Sign-on?
            […]
            Single Sign-on only works with Passwords. Does not work with Smartcards. “

          2. Yikes… that is super unfortunate. I was able to get the certificate to show up in MMC by both setting up the GPO you talked about as well as ticking a box in the User Setup portion of the FAS GUI. But it does not appear as an option when connecting with RDP.

  21. We are testing SAML and having an issue with Receiver SSO.

    When logging into a desktop VDA via Netscaler with SAML, Receiver SSO doesn’t work to access XenApp apps from the desktop VDA. Apps launch but users get windows login prompt when launching app. This doesnt happen if the Netscaler uses LDAP login to desktop VDA or if users login to desktop VDA via Storefront.

    1. That’s an interesting point since Reciver doesn’t have the user’s password. I assume browser to StoreFront from inside the session works fine?

      1. I dont have this working yet but I am guessing after reading into it more we need to enable Kerberos for Citrix Receiver – https://docs.citrix.com/en-us/receiver/windows/4-6/secure-connections/ica-kerberos-sspi-v2.html. Existing policy enables SSO for Reciever but no Kerberos. The documentation isn’t clear which machines we need to enable “trust this computer for delegation”. Is this on Storefront Servers? Delivery Controllers? XenDesktop VDA? XenApp VDA? Some combination of those?

        Users login to Windows 10 XenDesktop VDA via SAML and launch XenApp Apps from Server OS VDA running on Windows 2012 R2.

      2. Carl, we are having exactly same issue. We are able to launch publsihed desktop through Netscaler SAML authentication, after setting FAS service and enabling GPO for FAS in VDA side, published desktop launches and SSO automatically. But Receiver configured in VDA is not SSO to Storefront site and it prompts for ID and password.

        Netscaler external URL and Storefront Service site configured in VDA is internal.

        When I remove FAS GPO at VDA, Receiver SSO works as expected.

        1. Since Receiver doesn’t have access to the user’s password, SSON to Receiver inside the VDA will not work. I don’t have a workaround for this.

  22. Hi Carl,

    I have configured an environment with this guide but when I click the application into Storefront i received this error: Citrix Receiver cannot connect to the server. Please refer to the Citrix Knowledge Center article on configuring local access for HTML5.
    Have you an idea?

    Thank you

    Silvio

    1. Are you internal?

      Do you have Receiver installed on the endpoint machine? If so, in the browser, click your name on the top right, and click Change Receiver. Make sure you click the blue button to detect Receiver.

      1. I have configured a SAML login with OneLogin and NetScaler ADC 11.1; The login it’s ok but when I launch any applications I receive this error.
        The HTML5 access is wanted. In case that I use the Citrix Receiver installed into my machine I receive this error:
        Cannot connect to the Citrix XenApp server. The Citrix SSL server you have selected is not accepting connections

        Thank you

        1. This looks like an issue with the StoreFront/NetScaler Gateway configuration. STAs are identical on both StoreFront and NetScaler Gateway? The Gateway address is actually reachable from your client machine? ICA Proxy is enabled on your Gateway?

          I don’t think this is related to SAML or FAS.

        2. Also, I’ve seen security software (e.g. proxies, packet inspection devices) interfere with Citrix connections.

  23. We want to use keycloak claim to authenticate against xenapp. I think this can be done using FAS without integration with netscalar. Could you please suggest?

      1. Yes i am able to get the user name from keycloak by using oauth token. I have code that returns the username and i have tested that code with magicauthentication sample deployed in storefront. I understand that can give me certificate for the user and i have setup FAS as well. Plan is to user custom FAS claims factory, get user name from keycloak and get certificate from FAS. But struggling to make custom claims factory sample.

        1. This is beyond me. If you post to Citrix Discussions, the StoreFront Product Managers sometimes respond. Or Citrix Consulting can help you with your code.

  24. Can i use federated authentication service without netscalar? We need to authenticate user with oAuth token from keycloak. is there any way without using netscalar?

    1. If you can authenticate with StoreFront, then FAS will be used.

      StoreFront currently supports Kerberos, or password, or a NetScaler Gateway trust relationship. Maybe some custom code can enable other auth scenarios.

      1. I have deployed custom FAS citrix authentication sample and have performed all FAS specific configurations but not able to make the custom FAS sample run. Like magicword atuthentication i am able to deploy and enable it from storefront administration. Could you please guide me to some document that talks about FAS without netscalar?

  25. Hi Carl,

    If we have users in xyz.com domain and SAML IDP is also in the same domain.

    All XenApp, FAS & Netscaler are in abc.com domain.

    Do we need a shadow account in abc.com domain with same user name as in xyz.com domain?

    Regards,
    Ranveer

    1. Yes. The shadow accounts need the same UPN as the user’s email address, or whatever UPN/email the iDP is sending to the SP.

  26. Hey Carl,

    Great article! We followed these instructions to the letter, but we are having an issue: after authenticating at the IdP, the SAML assertion is received properly by the Netscaler (NS) (confirmed with logs), but we are getting a “Error: Not a priviledged user.” message on the browser. We are doing everything as you outlined here, with the only difference is we are using NS version 10.5. Do you know if this config will work with that version, or do we need to upgrade to 11.x?

    Cheers,
    Jim.

      1. We are using PingFederate as the IdP…and the NS logs show the SAML being received, the signature digest validated successfully, and the username is extracted from the SAML assertion. Then we get two “SSLVPN Message 25742 0 : “AAA Client Handler: Found extended error code 589826″” in the log…which is right about when the users gets the privileged user error.

          1. Your suggestion of setting the “Default Authorization Action = ALLOW” did the trick. Thanks a bunch!

  27. Hi Carl-

    I have this working with username and password with ADFS being my iDP.

    How would I enable this for smart cards using ADFS?

    Thanks,
    Bob

    1. I assume there’s some way to add smart card auth to ADFS. The ADFS generates the SAML token and NetScaler/FAS consumes it. Shouldn’t be anything different on the Citrix side. You won’t need the smart card to log into the VDA since FAS takes care of it.

  28. Hi Carl,

    Will the 3 FAS certificates will work with Windows Server 2003 Certificate Authority Services.

    Citrix_RegistrationAuthority_ManualAuthorization
    Citrix_RegistrationAuthority
    Citrix_SmartcardLogon

    1. They are created using the Win2003 version of the templates so they might work. But of course, 2003 is not supported.

  29. Technically are there any restrictions that do not allow the same group of XenApp servers (Delivery Controller, Store Front and VDA) to be configured to support both FAS and AD domain login concurrently?

    1. I’m not aware of any limitation. I recently did this at a Customer that wanted to minimize the number of VMs.

    2. However, since users connect to VDAs, you probably don’t want users to have access to Federated Authentication Service, which can create logon certificates for anybody in the domain.

    3. Let’s assume that Citrix resources are bound to a customer resource domain, while customer is still authenticated on his regular account domain, i.e. XenDesktop backend servers and front-end desktops are part of vdi.local domain while customer is authenticated on virtual desktop desk00x.vdi.local with james@acme.corp. In which domain would you install the federation server?

      1. The primary goal of Federated Authentication Service is to login to the VDA. So FAS needs to create certificates for AD accounts that are trusted by the VDA.

  30. Hi Carl-

    I’m using ADFS with our NetScaler 11.1 to for the federated service. When I log into the NetScaler with our smart card, it hits the iDP login page with an error. This is the following error I see under Event Viewer in ADFS:

    Exception details:
    System.UriFormatException: Invalid URI: The format of the URI could not be determined.
    at System.Uri.CreateThis(String uri, Boolean dontEscape, UriKind uriKind)
    at Microsoft.IdentityServer.Web.Protocols.Saml.SamlSignInContext.Validate()
    at Microsoft.IdentityServer.Web.Protocols.Saml.SamlProtocolHandler.GetRequiredPipelineBehaviors(ProtocolContext pContext)
    at Microsoft.IdentityServer.Web.PassiveProtocolListener.OnGetContext(WrappedHttpListenerContext context)

    Any help would be much appreciated.

    Thanks

      1. Hi Carl,

        I have the exact same issue. What do you mean with the ‘issuer name’ might not match? How can I correct

        1. In ADFS, edit the Relying Party. One of the tabs has a field for entering the Service Provider Issuer Name.

          On NetScaler, edit the SAML Policy/Profile. There’s a field for Issuer Name. Both NetScaler and ADFS must have the same Issuer Name configured.

  31. Hi Carl,

    We have setup FAS in our environment and successfully authenticated the users using Saml, but from last 2 months we noticed that some random users while launching the Desktop gets Struck at Welcome screen. After a rebooting the app server, the sessions just works fine. Could you please help us on this.

  32. Hi Carl,

    I believe you have a small error in your text under saml gateway configuration, it says:

    Import a certificate with private key for SAML assertion verification. You’ll also need to import this certificate (without private key) on your SAML iDP. The SAML iDP will use this certificate to sign the SAML assertions. NetScaler will then use the private key to verify the SAML signatures.

    This should be the other way around, the private key is always used to sign, and the public key is used to verify the signature. So the private key of the Netscaler signing certificate should be used to sign the SAML Request and the private key of the IDP(/ADFS) should be used to sign the SAML Response. (Your explanation is right for encryption of the saml response, this would be done with the public key of the Netscaler certificate, and can then only be decrypted with it’s private key.)

    Kind regards,
    Enrico Klein

    1. Once you’re connected to a VDA, you can use any app on the VDA. Or are you saying that your app requires additional authentication?

      1. some applications require another type of authentication that is not LDAP, Password Manager before it could, FAS can do the same?

        1. If NetScaler Gateway receives the user’s UPN, then it can send it to FAS to complete the authentication process.

  33. Hi Carl,

    I tested a configuration with OneLogin.
    After entering the credentials in the OneLogin page I get redirected to the StoreFront site. But the I get an Storefront error “request cannot be completed”.
    On the DDC&StoreFront-Server I realized some Errors in “Citrix Delivery Services”-EventVwr which are indicating that domain and password are missing (see below).
    At the CA there is no certificate created and FAS server shows no error message.
    I think the communication from StoreFront to FAS server is missing. The GPO is configured correctly.
    What else should I check?

    Event ID: 2 Source: Citrix Authentication Service Level: Error
    Access is denied. Contact your system administrator.
    Citrix.DeliveryServices.Security.Authentication.Exceptions.MissingDomainException, Citrix.DeliveryServices.Security, Version=3.6.0.0, Culture=neutral, PublicKeyToken=e8b77d454fa2a856
    The domain of the credential cannot be determined.
    at Citrix.DeliveryServices.Security.Authentication.UserInfo.Parse(String username, String domain, String defaultDomain, String password, Nullable`1 passwordExpired)
    at Citrix.DeliveryServices.Authentication.CitrixAGBasic.Controllers.CitrixAGBasicController.AuthenticateWithoutPassword(String username, String domain, AccessInfo accessInfo)
    at Citrix.DeliveryServices.Authentication.CitrixAGBasic.Controllers.CitrixAGBasicController.Authenticate()

    Event ID: 2 Source: Citrix Authentication Service Level: Error
    Access is denied. Contact your system administrator.
    Citrix.DeliveryServices.Security.Authentication.Exceptions.MissingDomainException, Citrix.DeliveryServices.Security, Version=3.6.0.0, Culture=neutral, PublicKeyToken=e8b77d454fa2a856
    The domain of the credential cannot be determined.
    at Citrix.DeliveryServices.Security.Authentication.UserInfo.Parse(String username, String domain, String defaultDomain, String password, Nullable`1 passwordExpired)
    at Citrix.DeliveryServices.Authentication.CitrixAGBasic.Controllers.CitrixAGBasicController.AuthenticateWithoutPassword(String username, String domain, AccessInfo accessInfo)
    at Citrix.DeliveryServices.Authentication.CitrixAGBasic.Controllers.CitrixAGBasicController.Authenticate()

    1. You didn’t mention NetScaler Gateway.

      Make sure the SAML Name ID matches a userPrincipalName in your local domain.

      1. Thanks Carl,

        I rechecked the SAML Name ID in OneLogin configuration and found some misspelling.
        Now everythink works fine.

        Regards
        Oliver

  34. After installing the Certificate templates, All servers and workstations (ones that have nothing to do with Xenapp) are now requesting the Citrix_RegistrationAuthority_ManualAuthorization certificate. How do we prevent that or is this normal?

  35. I keep getting “The term ‘Get-STFStoreService’ is not recognized as the name of a cmdlet, function, script file, or operable program.” when I get to the storefront configuration. I’m on Storefront 3.6.0.33

        1. Run the command with a & in front of it?

          & “C:\Program Files\Citrix\Receiver StoreFront\Scripts\ImportModules.ps1”

          Also run get-modules and make sure Citrix.StoreFront.Stores is in your list.

          1. I ran that command and it worked, but when I run “get-modules”, that also comes back with the same error “not recognized”

          2. The Citrix.Storefront.Stores is not in the list unfortunately. How do I import that module aside from the importmodules.ps1?

          3. Maybe you have a bad installation of StoreFront. If you call Support, they can help you fix your installation.

  36. I have followed the steps, and my account is a local admin on the FAS server and a Domain Admin. But for some reason when i try to open the FAS console it prompts me for a login after passing the FAS server list. It never accepts my credentials and i cannot proceed. Is the anything i am missing.

        1. Right Click on FAS app and click run as administrator even if you logged in using the admin credentials.

  37. “Import a certificate with private key for SAML assertion verification. You’ll also need to import this certificate (without private key) on your SAML iDP. The SAML iDP will use this certificate to sign the SAML assertions. NetScaler will then use the private key to verify the SAML signatures.”

    Is this a different certificate from the one bound to the NSG VIP?

    1. It can be the same. But most use self-signed certs. The important part is that NetScaler uses the private key to sign the iDP Auth Request. Then iDP uses the public key to verify it came from the NetScaler.

  38. Thank you Carl, but for the smartcard process, I research also the possibility to use the name mapping with smartcard. Have you a documentation for that process, thank you in advance.

  39. Hello Carl,
    Is there a possibility to use Xenapp or Xenapp and Storefront with smartcard authentication ? But I search a mode without ADFS. Do you have information for that ?

  40. We did manage to get it working, at least to the point of applications enumerating in Storefront but ran in to an issue with XML not trusted.

    1. Hi Tom, you need to run following command (powershell) on your DDC’s
      “Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true”

  41. Hi Carl,

    did you also test NS 11.1.47.14?

    It seams that there are many changes in SAML dialogs.

    Regards
    Oliver

    1. Thanks for reminding me.

      I also noticed that the SHA256 configuration was missing so I added it.

  42. I have followed the steps using shibboleth as my idp, but getting a error when redirection happens from IDP page, getting the error unsupported mechanism found in assertion. Are you aware of this problem

    1. What build of NetScaler?

      You might be able to use Fiddler to trace the SAML communication. Maybe something unsupported by NetScaler? 11.1 adds some new SAML features.

    1. I’ve seen some comments indicating that any auth to StoreFront will kick in FAS but I haven’t seen any instructions for it yet. Otherwise, all documented procedures include Gateway.

  43. Hi Carl – Very nicely done. I’m struggling to make it work with OKTA. XD79, SF36, NS11.1.47.14

    1. Getting an error regarding SAML auth with OKTA:
      SAML Assertion verification failed; Please contact your administrator

      SAML Tracer in Firefox:

      tom@mycorp.com

      Looks like Name ID isn’t matching up??

      1. Did you manage to get this working? Ours is working fine currently with the same environment as yours. We even managed to get it working on SHA256 by creating our own custom OKTA App and using the NS advanced options for SAML. Otherwise the default option for NS and the Native OKTA app are both SHA1. The time I’ve seen errors in the assertion have been when there was a mismatch in the encryption or mis-typed values in either NS or OKTA. I’d be curious to see the full error.

  44. Hi Carl,

    The article give by Citrix is a half baked one regarding netscaler and ADFS on windows 2012R2.Can you provide more info if you have any

  45. Great work! I’m wondering how to configure the relying party trust on ADFS? Do you have any steps on that?

  46. Hi Carl, great work by the way

    you mention in the post the requirements are

    Microsoft Certificate Authority in Enterprise mode
    XenApp/XenDesktop 7.9
    StoreFront 3.6
    NetScaler Gateway
    Receiver for Web only. Receiver Self-Service doesn’t support web-based authentication.

    Then it gets to the bottom and you show a screen for an ADFS server?

    I take it thats a requirement also for this to work?

    best regards

    Phil

    1. I was just using ADFS as an example SAML iDP. You can use any SAML iDP (e.g. Okta, Ping, etc.).

Leave a Reply

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