Citrix Federated Authentication Service (SAML)

Last Modified: Jan 13, 2017 @ 7:01 pm

Navigation

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
  • Receiver for Web only. Receiver Self-Service doesn’t support web-based authentication.

Install Service

The service should be installed on a secure, standalone server that does not have any other Citrix components installed.

  1. On the Federated Authentication Service server, go to the XenDesktop 7.9 or newer ISO and run AutoSelect.exe.
  2. On the bottom right, 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. In the Finish Installation page, click Finish.

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 ""

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

NetScaler Gateway Config

SAML on NetScaler Gateway 11.1

If NetScaler 11.0, see SAML on NetScaler Gateway 11.0.

Dennis Radstake SAML authentication for Citrix XenDesktop and XenApp has some ADFS configuration instructions.

  1. Export the signing certificate from your SAML iDP. The iDP could be ADFS, Okta, Ping, etc.
  2. Import the iDP SAML signing certificate (without private key) to NetScaler under Traffic Management > SSL > Certificates > CA Certificates. NetScaler uses this certificate to verify the signature of the SAML assertion from the iDP.

  3. Import a certificate with private key for signing of SAML authentication requests to the iDP. You’ll also need to import this certificate (without private key) on 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 SAML. This configuration will vary depending on your SAML iDP.
  7. For iDP Certificate Name, select the SAML iDP’s certificate (exported from the SAML iDP) that NetScaler will use 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.
  9. For Signing Certificate Name, select the NetScaler certificate (with key) that was imported to the SAML iDP for the Relying Party. NetScaler uses its private key to sign authentication requests to the iDP. iDP uses the public key to verify the signature.
  10. Enter an Issuer Name that the SAML iDP is expecting for the Relying Party.
  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. Edit your Session Policy/Profile. On the Published Applications tab, make sure Single Sign-on Domain is not configured.
  17. Edit your Gateway Virtual Server. Go to the Basic Authentication section, and add a policy.
  18. Bind the SAML policy. This is the only authentication policy you need. You can remove all other authentication policies.

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

Dennis Radstake SAML authentication for Citrix XenDesktop and XenApp has some ADFS configuration instructions.  💡

  1. Export the signing certificate from your SAML iDP. The iDP could be ADFS, Okta, Ping, etc.
  2. Import the iDP SAML signing certificate (without private key) to NetScaler. NetScaler uses this certificate to verify SAML assertions.

  3. Import a certificate with private key that NetScaler will use to sign SAML authentication requests. You’ll also need to import this certificate (without private key) on your SAML iDP so the SAML iDP can verify the SAML authentication requests 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 (exported from the SAML iDP) that NetScaler will use to verify SAML assertions.
  7. For Redirect URL, enter the URL to the SAML iDP’s authentication page. NetScaler Gateway will redirect users to this URL.
  8. For Signing Certificate Name, select the NetScaler certificate (with key) that was imported to the SAML iDP for the Relying Party. NetScaler uses its private key to sign the authentication request to the iDP. iDP uses the public key to verify the signature.
  9. Enter an Issuer Name that the SAML iDP is expecting for the Relying Party.
  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. Edit your Session Policy/Profile. On the Published Applications tab, make sure Single Sign-on Domain is not configured.
  16. Edit your Gateway Virtual Server. Go to the Authentication section and add a policy.
  17. Bind the SAML policy. This is the only authentication policy you need. You can remove all other authentication policies.
  18. Next step: configure StoreFront for SAML NetScaler Gateway.

StoreFront Config for SAML 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.

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.

67 thoughts on “Citrix Federated Authentication Service (SAML)”

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

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

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

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

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

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

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

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

  8. 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?

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

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

  11. “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.

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

  13. 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 ?

  14. 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”

  15. Hi Carl,

    did you also test NS 11.1.47.14?

    It seams that there are many changes in SAML dialogs.

    Regards
    Oliver

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

    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.

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

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

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

Leave a Reply