Citrix Federated Authentication Service (SAML) 7.14

Last Modified: Jul 11, 2017 @ 8:57 am

Navigation

This article applies to Federated Authentication Services versions 7.14, 7.13, 7.12, 7.11, and 7.9.

Overview

Citrix Federated Authentication Service enables users to login to NetScaler Gateway and StoreFront using SAML authentication.

Citrix Federated Authentication Service uses Microsoft Certificate Authority to issue certificates on behalf of users. These certificates are used for the StoreFront and Virtual Delivery Agent logon process.

Requirements:

  • Microsoft Certificate Authority in Enterprise mode
  • XenApp/XenDesktop 7.9 or newer
  • StoreFront 3.6 or newer
  • NetScaler Gateway. Note: StoreFront 3.9 and newer also supports SAML authentication natively without NetScaler.
  • Receiver for Web only.
  • Receiver Self-Service for Windows 4.6 and newer supports SAML auth when connecting to StoreFront native SAML without NetScaler.

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.

Install 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 XenDesktop 7.9 or newer ISO, and run AutoSelect.exe.
  2. In XenDesktop 7.13 and newer, in the lower half of the window, click Federated Authentication Service.
  3. Or in XenDesktop 7.9 through 7.12, on the bottom right, click Federated Authentication Service.
  4. In the Licensing Agreement page, select I have read, understand, and accept the terms of the license agreement, and click Next.
  5. In the Core Components page, click Next.
  6. In the Firewall page, click Next.
  7. In the Summary page, click Install.
  8. In the Finish Installation page, click Finish.

FAS Group Policy

  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, run gpupdate.
  10. 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 from domain B to the Windows Authorization Access Group on Domain B.  💡
  11. By default, the VDAs will verify the certificates aren’t revoked by downloading the Certificate Revocation List. You can disable this 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.

FAS Configuration

  1. From the Start Menu, run Citrix Federated Authentication Service as administrator. Make sure you run it elevated.
  2. The Federated Authentication Service FQDN should already be in the list (from group policy). Click OK.
  3. In Step 1: Deploy certificate templates, click Start.
  4. Click OK to add certificate templates to Active Directory. Sufficient permission is required.
  5. In Step 2: Setup Certificate Authority, click Start.
  6. Select a Certificate Authority to issue the certificates, and click Ok.
  7. In Step 3: Authorize this Service, click Start.
  8. 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.
  10. Step 3 is now yellow.
  11. Go to the Certificate 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. If it doesn’t turn green, then there might be a private hotfix. See David Lloyd at Citrix Discussions.
  13. Another user at XenDesktop 7.9 FAS at Citrix Discussions had to bump up the Validity Period of the Citrix_RegistrationAuthority_ManualAuthorization template to 2 days before it would authorize.
  14. After authorization, switch to the User Rules tab.
  15. Use the Certificate Authority drop-down to select the issuing Certificate Authority.
  16. Use the Certificate Template drop-down to select the Citrix_SmartcardLogon template.
  17. Click Edit next to List of StoreFront servers that can use this rule.
  18. 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.
  19. On the bottom half, make sure Assert Identity is Allowed. Click OK.
  20. By default, all users and all VDAs are allowed. You can click the other two Edit boxes to change this.
  21. When done, click Apply.
  22. Click OK when Rule updated successfully.
  23. 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

  1. On the StoreFront 3.6 or newer server, run the following elevated PowerShell command:
    & "$Env:PROGRAMFILES\Citrix\Receiver StoreFront\Scripts\ImportModules.ps1"
  2. 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"
  3. If you have multiple StoreFront servers, Propagate Changes.
  4. On a XenDesktop Delivery Controller, run the following commands:
    asnp citrix.*
    Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true

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

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

NetScaler Gateway Config

SAML on NetScaler Gateway 11.1

If NetScaler 11.0, see SAML on NetScaler Gateway 11.0.

ADFS-specific Links:

