Federated Authentication Service
You can use 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.
Starting with the 2206 release, you can customize the FAS port on the Linux VDA side through CTX_XDL_FAS_LIST in the ctxsetup.sh. For more information, see the Linux VDA installation article based on your distribution.
Configure FAS on the Linux VDA
FAS support on RHEL 8.x and Rocky Linux 8.x
FAS depends on the pam_krb5 module, which is deprecated on RHEL 8.x and Rocky Linux 8.x. The following steps are required if you want to use FAS on RHEL 8.x and Rocky Linux 8.x machines delivered in multi-session OS mode. For FAS on RHEL 8.x and Rocky Linux 8.x machines delivered in single-session OS (VDI) mode, you can skip the following steps.
-
Download the pam_krb5-2.4.8-6 source code from the following website:
https://centos.pkgs.org/7/centos-x86_64/pam_krb5-2.4.8-6.el7.x86_64.rpm.html.
-
Build and install the pam_krb5 module on RHEL 8.x and Rocky Linux 8.x.
yum install make gcc krb5-devel pam-devel autoconf libtool rpm2cpio pam_krb5-2.4.8-6.el7.src.rpm | cpio -div tar xvzf pam_krb5-2.4.8.tar.gz cd pam_krb5-2.4.8 ./configure --prefix=/usr make make install <!--NeedCopy--> -
Verify that pam_krb5.so exists under /usr/lib64/security/.
ls -l /usr/lib64/security | grep pam_krb5 <!--NeedCopy-->
Set FAS servers
To use FAS in a fresh Linux VDA installation, type the FQDN of each FAS server when you run 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 do not modify the order of server addresses.
To upgrade 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 ctxjproxy restart
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 ctxjproxy restart
service ctxvda restart
<!--NeedCopy-->
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 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.
Run ctxfascfg.sh
Run the ctxfascfg.sh script to configure FAS:
sudo /opt/Citrix/VDA/sbin/ctxfascfg.sh
<!--NeedCopy-->
Environment variables are added so that ctxfascfg.sh can be run in silent mode:
-
CTX_FAS_ADINTEGRATIONWAY=winbind | sssd | centrify | pbis: 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.
-
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.
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.
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
service ctxjproxy restart
service ctxvda restart
<!--NeedCopy-->
Limitation
-
FAS supports limited Linux platforms and AD integration methods. See the following matrix:
Winbind SSSD Centrify PBIS Amazon Linux 2 Yes Yes Yes Yes Debian 11.3 Yes Yes Yes Yes RHEL 9.1/9.0 Yes Yes No No RHEL 8.7/8.6/8.4 Yes Yes Yes Yes RHEL 7.9, CentOS 7.9 Yes Yes Yes Yes Rocky Linux 9.1/9.0 Yes Yes No No Rocky Linux 8.7/8.6 Yes Yes No No SUSE 15.4 Yes Yes Yes No Ubuntu 22.04/20.04/18.04 Yes Yes Yes Yes - 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 and 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. For more information, see XDPing.
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.
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 issue occurs when the FAS store is configured 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 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:
