Step 1: Ensure that CoolKey supports your smart card

1. Prepare a physical machine with RHEL 7.3 and CoolKey package installed. For more information about CoolKey installation, see Install the smart card driver.
2. Insert the smart card and run the following command:

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.

Step 2: Configure smart card environment

Step 3: Configure smart card support on Linux VDA

2. Install the smart card driver

3. Install the PAM modules for smart card authentication

4. Install the Linux VDA software on RHEL 7.3

5. Prepare a root certificate

• 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:

• Install the root certificate to the openssl directory. In the following command example, certnew.cer is a DER file:

6. Configure the NSS database

• Add the aforementioned root certificate to the NSS database using following command:

• Run the following command to verify that the root certificate is added to the NSS database successfully:

certutil -L -d /etc/pki/nssdb
The command output is similar to the following if the root certificate is added successfully:

• Check whether CoolKey is installed in the NSS PKCS#11 library using following command:

modutil -list -dbdir /etc/pki/nssdb
The command output is similar to the following if the CoolKey module is installed:

If the CoolKey module is not installed, run the following command to install it manually and check the installation again:
modutil -add "CoolKey PKCS #11 Module" -libfile libcoolkeypk11.so -dbdir /etc/pki/nssdb

7. 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:
mkdir /etc/pam_pkcs11/cacerts/
cp certnew.pem /etc/pam_pkcs11/cacerts/
cacertdir_rehash /etc/pam_pkcs11/cacerts

8. 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, for example:
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:

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

Step 4: (Optional) Configure single sign-on with 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 enter 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.

Step 5: Ensure that client host is properly configured

On the client machine, make sure the following requirements are met:

1. The smart card can be installed correctly in the operating system, you should be able to view it in system Device Manager:

2. Make sure the FQDN of StoreFront server can be resolved, you can either configure the DNS server to the Domain DNS server where StoreFront server resides in or add an entry to the hosts file (typically located at C:\Windows\System32\drivers\etc\hosts) as a workaround.  For example, add following entries the hosts file:

10.108.0.135 szcxc-ddc.xd.local
Where

• 10.108.0.135 is the IP address of the StoreFront server.
• szcxc-ddc.xd.local is the FQDN of the StoreFront server.

3. (Optional) Install the trusted CA Certificate on the clientTo install a trusted CA certificate, run the mmc.exe as Administrator. Add the “Certificates” snapin for the Computer Account. Right-click the “Trusted Root Certification Authorities” and Import the file.

If you don’t install CA certificate on the client machine, you’ll get the warning prompt below but the session can be established successfully.

 Note: If you want to use Firefox as the web browser, refer to Firefox for Windows section in Citrix KB article CTX206156-Smart Card Configuration for Testing Citrix Environments.

Usage

Log on to the Linux VDA with a smart card

The Linux VDA supports logon with a smart card in both SSO and non-SSO scenarios.

• In the SSO scenario, users are automatically logged on to StoreFront with the cached smart card certificate and PIN. When users launch a virtual Linux 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 enter a PIN to log on to StoreFront.

 

When users launch a virtual Linux desktop session in StoreFront, a dialog box for logon to the Linux VDA appears as follows, where the username is extracted from the certificate in the smart card and users must enter the PIN again for logon authentication.
This is the same behavior with the Windows VDA.
 

Reconnect to a session with 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 re-authentication 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 web 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:

Limitation

Smart card removal policy
Currently, the Linux VDA uses only the default behavior for smart card removal. That is, 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.