Federated Authentication Service

Overview

The Citrix Federated Authentication Service (FAS) is a privileged component designed to integrate with Active Directory Certificate Services. It dynamically issues certificates for users, allowing them to log on to an Active Directory environment as if they had a smart card. This functionality allows StoreFront to use a broader range of authentication options, such as Security Assertion Markup Language (SAML) assertions. SAML is commonly used as an alternative to traditional Windows user accounts on the Internet.

Note:

To use SAML authentication, configure FAS on the VDA properly.

Starting with CU3, the Linux VDA uses short connections to transmit data with FAS servers.

The following diagram shows FAS integrated with a Microsoft Certification Authority and providing support services for StoreFront and VDAs.

Trusted StoreFront servers contact the FAS when users request access to the Citrix environment. The FAS grants a ticket that allows a single Citrix Virtual Apps or Citrix Virtual Desktops session to authenticate with a certificate for that session. When a VDA needs to authenticate a user, it connects to the FAS and redeems the ticket. Only the FAS has access to the user certificate’s private key. The VDA must send each signing and decryption operation that it needs to perform with the certificate to the FAS.

Requirements

FAS is supported on Windows Server 2008 R2 and later.

• We recommend installing FAS on a server that does not contain other Citrix components.
• The Windows Server must be secured for accessing a registration authority certificate and a private key to automatically issue certificates for domain users and for accessing those user certificates and private keys.

In a Citrix Virtual Apps or Citrix Virtual Desktops Site:

• The Delivery Controllers must be minimum version 7.9.
• The StoreFront server must be minimum version 3.6 (version provided with the XenApp and XenDesktop 7.9 ISO).
• The Linux VDAs must be minimum version 7.18. Verify that the Federated Authentication Service Group Policy configuration has been applied correctly to the VDAs before creating the Machine Catalog in the usual way. For more information, see the Configure Group Policy section in this article.

References:

• Active Directory Certificate Services
  https://social.technet.microsoft.com/wiki/contents/articles/1137.active-directory-certificate-services-ad-cs-introduction.aspx
• Configuring Windows for Certificate Logon
  http://support.citrix.com/article/CTX206156
• Installing the Federated Authentication Service
  Federated Authentication Service

Configure Windows for Certificate Logon

For information on configuring Windows for certificate logon, open Knowledge Center article CTX206156 to download and read the Smart_card_config_Citrix_Env.pdf file (hereinafter “the PDF file”). Perform the following steps according to the PDF file while noting the differences or complements that are given in each step. Pay special attention to the target machine you are operating on, for example, the AD, Delivery Controller, or StoreFront.

Set up a Windows domain (on AD)

Install domain controller roles

See the Installing Domain Controller Roles section of the PDF file.

During installation of the Active Directory Certificate Services, ensure that the following options are selected:

Open http://localhost/certsrv/ to check whether it displays the following welcome page. If yes, the Active Directory Certificate Services are installed successfully.

Prepare the Certificate Authority for smart card usage

No complement. See the Preparing the Certificate Authority for Smart card usage section of the PDF file.

Issue a Domain Controller certificate

No complement. See the Issuing a Domain Controller Certificate section of the PDF file.

Configure Microsoft IIS for HTTPS (on StoreFront)

Configure HTTPS on Microsoft IIS

No complement. See the Configuring HTTPS on Microsoft IIS section of the PDF file.

Non-domain joined computers

See the Non-Domain Joined Computers section of the PDF file.

Retrieve the CA Certificate from the Microsoft CA (on AD)

No complement. See the Retrieving the CA Certificate from the Microsoft CA section of the PDF file.

Install the trusted CA certificate on Windows

No complement. See the Installing the Trusted CA Certificate on Windows section of the PDF file.

Configure Citrix StoreFront (on StoreFront)

Create the store

See the Creating the Store section of the PDF file.

After the preceding IIS configuration, the base URL of the common store is forcibly set to https:// rather than http://. Because FAS does not share the store with smart cards, a new store is needed for FAS. The Linux VDA FAS is compatible with any StoreFront authentication methods. For example, the FAS store can be configured to use passwords or SAML, but cannot use both at the same time. When SAML is selected, the URL of StoreFront automatically redirects to IdP and the password authentication method is ignored.