Configure the SAML iDP:

  1. In your SAML iDP, create a Relying Party Trust (aka service provider trust).
  2. NetScaler doesn’t have a SAML metadata service, but you can create a metadata file manually by following the instructions at Citrix CTX133919 How to Configure NetScaler SAML to Work with Microsoft AD FS 2.0 IDP.
  3. Otherwise, select the option to enter relying party data manually.
  4. For the Assertion Consumer Service URL (aka relying party service URL), enter the URL to your NetScaler Gateway with /cgi/samlauth appended to the end (e.g. https://gateway.corp.com/cgi/samlauth)
  5. Enter a Relying party trust identifier. You must specify the same identifier (Issuer Name) on the NetScaler as detailed soon.
  6. Configure the SAML iDP to send email address or User-Principal-name as Name ID. NetScaler 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.
  7. NetScaler will sign the authentication requests it sends to the iDP. On the NetScaler, you will soon configure the NetScaler signing certificate with private key that signs the requests. In your SAML iDP, import the same NetScaler signing certificate but without private key.
  8. Copy the SAML authentication URL (aka Token Issuance URL) from your SAML iDP. You’ll need to enter this same URL on your NetScaler later.
  9. Export the iDP Token-signing certificate from your SAML iDP. The iDP could be ADFS, Okta, Ping, etc.

Configure the NetScaler:

  1. On NetScaler, import the iDP SAML token-signing certificate (without private key) under Traffic Management > SSL > Certificates > CA Certificates. NetScaler uses this certificate to verify the signature of the SAML assertion from the iDP.

  2. Import or create a NetScaler SAML signing certificate with private key for signing of SAML authentication requests to the iDP. This can be the same certificate used on NetScaler Gateway. Or a more common practice is to create a self-signed certificate.
  3. You’ll also need to import this NetScaler SAML signing certificate (without private key) to your SAML iDP so it can verify the SAML authentication request signature from the NetScaler.
  4. Go to NetScaler Gateway > Policies > Authentication > SAML.
  5. On the right, switch to the Servers tab, and click Add.
  6. Enter the information for authenticating with your SAML iDP. This configuration will vary depending on your SAML iDP.
  7. For iDP Certificate Name, select the SAML iDP’s certificate that was exported from the SAML iDP and imported to NetScaler. NetScaler will use this iDP certificate to verify SAML assertions from the iDP.
  8. For Redirect URL, enter the URL to the SAML iDP’s authentication page. NetScaler 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 iDPs, get the URL from your iDP.
  9. For Signing Certificate Name, select the NetScaler certificate (with private key) that NetScaler 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.
  10. Enter an Issuer Name 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.
  11. Click More.
  12. NetScaler defaults to SHA1. You might have to change the Signature Algorithm and Digest Method to SHA256.
  13. Review the other settings as needed by your iDP. Click Create when done.
  14. On the right, switch to the Policies tab, and click Add.
  15. Give the policy a name, select the SAML Server, and enter ns_true for the expression. Click Create.
  16. If you haven’t created your Session Polices yet, then see http://www.carlstalhood.com/session-policies-for-storefront-netscaler-11-1/.
  17. Edit your Session Policy/Profile. On the Published Applications tab, make sure Single Sign-on Domain is not configured.
  18. If you haven’t created your Gateway Virtual Server yet, then see http://www.carlstalhood.com/netscaler-gateway-11-1-virtual-server/.
  19. Edit your Gateway Virtual Server. Go to the Basic Authentication section, and add a policy.
  20. Bind the SAML policy. This is the only authentication policy you need. You can remove all other authentication policies.

  21. Next step: configure StoreFront for SAML NetScaler Gateway.

SAML on NetScaler Gateway 11.0

If NetScaler 11.1, see SAML on NetScaler Gateway 11.1.

ADFS-specific Links:

Configure the SAML iDP:

  1. In your SAML iDP, create a Relying Party Trust (aka service provider trust).
  2. NetScaler doesn’t have a SAML metadata service, but you can create a metadata file manually by following the instructions at Citrix CTX133919 How to Configure NetScaler SAML to Work with Microsoft AD FS 2.0 IDP.
  3. Otherwise, select the option to enter relying party data manually.
  4. For the Assertion Consumer Service URL (aka relying party service URL), enter the URL to your NetScaler Gateway with /cgi/samlauth appended to the end (e.g. https://gateway.corp.com/cgi/samlauth)
  5. Enter a Relying party trust identifier. You must specify the same identifier (Issuer Name) on the NetScaler as detailed soon.
  6. Configure the SAML iDP to send email address or User-Principal-name as Name ID. NetScaler 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.
  7. NetScaler will sign the authentication requests it sends to the iDP. On the NetScaler, you will soon configure the NetScaler signing certificate with private key that signs the requests. In your SAML iDP, import the same NetScaler signing certificate but without private key.
  8. Copy the SAML authentication URL (aka Token Issuance URL) from your SAML iDP. You’ll need to enter this same URL on your NetScaler later.
  9. Export the signing certificate from your SAML iDP. The iDP could be ADFS, Okta, Ping, etc.

Configure the NetScaler:

  1. On NetScaler, import the iDP SAML signing certificate (without private key). NetScaler uses this certificate to verify SAML assertions from the iDP.

  2. Import or create a NetScaler SAML signing certificate with private key for signing of SAML authentication requests to the iDP. This can be the same certificate used on NetScaler Gateway. Or a more common practice is to create a self-signed certificate.
  3. You’ll also need to import this NetScaler SAML signing certificate (without private key) to your SAML iDP so it can verify the SAML authentication request signature from the NetScaler.
  4. Go to NetScaler Gateway > Policies > Authentication > SAML > Servers, and click Add.
  5. Enter the information for authenticating with SAML. This configuration will vary depending on your SAML iDP.
  6. For iDP Certificate Name, select the SAML iDP’s certificate that was exported from the SAML iDP and imported to NetScaler. NetScaler will use this iDP certificate to verify SAML assertions from the iDP.
  7. For Redirect URL, enter the URL to the SAML iDP’s authentication page. NetScaler 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 iDPs, get the URL from your iDP.
  8. For Signing Certificate Name, select the NetScaler certificate (with private key) that NetScaler 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.
  9. Enter an Issuer Name 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.
  10. Click More.
  11. NetScaler defaults to SHA1. You might have to change the Signature Algorithm and Digest Method to SHA256.
  12. Review the other settings as needed by your iDP. Click Create when done.
  13. On the right, switch to the Policies tab and click Add.
  14. Give the policy a name, select the SAML Server, and enter ns_true for the expression. Click Create.
  15. If you haven’t created your Session Polices yet, then see http://www.carlstalhood.com/session-policies-for-storefront-netscaler-11/.
  16. Edit your Session Policy/Profile. On the Published Applications tab, make sure Single Sign-on Domain is not configured.
  17. If you haven’t created your Gateway Virtual Server yet, then see http://www.carlstalhood.com/netscaler-gateway-11-virtual-server/.
  18. Edit your Gateway Virtual Server. Go to the Authentication section and add a policy.
  19. Bind the SAML policy. This is the only authentication policy you need. You can remove all other authentication policies.
  20. Next step: configure StoreFront for SAML NetScaler Gateway.

StoreFront Config for SAML NetScaler Gateway

  1. In StoreFront 3.6 or newer, right-click the store, and click Manage Authentication Methods.
  2. Make sure Pass-through from NetScaler Gateway is selected.
  3. Click the gear icon on the right, and click Configure Delegated Authentication.
  4. Check the box next to Fully delegate credential validation to NetScaler Gateway, and click OK twice.
  5. In StoreFront, add a NetScaler Gateway object that matches the NetScaler 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

SAML on StoreFront without NetScaler

New in StoreFront 3.9 is native support for SAML Authentication without NetScaler.

Notes:

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

To configure 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), 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. Currently, the only supported configuration is ADFS with SAML to StoreFront without NetScaler.
  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.

161 thoughts on “Citrix Federated Authentication Service (SAML) 7.14”

  1. Is there a possibility to have two FAS servers ? build a loadbalanced FAS, just like any other component is HA in my Citrix,
    Thanks,

  2. Hi Carl

    Can you use a Standalone CA (i.e., not an Active Directory integrated CA) in using FAS, as long as you add the cert of your standalone CA to the Trusted Roots store on your VDAs/Storefront servers?

    Thanks

    1. The Enterprise CA is needed to issue certificates for each user and link them to Active Directory users.

      1. Hi Carl,

        I am totally new to ADFS and would like to learn and get a better understanding of how it can be used for enabling users from Domain A (client domain) to be able to launch a XenApp or XenDesktop session in Domain B (resouce domain) the two domans do not trust each other. Both domains are in the same organization all be it they live in two separate network subnets with a firewall. Can I acheive this using the steps you have shown?

        Thanks!

        1. Yes. If internal only, then StoreFront has native support for ADFS and FAS.

          Note: you must create accounts in Domain B for each of your users. The passwords don’t matter. The Domain B users are for authorization and identity mapping. What SAML does is avoid you having to synchronize passwords between the domains. And when you delete a user from Domain A, it can no longer be used to login to Domain B.

          1. Thanks Carl for your quick reply. I take it I will first need to configure ADFS services on both domains before I proceed with the Citrix configuration steps? If so would you be able to suggest any good blog/guides for configuring ADFS.

          2. So I need only need to configure ADFS in the resource domain. Or is it the client domain which is where the identity and passwords will be provided from? I can’t seem to get my head round this one 🙂

  3. Hi Carl,

    After logging in ADFS opens with an error page. In eventlog:

    Encountered error during federation passive request.

    Additional Data

    Protocol Name:

    Relying Party:

    Exception details:
    Microsoft.IdentityServer.RequestFailedException: MSIS7065: There are no registered protocol handlers on path /adfs/ls to process the incoming request.
    at Microsoft.IdentityServer.Web.PassiveProtocolListener.OnGetContext(WrappedHttpListenerContext context)

    I can open /adfs/ls/idpinitiatedsignon.aspx and I see my relying parties. When selecting NetScaler Gateway I get Http/1.1 Service Unavailable

    Any idea what this could be?

    Thanks

  4. This is a great article Carl. Question after i do the SAML authentication I can see the desktop and published apps. When i launch the application i get the desktop logon screen before federated authentication i was able to launch the app. Can you point me in the right direction.

Leave a Reply