Smart Card Authentication ¶

Smart card authentication is supported for Linux Clients running on Ubuntu 22.04 connecting to Linux agents. The following section contains information on system requirements, limitations, agent setup, and client setup.

General Requirements ¶

Smart Card Certificate Requirements ¶

The smart card certificate prerequisites are as follows:

• Key usage is set to digital signature

• The Subject common name and subject alternative name (other name) are defined

• Enhanced key usage must include client authentication and/or smart card logon

• Key length does not exceed 2048 bit

Tested Smart Card Readers ¶

The following smart card readers have been tested:

• Belkin USB Smart Card Reader (F1DN008U)

• Identiv SCR3310 USB Contact Smart Card Reader

Tested Smart Card Models ¶

The following smart card models have been tested:

Notes ¶

• Smart Card authentication is enabled by modifying the pcoip.enable_smart_card directive, as described in Enabling Smartcard Authentication.

• At present, only simultaneous configuration of a single card and single reader is supported.

• Smartcard authentication is only supported on Ubuntu 22.04 clients and Trusted Zero Clients connecting to Linux agents. It is not supported while connecting from Tera2 Zero Clients to Linux agents.

• If available, configure the Linux Desktop Environment to use smart cards for lock screen authentication.

Known Limitations ¶

• Elliptic Curve Cryptography (ECC) Certificates are not supported.

• Concurrent users cannot log on to agent machines using the same smart card for authentication.

• Smart cards having multiple certificates allow only one user to log on at a time. Others users must wait until the current users logs off before attempting to log on.

• Single sign-on is not supported. Users must authenticate twice: once on the client and again on the host machine's lock screen.

• Session locking upon smart card removal might not work as expected.

• Session will disconnect when authenticated smart card is removed from the reader.

• If PCoIP sessions fail, disable SELINUX and re-establish a PCoIP session. If this does not work, contact the HP Support team.

• If PIN prompts do not work on Linux Desktop Environments of agent machines, use the password to unlock the desktop. Smartcards will be remoted and available to be used in session.

Agent Setup ¶

Prerequisites ¶

• The host machine is domain-joined.
• If this is a brokered connection, make sure that you installed Leostream broker and Connection Manager.
• CA certificates for authenticating smart cards are available.

Step I: Prepare the Linux Machine ¶

1. Connecting the machine directly to AD using SSSD. For more information, consult the following topics:

   • Connecting RHEL systems directly to AD using SSSD

   • Set up SSSD with Active Directory on Ubuntu machines

2. Enable smart card authentication on the Linux machine and configure smart card for lock screen. For more information, consult the following topics:

   • Configuring smart card authentication on RHEL machines

   • Configuring smart card authentication on Ubuntu

3. Install the Leostream agent on the Linux machine. For more information, see the Leostream® Platform Installation Guide.

   Info

   For common errors encountered during Leostream agent configuration, see the Leostream Install Errors article.

Example Steps to Prepare the Ubuntu Machine ¶

Prepare the Ubuntu 22.04 Machine

1. Sign in to the test machine, and run the following command:

   sudo hostnamectl set-hostname <machine-name.example.net>
   

   sudo reboot
   

   Note

   Modify the hostname of the test machine to include the domain name.

2. Verify that the hostname has been updated successfully.

   hostnamectl
   

3. Install the required packages.

   sudo apt -y install realmd sssd sssd-tools libnss-sss libpam-sss adcli samba-common-bin oddjob oddjob-mkhomedir packagekit
   

4. Join in Active Directory domain, replace SRV.WORLD with your domain name, and replace domain_join_user with your domain user that has permission to join the domain.

   root@test:~# sudo realm join SRV.WORLD -U domain_join_user
   

   Password for domain_join_user: # AD password

5. Verify that you can get AD user information.

   root@test:~# id Serverworld@srv.world
   uid=1259201103(serverworld@srv.world) gid=1259200513(domain users@srv.world) groups=1259200513(domain users@srv.world),1259200512(domain admins@srv.world),1259200572(denied rodc
   password replication group@srv.world)
   

   root@test:~# nano /etc/pam.d/common-session
   

6. To automatically create a home directory on initial login, add the following line at the end of Step 5:

   session optional        pam_mkhomedir.so skel=/etc/skel umask=077
   

7. Sign in to the console or an SSH session with a domain user account to verify that the domain joining was successful.

Enable Smart Card Authentication in Ubuntu 22.04 Machine

