Tutorial: Use PKCS#11 Hardware Tokens for VPN Connections (YubiKey)
Overview
This tutorial shows how to use hardware tokens, such as YubiKey, for certificate-based authentication in OpenVPN Access Server using PKCS#11.
You'll learn how to:
Create a connection profile.
Move certificates and keys to a hardware token.
Configure OpenVPN Connect to use the token.
Connect securely using the hardware token.
Prerequisites
Access Server installed.
A hardware token with PKCS#11 support (for example, YubiKey 5 NFC).
Yubico PIV Tool (CLI) installed.
YubiKey Manager (CLI) installed.
Connect to the Access Server console and get root privileges.
Run this command to create a new user-locked connection profile for your user:
sacli --prefer-tls-crypt-v2 --user <USER_NAME> GetUserlogin > yubico-profile.ovpnOptional: Run this command to create a new auto-login connection profile for your user:
sacli --prefer-tls-crypt-v2 --user <USER_NAME> GetAutologin > yubico-profile.ovpnExtract the client certificate:
sed -n '/<cert>/,/<\/cert>/p' yubico-profile.ovpn | sed '1d;$d' > yubico-cert.crtExtract the private key:
sed -n '/<key>/,/<\/key>/p' yubico-profile.ovpn | sed '1d;$d' > yubico-private.keyRemove the client's certificate and private key from the connection profile:
sed -i '/<cert>/,/<\/cert>/d' yubico-profile.ovpn sed -i '/<key>/,/<\/key>/d' yubico-profile.ovpnCreate a PKCS #12 file containing the client certificate and private key:
openssl pkcs12 -export -inkey yubico-private.key -in yubico-cert.crt -out yubico.p12 -name "<USER_NAME>"When prompted (twice), enter a password for the P2 file.
Transfer the files to the client device via WinSCP or SCP:
yubico-profile.ovpn(connection profile)yubico-cert.crt(client certificate)yubico-private.key(private key)yubico.p12(client P12 file)
You can use either a CLI tool, Yubico PIV Tool, or a UI tool, YubiKey Manager. You have two ways to import the certificate and key:
Import as two separate files (
.crtand.key).Import as a single file (
.p12or.pfx).
Option 1: Import certificate and key as separate files
Using Yubico PIV Tool (CLI)
Ensure your hardware token (YubiKey) is connected to your PC.
Open Command Prompt and navigate to:
cd C:\Program Files\Yubico\Yubico PIV Tool\binRun yubico-piv-tool commands to import the client certificate and private key.
Confirm your files are available, for example:
C:\Users\<USER>\Documents\YUBICO\yubico-cert.crt C:\Users\<USER>\Documents\YUBICO\yubico-private.keyImport the client certificate and private key (replace values where appropriate for your setup):
yubico-piv-tool -a import-certificate -s 9a -i <PATH_TO_CERT> yubico-piv-tool -a import-key -s 9a -i <PATH_TO_KEY>If the process succeeds, you should see messages like:
C:\Program Files\Yubico\Yubico PIV Tool\bin>yubico-piv-tool -a import-certificate -s 9a -i C:\Users\<USER>\Documents\YUBICO\yubico-cert.crt Successfully imported a new certificate. C:\Program Files\Yubico\Yubico PIV Tool\bin>yubico-piv-tool -a import-key -s 9a -i C:\Users\<USER>\Documents\YUBICO\yubico-private.key Successfully imported a new private key.
Using YubiKey Manager (UI)
Ensure your hardware token (YubiKey) is connected to your PC.
Open YubiKey Manager and confirm that your hardware token is connected.
Go to Applications → PIV.
Click Configure Certificates.
Under the Authentication tab:
Click Import and select
yubico-cert.crt.Click Import again and select
yubico-private.key.
Option 2: Import certificate and key as a single file (.p12 or .pfx)
Using YubiKey Manager (UI)
Ensure your hardware token (YubiKey) is connected to your PC.
Open YubiKey Manager and confirm that your hardware token is connected.
Go to Applications → PIV.
Click Configure Certificates.
Under the Authentication tab:
Click Import.
Select the
.p12file (for example,yubico.p12).
Follow these steps to ensure OpenVPN Connect can recognize the vendor module.
Windows
Press Windows + R to launch the Windows Run prompt.
Enter
sysdm.cpland press Enter to launch the System Properties window.Click Advanced to access the Environment Variables button.
Under System Variables, highlight Path and click Edit.
Click New and add C:\Program Files\Yubico\Yubico PIV Tool\bin, then click OK.
Go to C:\Program Files\Yubico\Yubico PIV Tool\bin and copy the file named
libykcs11.dll.Go to C:\Program Files\OpenVPN Connect and create a new folder named pkcs11_modules.
Open the new directory and paste the
libykcs11.dllfile you copied in step 6.
macOS
Locate the library:
/usr/local/lib/libykcs11.x.x.x.dylibExample: libykcs11.2.3.1.dylib. Ensure it's a file, not a symlink.
Open Terminal and execute this command to create a symlink to the library file.
ln -s /usr/local/lib/libykcs11.x.x.x.dylib ~/.pkcs11_modules/libykcs11.dylibIf the .pkcs11_modules directory doesn't exist, an error is displayed.
ln: /Users/brandon/.pkcs11_modules/libykcs11.dylib: No such file or directoryIf an error appears, create the directory:
mkdir ~/.pkcs11_modules
Open Terminal and execute this command to create a symlink to the library file.
ln -s /usr/local/lib/libykcs11.2.3.1.dylib ~/.pkcs11_modules/libykcs11.dylibVerify the setup:
ls -al .pkcs11_modules
Close OpenVPN Connect if it's running.
Open OpenVPN Connect v3.
Import the connection profile,
yubico-profile.ovpn.Click Menu → My Profiles.
Click or tap the Edit icon for the profile.
Under Certificate and Key, click Assign.
Under Hardware Tokens, select the hardware token from the list and click Authorize.
Enter a PIN for the hardware token, then click OK.
After successful authorization, select the certificate and key for the connection profile, then click Confirm.
In our example, the client certificate has the username yubico-user, and the private key is Private Key for PIV Authentication.
Save the connection profile configuration.
Now that you have a certificate and key assigned to the profile, you can connect using the connection profile and the hardware token (YubiKey).
Start the connection.
Enter your user credentials (if required).
Enter the hardware token PIN, then click Enter.
✅ Pass: Connection succeeds and displays connection statistics.
❌ Fail: Authentication fails → verify certificate import, module setup, and profile configuration