YubiKey Provisioning

Provisioner repository: https://github.com/DefGuard/YubiKey-Provision

Compatibility

Some Yubikey's will not be compatible with this feature.

This feature was tested only on Yubikey series 5, we don't support older series ( some still might work).

Conditions below needs to be met:

• Yubikey needs to return serial number via ykman list

• Yubikey needs to have available and active OpenPGP application. You can check out your series capabilities on yubico website here.

• Yubikey needs to support RSA 4096, older series can have problem with this especially with older firmware versions.

Overview

Our provisioning service (installed on a computer that has USB access and securely communicating with defguard) allows you to easily create and populate the SSH and GPG/OpenPGP keys on a YubiKey hardware key, and share its public information inside defguard - which can be used for example to authenticate to servers using defguard.

Defguard allows also of uploading/managing any GPG/SSH keys in the user profile.

It's completely safe, defguard does not store private keys. Every key is provisioned inside an encapsulated session so any gpg-related files are deleted right after the process ends successfully or not. Only public PGP and SSH keys are sent to defguard so you can access them at any time.

GPG keys warning!

That also means that the master key is deleted and only sub-keys are stored - so you will not be able for example to edit the GPG key and add additional emails, etc - as that requires the master key to be imported to GPG.

As we do not want to store any private keys for security reasons, we have some ideas and plans for optional master-key storage based on HSM encryption, but we want to see if any actual companies/users need that, as there is always a way just to overwrite the existing YK and provision with new data.

Prerequisites

If you want to use solutions other then docker, the provisioning station needs to have both gpg2 and ykman programs on the provisioning machine.

Installation of provisioning service

The provisioning service is required as we need physical access to the USB and to the YK device.

It's good for example to prepare a provisioning station in your organization that will be available for just plugging in new YK's and provisioning them with ease..

Currently, we provide Linux .rpm and .deb packages alongside Docker image, but provisioning clients can also be compiled and run under Windows and MacOS.

Note that if you decide to use Docker make sure your container has access to host machine devices, otherwise, you will encounter No keys detected error.

Configuration

All of the available options are described in the help:

yubikey-provision -h

CLI options and configuration

Configuration can be provided in CLI with options, in environment variables, or via .env file.

Name	Description	Required	CLI option	Environment variable	Default value
Provisioner ID	Shown in Defguard UI		--id	WORKER_ID	YubikeyProvisioner
Log level	Sets logging level		--log-level	LOG_LEVEL	info
GRPC Endpoint	Url of your Defguard instance GRPC endpoint. Make sure you include http or https !		--grpc	GRPC_URL	http://127.0.0.1:50055
GRPC CA File	Path to CA file. Needed if you want GRPC to use TLS. You don't need to change http in endpoint if this is present.		--ca-file	GRPC_CA
Authorization Token	Authorization Token found in Defguard UI on Provisioners page.		--token	DEFGUARD_TOKEN
Detection retries	How many times provisioner will check for YubiKey presence in system before abandoning the process.		--smartcard-retries	YUBIKEY_RETRIES	1
Retry interval	How long between retries provisioner will wait ( in seconds )		--smartcard-retry-interval	YUBIKEY_RETRY_INTERVAL	15
GPG debug level	Sets debug level for gpg command during gpg operations		--gpg-debug-level	GPG_DEBUG_LEVEL	none

Example command

Example of working command to run a provisioner.

This will run the provisioner with an id of "example" for instance with GRPC endpoint on 50055.

yubikey-provision --id example --token <TOKEN> --grpc http://localhost:50055

Client access token

To register a new provisioning client you will need an access token provided by your instance. You can find it in the info card on the "Provisioners" page.\

Example of use

This path describes how the admin can provision a key for a user, but the same provisioning modal is also available to the users on the user profile if any workers are available on the instance.

web applicationYou can see available clients in Defguard web-application under "provisioners" tab.

To provision the key:

1. select the user from "Users" page in Defguard web application (or go to "My Profile" if you're provisioning a key for yourself)\

2. insert a YubiKey to machine that is running the provisioner client.

3. select "Add YubiKey" from the actions menu for a User in the list.\

   
4. select your provisioner and click the "Provision YubiKey" button.\

   

The service will take a short moment to prepare and provision your keys. Once the process is done, the modal will close and you will see a notification in the corner of the screen.

After provisioning a YK with serial number and all keys details will be visible in yousr profile:

Common problems

YubiKey is not detected by the client

If the client will not detect your YubiKey, it may work if you unplug and plug it back into your machine. If you are running on Linux, try to restart the pcscd service. If you are using a docker image, make sure the container has access to your host devices.

Provisioning failed / IO Error in logs

This is very similar to Yubikey not detected issue. If run under VM with no direct access to host USB devices, the provisioner or rather gpg program itself can have trouble with sending proper commands to YubiKey smartcard. In this case, ensure that gpg can access the smartcard and write into it from VM without problems, for testing this, follow this guide from Yubico.

Failed to register worker

This error is most commonly caused by your provisioner having problems making a connection to the defguard GRPC endpoint. Make sure to:

• Include http:// in your GRPC URL.

• Run docker on the host network with the --privileged option. If you are using a docker container.

• The host that runs the provisioner can connect to the defguard GRPC endpoint.