Start Internet Explorer and open the URL of the FAS store (for example, https://mzgwy-ddc.xd.local/Citrix/FASWeb).

Note: The URL of the FAS store must have Web appended.

Install and set up FAS

The installation and setup process consists of the following steps:

1. Install the Federated Authentication Service
2. Enable the Federated Authentication Service plug-in on StoreFront servers
3. Configure Group Policy
4. Use the Federated Authentication Service administration console to: (a) Deploy the provided templates, (b) Set up certificate authorities, and (c) Authorize the Federated Authentication Service to use your certificate authority
5. Configure user rules

For instructions on each of the steps, see Federated Authentication Service. Note the following differences or complements in each of the steps. Pay special attention to the target machine you operating on, for example, the AD, Delivery Controller, StoreFront, or the FAS server.

Install the Federated Authentication Service (on the FAS server)

For security, install FAS on a dedicated server that is secured in a similar way to a domain controller or certificate authority.

Enable the Federated Authentication Service plug-in on a StoreFront store (on StoreFront)

Ensure that the following command uses the same FAS store name that you typed when configuring StoreFront. For example, FAS is the store name in this example:

$StoreVirtualPath = “/Citrix/FAS”

Configure the Delivery Controller (on Delivery Controller)

To use the Federated Authentication Service, configure the Delivery Controller to trust the StoreFront servers that can connect to it: run the Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true PowerShell cmdlet. Sometimes, you might need to run Add-PSSnapin citrix.* first.

Configure Group Policy (on the FAS server and on the AD)

You must be an administrator to be able to perform Steps 1–7 in this section. Step 1 must be done on the FAS server and Steps 2–7 must be done on the AD.

After you complete Steps 1–7, check in the Registry Editor of the FAS server to confirm that the FAS policy has been set.

Enable in-session certificate support

The Linux VDA does not support in-session certificates.

Use the Federated Authentication Service administration console (on the FAS server)

No complement. See the Federated Authentication Service article.

Deploy certificate templates (on the FAS server)

No complement. See the Federated Authentication Service article.

Set up Active Directory Certificate Services (on the FAS server)

No complement. See the Federated Authentication Service article.

Authorize the Federated Authentication Service (on the FAS server)

No complement. See the Federated Authentication Service article.

Configure user rules (on the FAS server)

No complement. See the Federated Authentication Service article.

For more information, see also the Delegated Enrollment Agents and Access Control List configuration parts in the Security considerations section of the Federated Authentication Service article.

Federated Authentication Service ADFS deployment

For information on how to deploy the ADFS IdP for Federated Authentication Service, see Federated Authentication Service ADFS deployment.

Configure the Linux VDA

Set FAS servers

For fresh Linux VDA installation, to use FAS, type the FQDN of each FAS server when you are asked for CTX_XDL_FAS_LIST during the execution of ctxinstall.sh or ctxsetup.sh. Because the Linux VDA does not support AD Group Policy, you can provide a semicolon-separated list of FAS servers instead. If any server address is removed, fill its blank with the <none> text string and keep the sequence of server addresses without any changes.

For upgrading an existing Linux VDA installation, you can rerun ctxsetup.sh to set the FAS servers. Or you can run the following commands to set the FAS servers and to restart the ctxvda service to make your setting take effect.

sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKLM\Software\Citrix\VirtualDesktopAgent\Authentication\UserCredentialService" -t "REG_SZ" -v "Addresses" -d "<Your-FAS-Server-List>" --force

service ctxvda restart
<!--NeedCopy-->

To update the FAS servers through ctxreg, run the following commands:

sudo /opt/Citrix/VDA/bin/ctxreg update -k "HKLM\Software\Citrix\VirtualDesktopAgent\Authentication\UserCredentialService" -v "Addresses" -d "<Your-FAS-Server-List>"

service ctxvda restart
<!--NeedCopy-->

Install a root CA certificate

For the verification of users’ certificates, install the root CA certificate on the VDA. Obtain the AD root certificate from the preceding Retrieve the CA Certificate from the Microsoft CA (on AD) step, or download its DER format from the root CA server http://CA-SERVER/certsrv.

Note:

The following commands also apply to configuring an intermediate certificate.

Convert a DER file (.crt, .cer, .der) to PEM by running the command similar to the following:

sudo openssl x509 -inform der -in root.cer -out root.pem
<!--NeedCopy-->

Then, install the root CA certificate to the openssl directory by running the command similar to the following:

sudo cp root.pem /etc/pki/CA/certs/
<!--NeedCopy-->

Note:

Do not put the root CA certificate under the /root path. Otherwise, FAS does not have the read permission to the root CA certificate.

Configure FAS

Run the following script to configure FAS:

sudo /opt/Citrix/VDA/sbin/ctxfascfg.sh
<!--NeedCopy-->

Note:

The preceding script handles only scenarios with a single root CA certificate.

If there are intermediate certificates in your environment, add the intermediate paths to /etc/krb5.conf as follows:

[realms]
EXAMPLE.COM = {
…
pkinit_anchors = FILE:/etc/pki/CA/certs/root.pem
pkinit_pool = FILE:/etc/pki/CA/certs/intermediate.pem
…
}

Two environment variables are added so that ctxfascfg.sh can be run in silent mode:

• CTX_FAS_ADINTEGRATIONWAY=winbind | sssd | centrify – Denotes the Active Directory integration method, which equals to CTX_EASYINSTALL_ADINTEGRATIONWAY when CTX_EASYINSTALL_ADINTEGRATIONWAY is specified. If CTX_EASYINSTALL_ADINTEGRATIONWAY is not specified, CTX_FAS_ADINTEGRATIONWAY uses its own value setting.

• CTX_FAS_ROOT_CA_PATH=<root_CA_certificate> – Specifies the full path of the root CA certificate.

Choose the correct Active Directory integration method and then type the correct path of the root CA certificate (for example, /etc/pki/CA/certs/root.pem).

The script then installs the krb5-pkinit and pam_krb5 packages and sets the relevant configuration files.

Limitation

• FAS supports limited platforms and AD integration methods, see the following matrix:

  	Winbind	SSSD	Centrify
  RHEL 7.7 /CentOS 7.7	√	√	√
  Ubuntu 18.04	√	×	√
  Ubuntu 16.04	√	×	√
  SLES 12.3	√	×	√

• FAS does not support lock screen yet. If you click the lock button in a session, you cannot log back on to the session again by using FAS.
• This release supports only the common FAS deployments summarized in the Federated Authentication Service architectural overview article and does not include Windows 10 Azure AD Join.

Troubleshooting

Before troubleshooting FAS, ensure that the Linux VDA is installed and configured correctly so that a non-FAS session can be launched successfully on the common store by using password authentication.

If non-FAS sessions work properly, set the HDX log level of the Login class to VERBOSE and the VDA log level to TRACE. For information on how to enable trace logging for the Linux VDA, see Knowledge Center article CTX220130.

FAS server configuration error

Launching a session from the FAS store fails. For example, see the following screen capture:

Check /var/log/xdl/hdx.log and find the error log similar to the following:

2018-03-27 10:17:56.722 <P10122:S2> citrix-ctxlogin: query2fas: failed to retrieve data: No such file or directory.

2018-03-27 10:17:56.722 <P10122:S2> citrix-ctxlogin: sayhello2fas_internal: Failed to query.

2018-03-27 10:17:56.722 <P10122:S2> citrix-ctxlogin: sayhello2fas_convertcredential: exit.

2018-03-27 10:17:56.722 <P10122:S2> citrix-ctxlogin: LoginFasValidate: Failed to start FAS.

2018-03-27 10:17:56.722 <P10122:S2> citrix-ctxlogin: receive_data: LoginFASValidate - parameters check error.

2018-03-27 10:17:56.722 <P10122:S2> citrix-ctxlogin: receive_data: Exit FAILURE

2018-03-27 10:17:56.722 <P10122:S2> citrix-ctxlogin: main: EXITING login process..., FAILURE
<!--NeedCopy-->

Solution

Run the following command to verify that the Citrix registry value “HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\VirtualDesktopAgent\Authentication\UserCredentialService” is set to <Your-FAS-Server-List>.

sudo /opt/Citrix/VDA/bin/ctxreg dump | grep "UserCredentialService"
<!--NeedCopy-->

If the existing setting is incorrect, follow the preceding Set FAS servers step to set it again.

Incorrect root CA certificate configuration

Launching a session from the FAS store fails. A gray window appears and disappears several seconds later.

Check /var/log/xdl/hdx.log and find the error log similar to the following:  

2018-03-27 10:15:52.227 <P9099:S3> citrix-ctxlogin: validate_user: pam_authenticate err,can retry for user user1@CTXFAS.LAB

2018-03-27 10:15:52.228 <P9099:S3> citrix-ctxlogin: logout_user: closing session and pam transaction

2018-03-27 10:15:52.228 <P9099:S3> citrix-ctxlogin: validate_user: Exit (user=user1@CTXFAS.LAB)=INVALID_PASSWORD

2018-03-27 10:15:52.228 <P9099:S3> citrix-ctxlogin: LoginBoxValidate: failed validation of user 'user1@CTXFAS.LAB', INVALID_PASSWORD

2018-03-27 10:15:52.228 <P9099:S3> citrix-ctxlogin: Audit_login_failure: Not yet implemented
<!--NeedCopy-->

Solution

Verify that the full path of the root CA certificate is set correctly in /etc/krb5.conf. The full path is similar to the following:

 [realms]

EXAMPLE.COM = {

    ......

    pkinit_anchors = FILE:/etc/pki/CA/certs/root.pem

    ......

}  
<!--NeedCopy-->

If the existing setting is incorrect, follow the preceding Install a root CA certificate step to set it again.

Alternatively, check whether the root CA certificate is valid.

Shadow account mapping error

FAS is configured by SAML authentication. The following error might occur after an ADFS user enters the user name and password on the ADFS logon page.

This error indicates that the ADFS user has been verified successfully, but there is no shadow user configured on AD.

Solution

Set the Shadow Account on AD.

ADFS not configured

The following error occurs during a logon attempt to the FAS store:

The cause is that the FAS store is configured to use SAML authentication while the ADFS deployment is missing.

Solution

Deploy the ADFS IdP for Federated Authentication Service. For more information, see Federated Authentication Service ADFS deployment.

Related information

• The common FAS deployments are summarized in the Federated Authentication Service architectural overview article.
• “How-to” articles are introduced in the Federated Authentication Service advanced configuration chapter.

Known issue

When FAS is in use, you can fail when trying to launch a published desktop or app session with non-English characters.

Workaround

Right-click Manage Templates in the CA tool to change the Citrix_SmartcardLogon template from Build from this Active Directory information to Supply in the request: