Skip to main content

Tutorial: Use PKCS#11 Hardware Tokens for VPN Connections (YubiKey)

Abstract

Use hardware tokens like YubiKey with PKCS#11 to authenticate VPN connections in OpenVPN Access Server. Learn how to import certificates and configure OpenVPN Connect for secure login.

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:

Note

PKCS#11 hardware token support requires OpenVPN Connect 3.3 or newer and is available on Windows and macOS.

Important

OpenVPN Connect 3.5 supports loading ECC certificates when you use hardware tokens such as YubiKey. Use RSA-based certificates for other versions. Access Server 2.9 and newer supports multiple CAs per server.

Prerequisites

Note

This guide uses YubiKey as an example. If you use another hardware token, refer to the vendor's documentation for equivalent steps.

Step 1: Create and prepare the connection profile

Important

In these steps, replace <USER_NAME> with the target VPN username.

  1. Connect to the Access Server console and get root privileges.

  2. 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.ovpn

    Optional: 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.ovpn

  3. Extract the client certificate:

    sed -n '/<cert>/,/<\/cert>/p' yubico-profile.ovpn | sed '1d;$d' > yubico-cert.crt

  4. Extract the private key:

    sed -n '/<key>/,/<\/key>/p' yubico-profile.ovpn | sed '1d;$d' > yubico-private.key

  5. Remove 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.ovpn

  6. Create 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>"

  7. When prompted (twice), enter a password for the P2 file.

  8. 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)

Step 2: Import the certificate into the hardware token

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 (.crt and .key).

  • Import as a single file (.p12 or .pfx).

Option 1: Import certificate and key as separate files

Using Yubico PIV Tool (CLI)

  1. Ensure your hardware token (YubiKey) is connected to your PC.

  2. Open Command Prompt and navigate to:

    cd C:\Program Files\Yubico\Yubico PIV Tool\bin

  3. Run yubico-piv-tool commands to import the client certificate and private key.

  4. Confirm your files are available, for example:

    C:\Users\<USER>\Documents\YUBICO\yubico-cert.crt
C:\Users\<USER>\Documents\YUBICO\yubico-private.key

  5. Import 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.

      Important

      Ensure you import the private key and certificate into the same slot on the token (for example, slot 9a).

Using YubiKey Manager (UI)

  1. Ensure your hardware token (YubiKey) is connected to your PC.

  2. Open YubiKey Manager and confirm that your hardware token is connected.

  3. Go to Applications → PIV.

  4. Click Configure Certificates.

  5. Under the Authentication tab:

    • Click Import and select yubico-cert.crt.

    • Click Import again and select yubico-private.key.

    Note

    You won't see the private key listed, but if you see a message like, "Private key was imported into slog 9a", the import was successful.

Option 2: Import certificate and key as a single file (.p12 or .pfx)

Using YubiKey Manager (UI)

  1. Ensure your hardware token (YubiKey) is connected to your PC.

  2. Open YubiKey Manager and confirm that your hardware token is connected.

  3. Go to Applications → PIV.

  4. Click Configure Certificates.

  5. Under the Authentication tab:

    • Click Import.

    • Select the .p12 file (for example, yubico.p12).

Step 3: Configure the PKCS#11 module

Follow these steps to ensure OpenVPN Connect can recognize the vendor module.

Windows

  1. Press Windows + R to launch the Windows Run prompt.

  2. Enter sysdm.cpl and press Enter to launch the System Properties window.

  3. Click Advanced to access the Environment Variables button.

  4. Under System Variables, highlight Path and click Edit.

  5. Click New and add C:\Program Files\Yubico\Yubico PIV Tool\bin, then click OK.

  6. Go to C:\Program Files\Yubico\Yubico PIV Tool\bin and copy the file named libykcs11.dll.

  7. Go to C:\Program Files\OpenVPN Connect and create a new folder named pkcs11_modules.

  8. Open the new directory and paste the libykcs11.dll file you copied in step 6.

macOS

  1. Locate the library: /usr/local/lib/libykcs11.x.x.x.dylib

    Example: libykcs11.2.3.1.dylib. Ensure it's a file, not a symlink.

  2. 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.dylib

    Note

    Use the version number (x.x.x) from step 1.

    • If the .pkcs11_modules directory doesn't exist, an error is displayed.

      ln: /Users/brandon/.pkcs11_modules/libykcs11.dylib: No such file or directory

      If an error appears, create the directory:

      mkdir ~/.pkcs11_modules

  3. 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.dylib

  4. Verify the setup:

    ls -al .pkcs11_modules

    Note

    In this guide, we use version 2.3.1 from the Yubico PIV Tool website. If you use a different version, verify your version in the /usr/local/lib/ directory and adjust the file name accordingly (libykcs11.x.x.x.dylib).

Step 4: Assign the hardware token to the connection profile

  1. Close OpenVPN Connect if it's running.

  2. Open OpenVPN Connect v3.

  3. Import the connection profile, yubico-profile.ovpn.

  4. Click Menu → My Profiles.

  5. Click or tap the Edit icon for the profile.

  6. Under Certificate and Key, click Assign.

  7. Under Hardware Tokens, select the hardware token from the list and click Authorize.

  8. Enter a PIN for the hardware token, then click OK.

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

  10. Save the connection profile configuration.

Step 5: Connect with a connection profile and hardware token

Now that you have a certificate and key assigned to the profile, you can connect using the connection profile and the hardware token (YubiKey).

  1. Start the connection.

  2. Enter your user credentials (if required).

  3. 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

    Important

    Keep the hardware token connected during the connection process.

In this section:

A file with the information for a VPN client to securely connect to Access Server.

The VPN client app to connect to Access Server.