Linux Virtual Delivery Agent

Configure Federated Authentication Service

The Linux VDA supports using FAS to log on to your Citrix Virtual Apps and Desktops environment. It 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.

Configure FAS on the Linux VDA

FAS support on RHEL 8/CentOS 8

FAS depends on the pam_krb5 module, which is deprecated on RHEL 8/CentOS 8. To use FAS on RHEL 8/CentOS 8, build the pam_krb5 module as follows:

  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/CentOS 8.

    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

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 do not modify the order of server addresses.

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

Run ctxfascfg.sh

Run the ctxfascfg.sh script to configure FAS parameters:

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

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_CERT_PATH =<certificate path> – Specifies the full path that stores the root certificate and all intermediate certificates.

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.

Limitation

  • FAS supports limited Linux platforms and AD integration methods. See the following matrix:

      Winbind SSSD Centrify
    RHEL 8.3 / CentOS 8.3 Yes Yes Yes
    RHEL 8.2 / CentOS 8.2 Yes Yes Yes
    RHEL 8.1 / CentOS 8.1 Yes Yes Yes
    RHEL 7.9 / CentOS 7.9 Yes Yes Yes
    RHEL 7.8 / CentOS 7.8 Yes Yes Yes
    Ubuntu 20.04 Yes No Yes
    Ubuntu 18.04 Yes No Yes
    Ubuntu 16.04 Yes No Yes
    SLES 12.5 Yes No Yes
  • 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 architectures 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.

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 the full path that stores the root CA certificate and all intermediate certificates is set correctly in /etc/krb5.conf. 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.

Image of 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

Configure Federated Authentication Service