Linux Virtual Delivery Agent

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.

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

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

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

Known issue

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

Federated Authentication Service