Linux Virtual Delivery Agent

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
Amazon Linux 2 Yes Yes Yes Yes
Debian 11.7/11.3 Yes Yes Yes Yes
RHEL 9.2/9.0 Yes Yes No No
RHEL 8.8/8.6 Yes Yes Yes Yes
RHEL 7.9, CentOS 7.9 Yes Yes Yes Yes
Rocky Linux 9.2/9.0 Yes Yes No No
Rocky Linux 8.8/8.6 Yes Yes No No
SUSE 15.5 Yes Yes Yes No
Ubuntu 22.04/20.04 Yes Yes Yes Yes

Configure FAS on the Linux VDA

FAS support on RHEL/Rocky Linux 8.x and later

FAS depends on the pam_krb5 module, which is deprecated on RHEL/Rocky Linux 8.x and later. The following steps are required if you want to use FAS on RHEL/Rocky Linux 8.x or later machines delivered in multi-session OS mode. For FAS on RHEL/Rocky Linux 8.x and later machines delivered in single-session OS (VDI) mode, you can skip the following steps.

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

  2. Build and install the pam_krb5 module.

    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-->
    
  3. Verify that pam_krb5.so exists under /usr/lib64/security/.

    ls -l /usr/lib64/security | grep pam_krb5
    <!--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 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: 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_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.

  • CTX_FAS_SERVER_LIST=’list-fas-servers’ – The Federated Authentication Service (FAS) servers are configured through AD Group Policy. For information about FAS policy setting on the domain GPO, see Configure Group Policy. The Linux VDA does not support AD Group Policy, but you can provide a semicolon-separated list of FAS servers instead. The sequence must be the same as configured in 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 that 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 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
    
     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.

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.

Invalid logon due to incorrect root CA certificate configuration

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.

Shadow account mapping error

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:

ADFS not configured

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.

Known issues

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

Failing in launching sessions 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:

The supply in the request option