Table of Contents
Overview
I use a YubiKey 5Ci (by Yubico) in my lab. This allows me to log in with a smart card interface. If you are looking for information on how to configure smart card access in your lab, please reference the following post: MyLab: Smart Card Authentication
Certificates, Smart Cards, and YubiKeys
First, smart cards are nothing more than storage devices that store user-based certificates. These can be an actual card similar in appearance to a debit or credit card that has a chip. The alternative can be a USB storage device, like a YubiKey, that can also act as a smart card.
A certificate authority needs to be present and configured in the domain. I also have a post for configuring a certificate authority, MyLab: The Certificates. When it comes to the certificates, there is a trust chain. This trust chain can contain one or more signing certificates. Usually, I see two levels under (an intermediate CA and a root CA), however, there is not a standard. The thing to take away from here is that all certificates that make up the chain must be present for the chain to be trusted. In my lab, I have a root CA and an intermediate CA. My lab is fairly simple. Some environments may consist of multiple root CA servers and subsequent intermediate CA servers, and the chain of trust can get lengthy.
Prerequisites
Ensure the following prerequisites are configured before setting up Smart Card authentication.
- Make sure the vCenter Server has a trusted TLS certificate configured. (https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.authentication.doc/GUID-BD70615E-BCAA-4906-8E13-67D0DBF715E4.html)
- Make sure the vCenter Server has a configured Identity Source using Active Directory over LDAP. (https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.authentication.doc/GUID-98B36135-CDC1-435C-8F27-5E0D0187FF7E.html)
- Assign administrative users to the Administrator role, preferably using an Active Directory Security Group. (https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.authentication.doc/GUID-7877D42E-9EB3-40D3-B92F-E86559966BBC.html)
- Configure the Reverse Proxy and restart the virtual machine. (See next section for details) (https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.authentication.doc/GUID-DE48ED27-E48B-4FDA-B3C8-DD7127BF6879.html)
VMware vSphere
The high level steps here are:
- Configuring vCenter Server to request certificates.
- Activating the smart card configuration.
- Applying a certificate revocation policy.
Configure vCenter Server to Request Certificates
Note: This will require uploading certificate files to the vCenter Server appliance. In some organizations, simply using WinSCP or a similar utility can be used. If the organization does not have the tools or does not allow these utilities, you can sometimes make an SSH connection to the vCenter Server appliance and write the files using vi.
Start by taking a fresh snapshot!
For this activity, I am going to connect with SSH to the vCenter Server appliance using the fully qualified domain name. If prompted, type shell to launch BASH.
We need to create and populate a file, called clienttrustCA.pem, with all of the certificates (all root and intermediate certificates) that are used to sign the user certificates stored on the Smart Card or PIV.
As you can see, my appliance does not currently contain the file.
/usr/lib/vmware-sso/vmware-sts/conf/clienttrustCA.pem
I am going to open the certificate files on my desktop and create a single temporary file.
Copy all the contents in the temporary file so they are in the buffer.
On the SSH window, create a new file using vi.
vi /usr/lib/vmware-sso/vmware-sts/conf/clienttrustCA.pem
Put the contents using the letter p or just paste the contents from the buffer after pressing the letter i.
Save the file [in vi, press colon (:) and then w (for write) and q (for quit)] and cat the file back out to ensure there are no issues reading the file.
:wq
The file permissions on the clienttrustCA.pem file should be:
-rw-r--r-- 1 root root 0 Nov 27 10:09 clienttrustCA.pem
The KB says to Restart the Security Token Service (STS) Service, however, I find this doesn’t work, so just restart the entire virtual machine.
/usr/lib/vmware-vmon/vmon-cli --restart sts
Activating the smart card configuration.
Log in to the vSphere Client and navigate to Administration > Single Sign On: Configuration > Identity Provider: Smart Card Authentication. Select Edit on the Authentication Method table.
For testing, select Enable both options.
For production, select Enable smart card authentication.
When you log out of the vSphere Client and log back in, there should now be a new option for Use Smartcard authentication.
Make sure the user with the smart card to test log in has been configured to log into the appliance and also that the smart card reader has been configured in the browser. Once the Smart card authentication is configured and confirmed, be sure to adjust the authentication method above (only Smart card vs both methods) as required.
Troubleshooting
I find that browser cookies get in the way…a lot. Sometimes, simply removing the browser cookies and restarting the browser is enough.
If you are unable to log in, the Certificate revocation settings may need to be adjusted. Back on the vSphere Client, navigate to Administration > Single Sign On: Configuration > Identity Provider: Smart Card Authentication. Under Smart card authentication settings, select Certificate revocation, and then edit.
Change the Revocation check as necessary.
Unable to validate the submitted credential.
When trying to log in to the appliance, you receive the message, Unable to validate the submitted credential.
The fix for this is to add certificates at Administration > Single Sign On: Configuration > Identity Provider: Smart Card Authentication. Maybe newer signing CAs have been implemented since the initial configuration.
Click Add under Smart card authentication settings: Trusted CA certificates.
User Name and Password are Required When Using Firefox
When trying to log in to the appliance with Firefox, you receive the message, User Name and password are required.
ref: https://kb.vmware.com/s/article/90207
Enable the flag to use client certificates in CORS pre-flight requests:
about:config
Toggle the following configuration item to true.
network.cors_preflight.allow_client_cert
Remove any cookies, close the browser, open a new Firefox window, and try to authenticate with the Smart Card, again.
User Name and Password are Required Regardless of Browser
When trying to log in to the appliance regardless of browser, you receive the message, User Name and password are required.
The first thing to do is check the logs on the vCenter
tail -f /var/log/vmware/sso/websso.log
Examples of messages that may be found:
Responded with ERROR 401 message Unable to validate the submitted credential.
Ignoring exception while iterating providers: Failed in account linking using certificate SAN: <username>@domain.com
Check that the user certificate’s Subject Alternative Name (SAN) has an entry that matches the Active Directory User Principle Name (UPN) for the user.
Note that vCenter queries the pre-Windows 2000 entry when searching for users.
