Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (2024)

Navigation

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

  • Change Log
  • Overview
    • FAS Versions
  • Install/Upgrade FAS Service
  • FAS Group Policy
  • FAS Configuration
  • StoreFront Configuration
  • SAMLConfiguration:
    • SAML Traffic Flow
    • Configure the SAML Identity Provider
      • Azure AD as Identity Provider
      • Microsoft ADFS as Identity Provider
    • Configure Citrix ADC as SAML Service Provider
      • nFactor Method
        • nFactor LDAP Group Extraction
      • StoreFront Configuration for SAML through Citrix Gateway
    • Native SAML on StoreFront 3.9+ without Citrix Gateway/ADC
  • Active Directory Shadow Accounts
  • Verify FAS

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. SeeCTX218941FAS – 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 Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (1)
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (2)
  • 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 CTX225721Federated 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 atHowTo: Active-Active Multi-Datacenter Citrix FAS.
Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (3)

Also see theCitrix Federated Authentication Service Scalability whitepaper.
Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (4)

Federated Authentication Service Versions

The most recent Federated Authentication ServiceCurrent Release is version 2402.

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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (8)
  2. In the lower half of the window, click Federated Authentication Service.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (9)
  3. In the Licensing Agreement page, select I have read, understand, and accept the terms of the license agreement, and click Next.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (10)
  4. In the Core Components page, click Next.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (11)
  5. In the Firewall page, click Next.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (12)
  6. In the Summary page, click Install.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (13)
  7. The installer will probably ask for a restart.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (14)
    1. After the reboot, and after logging in again, you might see aLocate ‘Citrix Virtual Apps and Desktops 7’ installation media window. Don’t click anything yet.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (15)
    2. Go to the Citrix_Virtual_Apps_and_Desktops_7_2402_LTSR.iso file and mount it.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (16)
    3. Go back to theLocate ‘Citrix Virtual Apps and Desktops 7’ installation mediawindow.
    4. On the left, expand This PC, and click the DVD Drive.
    5. Click Select Folder.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (17)

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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (18)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (19)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (20)
  6. Enable the setting and click Show.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (21)
  7. Enter the FQDN of the Federated Authentication Service server. You can add more than oneFederated Authentication Service server.
  8. Click OK twice.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (23)
  9. On the Federated Authentication Service server, and VDAs, run gpupdate.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (24)
  10. On the FAS server, and on VDAs, look in the registry atHKLM\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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (25)
  11. If the VDAs and Users are in different domains, seeCTX220497Users 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. Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (26)
  13. By default, the VDAs will verify the certificates aren’t revoked by downloadingthe Certificate Revocation List. You can disable CRL checking by configuring HKEY_Local_Machine\System\CurrentControlSet\Control\LSA\Kerberos\Parameters\UseCachedCRLOnlyAndIgnoreRevocationUnknownErrors (DWORD) = 1 as detailed atCTX217150Unable to login using the FAS Authentication – Getting Stuck on Please wait for local session manager.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (27)
  14. 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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (28)
  3. In the tab named Initial Setup, in the row named Deploy certificate templates, click Deploy.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (29)
  4. Click OK to deploy the templates to Active Directory.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (30)
  5. In the row named Set up a certificate authority, click Publish.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (31)
  6. Select an Enterprise Certificate Authority that will be issue the FAS certificates and click OK.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (32)
  7. In the row namedAuthorize this service, click Authorize.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (33)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (34)
  9. The row named Authorize this service has a new icon indicating it is waiting on the registration authority certificate to be approved.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (35)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (36)
  11. Back in the FAS Administration Console, on the top right, click Refresh.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (37)
  12. The row named Authorize this service should now have a green check mark.
  13. In the row namedCreate a rule, click Create.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (38)
  14. In the Rule name page, leave it set to Create the default rule and click Next.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (39)
  15. In the Template page, click Next.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (40)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (41)
  17. In the In-session use page, click Next.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (42)
  18. In the Access control page, click the link to Manage StoreFront access permissions.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (43)
  19. In thePermission for StoreFront Servers page, add your StoreFront servers and give them the permission Assert Identity. Click OK.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (44)
  20. Back in the Create Rule wizard, click Next.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (45)
  21. In the Restrictions page, you can optionally reduce the VDAs that are authorized to use FAS. Click Next.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (46)
  22. In the Summary page, click Create.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (47)
  23. The FAS Registration Authority certificate expires in two years. You’ll need to manually renew theFAS Registration Authority certificate before it expires. Put a notification on your calendar.For details, seeRenew 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.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (48)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (49)
  3. The Federated Authentication Service FQDN should already be in the list (from group policy). Click OK.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (50)
  4. In Step 1: Deploy certificate templates, click Start.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (51)
  5. Click OK to add certificate templates to Active Directory. Sufficient permission is required.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (52)
  6. In Step 2: Setup Certificate Authority, click Start.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (53)
  7. Select a Certificate Authority to issue the certificates, and click Ok.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (54)
  8. In Step 3: Authorize this Service, click Start.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (55)
    • 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 atFederated Authentication Service private key protection at Citrix Docs. When runningNew-FasAuthorizationCertificateRequest, the-UseTPM switch is optional.
  9. Select the issuing Certificate Authority, and click OK.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (56)
    • 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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (57)
  11. On the Microsoft CA server, go to the Certification Authority Console > Pending Requests. Find the pending request, and Issueit.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (58)
  12. In a minute or two, Federated Authentication Service will recognize the issued certificate and Step 3 will turn green.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (59)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (60)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (61)
  19. By default, all users and all VDAs are allowed. You can click the other two Edit boxes to change this.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (62)
  20. When done, click Apply.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (63)
  21. Click OK when you seeRule updated successfully.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (64)
  22. The FAS Registration Authority certificate expires in two years. You’ll need to manually renew theFAS Registration Authority certificate before it expires. Put a notification on your calendar.For details, seeRenew 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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (65)
  2. There should be three templates with names starting with Citrix_. Open the properties on each one.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (66)
  3. On the Security tab, highlight each group assigned to the template.
  4. On the bottom half, uncheck the box in theAutoenroll row but leaveEnroll checked. Perform this step for every group assigned to this template. Then clickOK.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (67)
  5. Repeat disabling autoenroll for the other two templates.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (68)

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

  1. Open the Properties of one of theCitrix_RegistrationAuthority certificate templates.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (69)
  2. On theSecurity tab, removeDomain Computers.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (70)
  3. Add your FAS servers and enable theEnroll permission.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (71)
  4. Repeat for the other Registration Authority certificate.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (72)

