Product Documentation

Pass-through authentication by using smart cards

Feb 26, 2018

Users can use a smart card connected to the client device for authentication when logging on to a Linux virtual desktop session. This feature is implemented through smart card redirection over the ICA smart card virtual channel. Users can also use the smart card within the session. Use cases include adding a digital signature to a document, encrypting or decrypting an email, or authenticating to a website that requires smart card authentication.

The Linux VDA uses the same configuration as the Windows VDA for this feature. For more information, see the Configure the smart card environment section.

The availability of pass-through authentication by using smart cards depends on the following factors:

  • The Linux VDA is installed on RHEL 7.3. 
  • SSSD is used for AD integration.
  • Smart cards supported by CoolKey are used.
  • Citrix Receiver for Windows is used.

Note

Smart card authentication to NetScaler Gateway is not officially supported. 

Ensure that CoolKey supports your smart card

CoolKey is a widely used smart card driver on RHEL. CoolKey supports four types of smart cards, which are CoolKey cards, CAC, PIV, and PKCS#15. But the number of cards that are formally supported and validated is still limited (see Smart Card Support in Red Hat Enterprise Linux). 

In this article, the Yubikey 4 smart card is used as an example to illustrate the configuration. Yubikey 4 is an all-in-one USB CCID PIV device that can easily be purchased from Amazon or other retail vendors. The CoolKey driver supports Yubikey 4.

localized image

If your organization requires some other more advanced smart card, prepare a physical machine with the RHEL 7.3 and CoolKey package installed. For information about the CoolKey installation, see Install the smart card driver. Insert your smart card, and run the following command to verify that CoolKey supports your smart card:

Command Copy

pkcs11-tool --module libcoolkeypk11.so --list-slots

If CoolKey supports your smart card, the command output is similar to the following where slot information is contained.

localized image

Configuration

Configure the smart card environment

The Linux VDA uses the same smart card environment with the Windows VDA. In the environment, multiple components must be configured, including the Domain Controller, Microsoft Certificate Authority (CA), Internet Information Services, Citrix StoreFront, and Citrix Receivers. For information about the configuration based on the Yubikey 4 smart card, see Citrix article CTX206156

Before proceeding to the next step, ensure that all components are correctly configured, the private key and user certificate are downloaded to the smart card, and you can successfully log on to the Windows VDA using the smart card.

Install the PC/SC Lite packages

PCSC Lite is an implementation of the Personal Computer/Smart Card (PC/SC) specification in Linux. It provides a Windows smart card interface for communicating to smart cards and readers. Smart card redirection in the Linux VDA is implemented on the PC/SC level.

Run the following command to install the PC/SC Lite packages.

Command Copy

yum install pcsc-lite pcsc-lite-ccid pcsc-lite-libs

Install the smart card driver

CoolKey is a widely used smart card driver on RHEL. If CoolKey is not installed, run the following command to install it.

Command Copy

yum install coolkey

Install the PAM modules for smart card authentication

Run the following command to install the pam_pkcs11, pam_krb5, and krb5-pkinit modules.

Command Copy

yum install pam_pkcs11 pam_krb5 krb5-pkinit

The pam_pkcs11 module is a pluggable authentication module that allows user authentication based on an X.509 certificate. The pam_krb5 module is a pluggable authentication module that PAM-aware applications can use to check passwords and obtain ticket-granting tickets from the Key Distribution Center (KDC). The krb5-pkinit module contains the PKINIT plug-in that allows clients to obtain initial credentials from the KDC using a private key and a certificate.

Install the Linux VDA software on RHEL 7.3

Install the Linux VDA software using the RPM package manager or easy install, see the Installation overview section. Ensure that SSSD is selected as the Active Directory (AD) integration method. 

After the VDA installation is complete, verify that the VDA can register to the Delivery Controller and the published Linux desktop sessions can be launched successfully using password authentication.

Prepare a root certificate

A root certificate is used to verify the certificate in the smart card. Do the following to download and install a root certificate.

1. Obtain a root certificate in PEM format, typically from your CA server.

You can run a command similar to the following to convert a DER file (*.crt, *.cer, *.der) to PEM. In the following command example, certnew.cer is a DER file.

Command Copy

openssl x509 -inform der -in certnew.cer -out certnew.pem

2. Install the root certificate to the openssl directory. The certnew.pem file is used as an example.

Command Copy

cp certnew.pem /etc/pki/CA/certs/

Configure the NSS database

The pam_pkcs11 module relies on the NSS database to access smart cards and certificates. Do the following to configure the NSS database.

1. Add the previously mentioned root certificate to the NSS database.

