Security Keys Authentication

Overview

📘
Supported in 2.10.0+
This feature is only available in the Windows Workforce Access Client 2.10.0 and above

This document describes how to enable Smartkeys (Security Keys) enrollment and authentication for HYPR Workforce Access Client.

Definitions

Acronym	Definition
PIN	A Personal Identification Number (PIN) is a set of characters used to unlock the smart card for use. For example, the Windows operating system allows numbers or letters for a PIN. Mac OS only supports numbers for PINs. The PIN is a decentralized secret the user should not share. The PIN is bound and used to unlock an authenticator. In the case of a hardware security key, such as a Yubico YubiKey, the PIN resides on the YubiKey and unlocks the authenticator that uses public/private key encryption to perform authentication.
PUK	A PIN Unblocking Key (PUK) is a code that is used by users or applications to reset a PIN that has been lost, forgotten, or locked because of too many failed attempts. The PUK is part of the PIV standard that the YubiKey follows.
PIV	Personal Identity Verification or frequently associated together as a "PIV Card" is commonly the reference to United States Federal smart card that contains the necessary data for the cardholder to be granted to Federal facilities and information systems and assure appropriate levels of security for all applicable Federal applications. It is also a general means of reference for Smartcards and associated protocols & standards used for authenticating users securely.

Pre-requisites

HYPR Workforce Access Client 2.10.0+
HYPR Server 3.9.0+
The certificate template needs to be configured to support smartcard logon.
Control Center is configured to support Security Key authentication
YubiKey 4 or YubiKey 5 series security key

Getting Started

Enrollment

Step 1: Open the Workforce Access App.

Step 2: Selecting Start Pairing will take you to the following screen which provides you with the choice of pairing a smartphone or pairing with a security key. Select security key to continue.

Step 3: To continue setting up a Security Key, start by entering in the temporary PIN provided to you by your administrator or through the instruction guide which accompanied your device.

🚧
Try Default PIN
If you are not aware of a temporary PIN, give the "Try Default PIN" toggle a try and it will insert a common PIN used for devices such as a YubiKey which is generally 123456.
If this does not work on the first attempt, reach out to your administrator for support. After enough subsequent tries, you may be locked out.

Step 4: Enter the new PIN, and reconfirm the PIN on the following field.

📘
PIN length
PIN must be between 6 and 8 characters

📘
PIN Complexity Enforcement
Users are not allowed to use weak PINs such as "123456" or "111111"

Step 5: Click on FINISH button.

Step 6: Wait for enrollment to complete.

Click the Finish button to view the paired device.

You will see Security Key paired when the enrollment finishes.

Authentication

Step 1: Insert your paired Security Key into the USB port of the computer.

Step 2: You should see Smartcard icon displayed as an additional login option.

Step 3: Click on the icon and type your PIN.

Step 4: Click enter on your keyboard or the submit arrow to login.

De-registration

📘
Security Key PIV Reset
De-registration resets the entire PIV area on a security key which may include the PIN, PUK, management key, and certificate area.

🚧
Security Key must be plugged in
Make sure to insert your Security Key into the USB port when initiating de-registration

Step 1: Open the app and click the trash icon to remove your paired Security Key.

Step 2: Confirm the deregistration request

Updating PIN

Step 1: Open the app and click on edit button for your paired Security Key.

Step 2: Enter your current and new PIN. Click on FINISH button to save.

Troubleshooting

Enrollment

The user's computer is not connected to a VPN during the pairing process.

Problem
I click on security key button and see an error message about the company network.

Solution

Ensure that the user is connected to VPN.
Close the application.
Open the application and try to pair again.

security key isn't plugged in

Problem
I click on security key button and see an error message that my security key isn't plugged in.

Solution

Plugin the security key into the USB port.
Try to pair again.

Entered PIN doesn't meet complexity requirements

Problem
User will see "Try a stronger combination" message when clicking on the FINISH button

Solution

Type stronger PIN combination. (e.g. "190753" instead of "123456")

"New PIN" entered doesn't match "Confirm New PIN."

Problem
User sees "PINs do not match" message when clicking on FINISH button

Solution

Ensure that "New PIN" and "Confirm New PIN" fields are matching (e.g., you need to enter "123098" PINs in both fields)

User entered incorrect PIN too many times

Problem
Users see "Too many failed attempts" message when trying to enroll.

Solution

Admin needs to reset the PIV of the security key and ensure that users know the default PIN value.

The user typed the same new PIN as the current one.

Problem
Users see "Please use a different PIN" message when trying to enroll.

Solution

User should use a different PIN, which is different from the current PIN.

Authentication

The user tried to authenticate with invalid PIN 3 times.

Problem
User see "The smart card is blocked" message when trying to authenticate

Solution

Admin needs to reset the PIN on the security key.
User needs to re-enroll with the new PIN.

Certificate not found on the security key not found.

Problem
User see "No valid certificates were found on this smart card" message when trying to authenticate

Solution

Reboot the computer and try again.
Attempt to log in with other authentication methods and try again.
Unplug the security key and plug it back. Try again.

User is not connected to the secure network

Problem
User see "The revocation status for the domain controller certificate card authentication could not be determined." message when trying to authenticate

Solution

Connect to company VPN and try again.
Ensure that the computer can reach the domain controller and try again.