1. Install the PKCS#11 Driver for Your Smart Card:

   1. Identify the PKCS#11 driver that supports your smart card device.

   2. To install the OpenSC PKCS#11 driver, enter the following command:

      sudo apt install opensc-pkcs11 -y
      

   Note

   If your device requires a different PKCS#11 driver, install the appropriate package instead.

2. Install PCSCD to enable the smart card reader.

   sudo apt install pcscd -y
   

3. Extract the CA chain that signs the smart card user certificate, and include the CA certificates in the SSSD CA database.

   sudo mkdir -p /etc/sssd/pki -m 600
   

   sudo su
   cat test_ca_chain.pem >> /etc/sssd/pki/sssd_auth_ca_db.pem
   

4. Add pam_cert_auth = True to the /etc/sssd/sssd.conf file.

   [pam]
   pam_cert_auth = True
   

5. Add certmap/<you_domain_name>/upn section to the /etc/sssd/sssd.conf file. Edit the /etc/sssd/sssd.conf file and add the following section. Replace <your_domain_name> with your actual domain name:

   [certmap/<you_domain_name>/upn]
   maprule=(|(userPrincipalName={subject_nt_principal})(samAccountName={subject_nt_principal.short_name}))
   

6. Restart the SSSD service.

   sytemctl restart sssd
   

7. Check if the SSSD service is running.

   systemctl status sssd
   

Example Steps to Prepare the Rocky Linux Machine ¶

Prepare for Rocky Linux 8/9 Machine

2. Log in to the test machine

3. Run the following command to modify the hostname of the test machine to include domain name:

   sudo hostnamectl set-hostname <machine-name.example.net>
   sudo reboot
   

4. Run the following command to verify that the hostname has been update successfully

   hostnamectl
   

5. Install required packages for domain joining

   sudo yum install samba-common-tools realmd oddjob oddjob-mkhomedir sssd adcli krb5-workstation -y
   realm discover example.net
   sudo realm join example.net -U <domain admin that has permission to join domain>
   

6. Run the following command to check if domain join works:

   getent passwd <domain user name>
   

7. Verify with the following command if the domain user could access the machine:

   ssh domain_user@example.net@machine_ip_address 
   

   Note

   If ssh session failed, check system log for any errors

Enable Smart Card Authentication in Rocky Linux 8/9 Machine

1. Run the following commands to fix failed to verify CMS error:

   sudo update-crypto-policies --set DEFAULT:SHA1
   sudo reboot
   sudo dnf  install opensc gnutls-utils  krb5-pkinit -y
   

   Info

   1. Use sudo update-crypto-policies --set DEFAULT:SHA1 and sudo reboot only on RHEL/Rocky Linux 9. Use sudo dnf install opensc gnutls-utils krb5-pkinit -y on RHEL/Rocky Linux 8 and 9.

   2. This is required for RHEL or Rocky Linux 9, to fix failed to verify CMS error. For more information refer to Red Hat Bugzilla - Bug 2060798.

2. Add the following to /etc/krb5.conf in [libdefaults] section:

   pkinit_kdc_hostname = example.net

   Note

   For more information, refer to MIT Kerberos Documentation.

3. Add or modify the following configuration in /etc/sssd/sssd.conf file:

   [domain/example.net]
   

   Adjust this setting if DoD CAC card does not work in the test environment:

   krb5_auth_timeout = 30 
   

4. Get CA chain that signs the smart card user certificate. Ensure that the CA chain is in pem format.

5. Assume the smart card user cert is signed by Ca-Auth-root-CERT.pem and Ca-Auth-leaf-CERT.pem.

6. Include the CA certificates in the SSSD CA database

   sudo mkdir -p /etc/sssd/pki -m 600 (Create /etc/sssd/pki if it does not exist)
   sudo su
   cat Ca-Auth-root-CERT.pem Ca-Auth-leaf-CERT.pem >> /etc/sssd/pki/sssd_auth_ca_db.pem
   

7. Add the CA chain to the system's trust anchors

   sudo trust anchor /etc/sssd/pki/sssd_auth_ca_db.pem
   

8. Run the following command to restart SSSD to apply changes:

   sudo systemctl restart sssd
   

9. Allow both smart card and password authentication with the following command:

   sudo authselect select sssd with-smartcard --force
   

Step II: Install and Configure Anyware Agent ¶

1. Make sure that you downloaded Anyware Agent 25.03 or later to the remote machine.

2. Install the agent following instructions in Installing the agent