To further restrict who can be issued certificates, go to your Certificate Authority’s Propertiesand use the Enrollment Agents tab to restrict enrollment agents.
Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (73)
Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (74)

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 atHKLM\Software\Policies\Citrix\Authentication\UserCredentialService\Addressesto 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 $storeSet-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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (75)
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (76)
    • 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 $storeSet-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 theIdentity 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, clickEnterprise applications.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (77)
  3. In the new blade that appears, on the All applications page, on the right, clickNew application.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (78)
  4. In the All Categories view of the gallery, on the top right, clickNon-gallery application.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (79)
  5. Give the application a descriptive name. Azure AD shows this name in the myapps portal. Click Add.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (80)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (81)
  8. In section 1 labelled Basic SAML Configuration, click the pencil icon.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (82)
  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 behttps. 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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (83)
  12. In section 2 labelledUser 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).
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (84)
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (85)
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (86)
  13. In section 3 labelledSAML Signing Certificate, click theDownload link in theCertificate (Base64) line.
  14. Citrix ADC 12.1 and newer support SAML metadata so feel free to copy the App Federation Metadata Url field.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (87)
  15. If you are running NetScaler 12.0 or older, then you will need to copy theLogin URL field from section 4 labelledSet up gateway5.corp.com
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (88)
  16. On the left, underManage, clickUsers and groups.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (89)
  17. Use the normal process to assign Azure AD users and groups to this application. Click Assign.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (90)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (91)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (92)
  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)
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (93)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (94)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (95)
  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 withprivate 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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (96)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (97)
  8. Export the IdP Token-signing certificate from your SAML IdP. The IdP could be ADFS, Okta, Ping, etc.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (98)

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.

    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (99)
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (100)

    • SAML IdP certificates are shown in the Unknown Certificates node.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (101)
  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 andImport 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.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (102)
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (103)
    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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (104)
  6. On the right, switch to the tab labelledServers, and click Add.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (105)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (106)
    1. In the SAML Server on Citrix ADC, in theSAML IDP Metadata URL field, paste in the URL. ADC should be able to extract the IdP’s certificate from the Metadata URL.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (107)
    2. In theIssuer Namefield, 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.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (108)
    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/")

      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (109)

    4. Scroll down and click More.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (110)
    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.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (111)
    6. Scroll down and clickCreate.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (112)
    7. Edit the SAML Server again.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (113)
    8. If you uncheck the box next toImport Metadata, you can see the fields that it filled in for you. Unfortunately, other fields must be configured manually as detailed soon.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (114)
  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.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (115)
    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 theIssuer Namefield, 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.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (116)
    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. 💡
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (117)
    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.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (118)
    8. Citrix ADC defaults to SHA1. You might have to change theSignature Algorithm andDigest Method toSHA256.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (119)
    9. Review the other settings as needed by your IdP. Click Create when done.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (120)

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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (121)
  2. On the right, click the button labelled Add.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (122)
    1. Change the drop-down for Action Type to SAML.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (123)
    2. Change the drop-down for Action to the SAML Action you created earlier.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (124)
    3. In the box labelled Expression, entertrue.
    4. Give the policy a name and click Create.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (125)
  3. In the left menu, expand Security, expand AAA – Application Traffic and then click Virtual Servers.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (126)
  4. On the right, click the button labelled Add.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (127)
    1. Change the drop-down named IP Address Type to Non Addressable and then click OK.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (128)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (129)
  6. On the left, in the section named Advanced Authentication Policies, click the row that says No Authentication Policy.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (130)
    1. Click where it says Click to select.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (131)
    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.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (132)
    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.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (133)
  7. Click Continue,
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (134)
  8. At the bottom of the page, click Done to finish creating the AAA vServer.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (135)
  9. In the left menu, expand Citrix Gateway and click Virtual Servers.
  10. On the right, edit your existing Gateway Virtual Server.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (136)
  11. On the right side of the screen, in the Advanced Settings column, click Authentication Profile.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (137)
  12. On the left side of the screen, find the Authentication Profile section and then click the button labelled Add.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (138)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (139)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (140)

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.0bind 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.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (141)
    2. Check the box next to an existing LDAP policy and click Add to copy its configuration. Or create a new one.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (142)
    3. Change the name of the LDAP Action.
    4. On the top right, uncheck the box next to Authentication.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (143)
    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.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (144)
    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.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (145)
    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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (146)
    1. Change Action Type to LDAP.
    2. Expression = true.
    3. Click Create.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (147)
  3. On the left, go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > Policy Label. On the right, click Add.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (148)
    1. Give the Policy Label a name and click Continue. The Login Schema should be LSCHEMA_INT.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (149)
    2. Select your LDAP Group Extract policy and then on the bottom click Bind.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (150)
    3. Click Done to close the Policy Label.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (151)
  4. On the left, go to Security > AAA – Application Traffic > Virtual Servers. On the right, edit your SAML AAA vServer.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (152)
    1. Click where it says 1 Authentication Policy.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (153)
    2. Right-click the Authentication Policy and then click Edit Binding.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (154)
    3. In the Select Next Factor field, click where it says Click to select.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (155)
    4. Select your LDAP Group Extract Policy Label and then click Bind.
      Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (156)
  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_INTbind 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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (157)
  2. Make sure Pass-through from Citrix Gateway is selected.
  3. Click the bottom gear icon on the right, and click Configure Delegated Authentication.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (158)
  4. Check the box next to Fully delegate credential validation toCitrix Gateway andclick OK twice.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (159)
  5. In StoreFront, add a Citrix Gateway object that matches the FQDN of the Citrix Gateway Virtual Server that has SAML enabled.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (160)
  6. On the Authentication Settings page, make sure you configure a Callback URL. It won’t work without it.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (161)
  7. Then assign (ConfigureRemote Access Settings) the Gateway to your Store.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (162)
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (163)
  8. Next step: createActive 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, seeCTX232042Configure 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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (164)
  2. In StoreFront 3.9 or newer console, right-click a Store, and click Manage Authentication Methods.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (165)
  3. Check the box next toSAML Authentication. If you don’t see this option (because you upgraded from an older version), click theAdvanced button on the bottom of the window, and install the authentication method.
  4. On the right, click the gear icon forSAML, and clickIdentity Provider.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (166)
  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. ClickImport.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (167)
  8. Browse to the signing certificate exported from your IdP, and click Open.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (168)
  9. Then click OK to close the Identity Provider window.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (169)
  10. On the right, in the SAML Authentication row, click the gear icon, and then click Service Provider.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (170)
  11. Click the first Browse button.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (171)
  12. Give the Signing certificate a name, and save it somewhere.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (172)
  13. Click the second Browse button.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (173)
  14. Give the Encryption certificate a name, and save it somewhere.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (174)
  15. Copy the Service Provider Identifier. Or you can change it to your desired value. Then click OK.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (175)
  16. In your IdP (e.g. ADFS), create a Relying Party Trust.
  17. Import the Encryption certificate that you exported from StoreFront.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (176)Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (177)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (178)
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (179)
  20. For the Relying party trust identifier, enter the identifier you copied from the Service Provider window in StoreFront.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (180)
  21. Configure the Claim Rules to send the user’s email address or userPrincipalName as Name ID.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (181)
  22. Edit the Relying Party Trust. Import the Signing certificatethat you exported from StoreFront.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (182)
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (183)
  23. CreateActive Directory Shadow Accounts. Federated users must be userPrincipalName mapped to local Active Directory accounts.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (184)
  24. If you point your browser tohttps://<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 CTX220639How to configure SAML Authentication-Test Configuration.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (185)
  25. See Citrix CTX220682Storefront SAML Troubleshooting Guide for event logs, SAML Metadata, Active Directory account mapping, Trust XML, etc.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (186)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (187)
  27. ADFS also works in Receiver 4.6 and newer, and Workspace app.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (188)
  28. When you logoff, it won’t let you log on again unless you close your browser and reopen it.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (189)
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (190)
  29. To fix this problem, see CTP Sacha ThometStoreFront – Allow relogin without browser close.Edit the file C:\inetpub\wwwroot\Citrix\StoreWeb\custom\script.js, and add the following line:
    CTXS.allowReloginWithoutBrowserClose = true

    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (191)

  30. Now when you logoff, you’re given an option to log on again.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (192)

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 createshadow 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. OpenActive Directory Domains and Trust.
  2. Right-click the top left node (not a domain node), and click Properties.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (193)
  3. In theUPN Suffixes tab, add a UPN suffix that matches the email suffix provided by the SAML IdP.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (194)
  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.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (195)
  6. If the shadow account is already created, edit the account, and on theAccount tab, use the drop-down to select the new UPN suffix.
    Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (196)
  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.V1Get-FasUserCertificate -address fas01.corp.local

Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (197)

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

Citrix Federated Authentication Service (SAML) 2402 LTSR – Carl Stalhood (2024)

References

Top Articles
Latest Posts
Recommended Articles
Article information

Author: Msgr. Refugio Daniel

Last Updated:

Views: 5693

Rating: 4.3 / 5 (74 voted)

Reviews: 89% of readers found this page helpful

Author information

Name: Msgr. Refugio Daniel

Birthday: 1999-09-15

Address: 8416 Beatty Center, Derekfort, VA 72092-0500

Phone: +6838967160603

Job: Mining Executive

Hobby: Woodworking, Knitting, Fishing, Coffee roasting, Kayaking, Horseback riding, Kite flying

Introduction: My name is Msgr. Refugio Daniel, I am a fine, precious, encouraging, calm, glamorous, vivacious, friendly person who loves writing and wants to share my knowledge and understanding with you.