Command Copy

certutil -A -n "My Corp Root" -t "CT,C,C" -a -d /etc/pki/nssdb -i  /etc/pki/CA/certs/certnew.pem

2. Run the following command to verify that the root certificate is added to the NSS database successfully.

Command Copy

certutil -L -d /etc/pki/nssdb

The command output is similar to the following if the root certificate is added successfully.

localized image

3. Check whether CoolKey is installed in the NSS PKCS#11 library.

Command Copy

modutil -list -dbdir /etc/pki/nssdb

The command output is similar to the following if the CoolKey module is installed. 

localized image

If the CoolKey module is not installed, run the following command to install it manually and check the installation again.

Command Copy

modutil -add "CoolKey PKCS #11 Module" -libfile libcoolkeypk11.so -dbdir /etc/pki/nssdb

Configure the pam_pkcs11 module

The pam_pkcs11 module relies on the local configuration (of the VDA) to verify user certificates. The default root certificate used by pam_pkcs11 locates at /etc/pam_pkcs11/cacerts/. Each root certificate in this path has a hash link. Run the following commands to install the prepared root certificate and configure pam_pkcs11.

Command Copy

mkdir /etc/pam_pkcs11/cacerts/

cp certnew.pem /etc/pam_pkcs11/cacerts/

cacertdir_rehash /etc/pam_pkcs11/cacerts

Configure the pam_krb5 module

The pam_krb5 module interacts with the KDC to get Kerberos tickets using certificates in the smart card. 

In the /etc/krb5.conf configuration file, add pkinit information according to the actual realm.

     EXAMPLE.COM = {

       kdc = KDC. EXAMPLE.COM

       pkinit_anchors = FILE:/etc/pki/CA/certs/certnew.pem

       pkinit_kdc_hostname = KDC.EXAMPLE.COM

       pkinit_cert_match = ||<EKU>msScLogin,<KU>digitalSignature

       pkinit_eku_checking = kpServerAuth

 }     

The configuration file resembles the following after you add the pkinit information.

localized image

Configure PAM authentication

PAM configuration files tell what modules are used for PAM authentication. For smart card authentication, add the following lines to the /etc/pam.d/smartcard-auth file for adding the pam_pkcs11 and pam_krb5 modules.

     auth        [success=ok ignore=2 default=die] pam_pkcs11.so nodebug wait_for_card     

     auth        optional      pam_krb5.so use_first_pass no_subsequent_prompt preauth_options=X509_user_identity=PKCS11:/usr/lib64/pkcs11/libcoolkeypk11.so

     auth        sufficient    pam_permit.so

     account     [default=bad success=ok auth_err=ignore user_unknown=ignore ignore=ignore] pam_krb5.so

     session     optional      pam_krb5.so   

The configuration file resembles the following after modification.

localized image

(Optional) Single sign-on by using smart cards

Single sign-on (SSO) is a Citrix feature that implements pass-through authentication with virtual desktop and application launches. This feature reduces the number of times that users type their PIN. To use SSO with the Linux VDA, configure Citrix Receiver. The configuration is the same with the Windows VDA. For more information, see Citrix article CTX133982.

Enable the smart card authentication as follows when configuring the group policy in Citrix Receiver.

localized image

Usage

Log on to the Linux VDA by using a smart card

Users can use a smart card to log on to the Linux VDA in both SSO and non-SSO scenarios.

  • In the SSO scenario, users are automatically logged on to StoreFront by using the cached smart card certificate and PIN. When users launch a Linux virtual desktop session in StoreFront, the PIN is passed to the Linux VDA for smart card authentication.
  • In the non-SSO scenario, users are prompted to select a certificate and type a PIN to log on to StoreFront.
localized image

When users launch a Linux virtual desktop session in StoreFront, a dialog box for logon to the Linux VDA appears as follows. The user name is extracted from the certificate in the smart card and users must type the PIN again for logon authentication. 

This behavior is the same with the Windows VDA.

localized image

Reconnect to a session by using a smart card

To reconnect to a session, ensure that the smart card is connected to the client device. Otherwise, a gray caching window appears on the Linux VDA side and exits quickly because reauthentication fails without the smart card connected. No other prompt is provided in this case to remind you to connect the smart card.

On the StoreFront side, however, if a smart card is not connected when you try to reconnect to a session, the StoreFront web might give an alert as follows.

localized image

Limitation

Smart card removal policy

Now, the Linux VDA uses only the default behavior for smart card removal. When you remove the smart card after logging on to the Linux VDA successfully, the session still keeps connected and the session screen is not locked.