3. Enable smart card authentication on the agent:

   1. Navigate to /etc/pcoip/.

   2. Open the pcoip-agent.conf file.

   3. Locate the pcoip.enable_smart_card directive.

   4. Set its value to "1".

   5. Save your changes.

   6. Add root and intermediate CA certificates to the agent's trusted certificate store:

      • Ubuntu - using update-ca-certificates, see Install a PEM-format certificate.

      • RHEL/Rocky - using update-ca-trust, see Adding new certificates.

   7. Add the following setting to the domain section in the sssd.conf file, available at the following location: /etc/sssd/

      For example:

      [domain/example.net]
      ad_gpo_map_permit = +pcoip-session
      

   8. Restart the PCoIP Agent service by running the following command:

      systemctl restart pcoip
      

      Note

      The following steps 9 to 17 are only applicable for Ubunutu 22.04.

   9. Ensure that smart card is showing in the lock screen. Create a user file in the /etc/dconf/profile.

      cat << EOF | sudo tee -a /etc/dconf/profile/user
      user-db:user
      system-db:local
      EOF
      

   10. Create the local.d directory.

       sudo mkdir -p /etc/dconf/db/local.d
       

   11. Disable the password authentication.

       cat << EOF | sudo tee -a /etc/dconf/db/local.d/00_gdm-password-disable
       [org/gnome/login-screen]
       enable-password-authentication=false
       EOF
       

   12. Enable the smart card authentication.

       cat << EOF | sudo tee -a /etc/dconf/db/local.d/00_gdm-smartcard-enable
       [org/gnome/login-screen]
       enable-smartcard-authentication=true
       EOF
       

   13. Create the locks directory.

       sudo mkdir -p /etc/dconf/db/local.d/locks
       

   14. Make enable-password-authentication and enable-smartcard-authentication non-user configurable. Add the following lines to the locks directory to prevent users from changing these settings:

       cat << EOF | sudo tee -a /etc/dconf/db/local.d/locks/00_gdm-smartcard-locks
       

   15. Make these options non-user configurable:

       /org/gnome/login-screen/enable-password-authentication
       /org/gnome/login-screen/enable-smartcard-authentication
       EOF
       

   16. To update the system dconf database after making changes, run the following command:

       sudo dconf update
       

   17. Restart the machine.

       sudo reboot
       

Client Setup ¶

1. Download Anyware Linux Client version 25.03 or later on the Ubuntu 22.04 client machine.

2. Configure the client machine to connect to the agent machine. Follow the instructions in the topic "Connecting to an Agent Machine " in the Anyware Linux Client guide.

3. Plug the smart card reader into the client machine.

4. Use your smart card to authenticate the session. For a full set of instructions on using smart cards to authenticate PCoIP sessions, consult "Using Smart Card Authentication to Connect to a Session" in the Anyware Linux Client guide.

Configuring Smartcard Removal Behavior ¶

This policy determines the action to be taken when the smart card used to authenticate the session is removed from the card reader, or the card reader is disconnected.

1. On the agent machine, navigate to /etc/pcoip/.

2. Open the pcoip-agent.conf file.

3. Set the smart_card_removal_behavior directive to configure the smart card removal behavior:

   • To disconnect session on smart card removal (default behavior), set pcoip.smart_card_removal_behavior to "1".

   • To take no action on removal of smart card, set pcoip.smart_card_removal_behavior to "0".

4. Restart the system.

Disabling Smart Card Support ¶

1. On the agent machine, navigate to /etc/pcoip/.

2. Open the pcoip-agent.conf file.

3. Set the pcoip.enable_smart_card directive to "0".

4. Save your changes.

5. Reboot the agent machine.

Troubleshooting Issues ¶

For higher latency networks where the latency between the client and host is higher than 100 milliseconds, authentication using smart cards on lock screen may fail.

This occurs because an SSSD component called p11_child times out before the pin gets validated. To workaround this issue, increase the SSSD p11_child time-out by making these changes in the /etc/sssd/sssd.conf file:

1. In the [pam] section, increase the p11_child_timeout value to 60 seconds.

2. Restart SSSD service.

   systemctl restart sssd.service
   

Reporting Issues ¶

To report issues with this feature, enable additional debugging capabilities before creating a support bundle as below:

1. On the host machine, uncomment the following line from the /etc/default/pcoip-pcscd-args file: PCSCD_ARGS=–debug

2. Save your changes.

3. Reproduce the issue.

4. Generate support bundle and send it to the HP Anyware support team.