Federated Authentication Service
You can use the Federated Authentication Service (FAS) to authenticate users logging on to a Linux VDA. The Linux VDA uses the same Windows environment as the Windows VDA for the FAS logon feature. For information about configuring the Windows environment for FAS, see Federated Authentication Service. This article provides extra information specific to the Linux VDA.
Note:
The Linux VDA does not support the In-session Behavior policy.
The Linux VDA uses short connections to transmit data with FAS servers.
Supported distributions
FAS supports limited Linux distributions and domain joining methods. See the following matrix:
| Winbind | SSSD | Centrify | PBIS | Quest | |
|---|---|---|---|---|---|
| Amazon Linux 2 | Yes | Yes | Yes | Yes | No |
| Debian 12.7/12.5/11.11 | Yes | Yes | Yes | Yes | No |
| RHEL 9.4/9.2 | Yes | Yes | No | No | Yes |
| RHEL 8.10/8.8 | Yes | Yes | Yes | Yes | Yes |
| Rocky Linux 9.4/9.2 | Yes | Yes | No | No | No |
| Rocky Linux 8.10/8.8 | Yes | Yes | No | No | No |
| SUSE 15.6 | Yes | Yes | Yes | No | No |
| Ubuntu 24.04/22.04/20.04 | Yes | Yes | Yes | Yes | Yes |
Configure FAS on the Linux VDA
Install certificates
For the verification of users’ certificates, install the root CA certificate and all intermediate certificates on the VDA. For example, to install the root CA certificate, get the AD root certificate from the preceding Retrieve the CA Certificate from the Microsoft CA (on AD) step, or download it from the root CA server http://CA-SERVER/certsrv.
Note:
The following commands also apply to configuring an intermediate certificate.
For example, to convert a DER file (.crt, .cer, .der) to PEM, run a 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.
Run ctxfascfg.sh
Run the ctxfascfg.sh script to configure FAS:
sudo /opt/Citrix/VDA/sbin/ctxfascfg.sh
<!--NeedCopy-->
You can run ctxfascfg.sh in silent mode. Before you run the script in silent mode, set the following environment variables:
-
CTX_FAS_ADINTEGRATIONWAY=winbind | sssd | centrify | pbis | quest: Denotes the Active Directory integration method, which equals to
CTX_EASYINSTALL_ADINTEGRATIONWAYwhenCTX_EASYINSTALL_ADINTEGRATIONWAYis specified. IfCTX_EASYINSTALL_ADINTEGRATIONWAYis not specified,CTX_FAS_ADINTEGRATIONWAYuses its own value setting. -
CTX_FAS_CERT_PATH =<certificate path>: Specifies the full path that stores the root certificate and all intermediate certificates.
-
CTX_FAS_KDC_HOSTNAME: Specifies the host name of the Key Distribution Center (KDC) when you select PBIS and Quest.
-
CTX_FAS_PKINIT_KDC_HOSTNAME: Specifies the PKINIT KDC host name, which equals to CTX_FAS_KDC_HOSTNAME unless otherwise specified. If you have multiple Delivery Controllers, add the host names of all KDCs of the domain to pkinit_kdc_hostname in the /etc/krb5.conf file. For more information, see Knowledge Center article CTX322129.
-
CTX_FAS_SERVER_LIST=’list-fas-servers’ – The Federated Authentication Service (FAS) servers are configured through the AD Group Policy. For information about FAS policy setting on the domain GPO, see Configure Group Policy. The Linux VDA does not support the AD Group Policy, but you can provide a semicolon-separated list of FAS servers instead. The sequence must be the same as configured in the AD Group Policy. If any server address is removed, fill its blank with the ’<none>‘ text string and do not modify the order of server addresses. To communicate with FAS servers properly, make sure you append a port number consistent with the port number specified on the FAS servers, for example, CTX_XDL_FAS_LIST=’fas_server_1_url:port_number; fas_server_2_url: port_number; fas_server_3_url: port_number’.
To upgrade an existing Linux VDA installation, you can run the following commands to set the FAS servers and to restart the
ctxvdaservice 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 systemctl restart ctxjproxy systemctl restart ctxvda <!--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>" systemctl restart ctxjproxy systemctl restart ctxvda <!--NeedCopy-->
Choose the correct Active Directory integration method and then type the correct path of certificates (for example, /etc/pki/CA/certs/).
The script then installs the krb5-pkinit and pam_krb5 packages and sets the relevant configuration files. For RHEL 8 and later, as PAM_KRB5 is moved to the EPEL repository, the script tries to enable EPEL in those distributions.
Disable FAS
To disable FAS on the Linux VDA, remove all FAS servers from ConfDB using the following commands:
sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKLM\Software\Citrix\VirtualDesktopAgent\Authentication\UserCredentialService" -t "REG_SZ" -v "Addresses" -d "" --force
systemctl restart ctxjproxy
systemctl restart ctxvda
<!--NeedCopy-->
Limitation
- FAS doesn’t support the lock screen yet. If you click the lock button in a session, you can’t 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 doesn’t include Windows 10 Azure AD Join.
Troubleshooting
Before troubleshooting FAS, make sure that:
- The Linux VDA is installed and configured correctly.
- 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 enabling trace logging for the Linux VDA, see Knowledge Center article CTX220130.
You can also use the Linux XDPing tool to check for common configuration issues that might exist in your Linux VDA environment.
FAS server configuration error
Launching a session from the FAS store fails.
Check /var/log/xdl/hdx.log and find the error log similar to the following:
2021-01-28 01:42:16.164 <P26422:S4> citrix-ctxlogin: validate_user: [Logon Type] Federated Authentication Logon.
2021-01-28 01:42:16.164 <P26422:S4> citrix-ctxlogin: validate_fas: entry
2021-01-28 01:42:16.164 <P26422:S4> citrix-ctxlogin: connect_fas: start connect to server 0
2021-01-28 01:42:16.164 <P26422:S4> citrix-ctxlogin: connect_fas0: failed to connect: Connection refused.
2021-01-28 01:42:16.164 <P26422:S4> citrix-ctxlogin: validate_fas: failed to connect to server [0], please confirm if fas service list is well configurated in condb
2021-01-28 01:42:16.164 <P26422:S4> citrix-ctxlogin: validate_fas: exit, 43
2021-01-28 01:42:16.164 <P26422:S4> citrix-ctxlogin: validate_user: failed to validate fas credential
2021-01-28 01:42:16.164 <P26422:S4> citrix-ctxlogin: LoginBoxValidate: failed validation of user 'user1@CTXDEV.LOCAL', INVALID_PARAMETER
<!--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 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:
2021-01-28 01:47:46.210 <P30656:S5> citrix-ctxlogin: get_logon_certificate: entry
2021-01-28 01:47:46.210 <P30656:S5> citrix-ctxlogin: check_caller: current process: pid [30656], name [/opt/Citrix/VDA/bin/ctxlogin]
2021-01-28 01:47:46.210 <P30656:S5> citrix-ctxlogin: get_public_certificate: entry
2021-01-28 01:47:46.211 <P30656:S5> citrix-ctxlogin: query_fas: waiting for response...
2021-01-28 01:47:46.270 <P30656:S5> citrix-ctxlogin: query_fas: query to server success
2021-01-28 01:47:46.270 <P30656:S5> citrix-ctxlogin: get_public_certificate: exit
2021-01-28 01:47:46.270 <P30656:S5> citrix-ctxlogin: fas_base64_decode: input size 1888
2021-01-28 01:47:46.271 <P30656:S5> citrix-ctxlogin: fas_base64_decode: output size 1415
2021-01-28 01:47:46.271 <P30656:S5> citrix-ctxlogin: get_logon_certificate: get logon certificate success
2021-01-28 01:47:46.271 <P30656:S5> citrix-ctxlogin: cache_certificate: cache certificate success
2021-01-28 01:47:46.271 <P30656:S5> citrix-ctxlogin: get_logon_certificate: exit, 0
2021-01-28 01:47:48.060 <P30656:S5> citrix-ctxlogin: validate_user: pam_authenticate err,can retry for user user1@CTXDEV.LOCAL
<!--NeedCopy-->
Solution
Verify that you have correctly set in /etc/krb5.conf the full path that stores the root CA certificate and all intermediate certificates. The full path is similar to the following:
[realms]
EXAMPLE.COM = {
......
pkinit_anchors = DIR:/etc/pki/CA/certs/
......
}
<!--NeedCopy-->
If the existing setting is incorrect, follow the preceding Install certificates 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.
The 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 issue occurs when you configure the FAS store to use SAML authentication but 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 issues
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:
