YubiKey Provisioning
Provisioner repository: https://github.com/DefGuard/YubiKey-Provision
We only support (and tested) Yubikey 5.
Yubikey 4 should work - we have not tested.
Other Yubikeys - especially NEO (which has slots for RSA GPG/PGP keys) will not work, as YK NEO has only 2048 key length slot, which is commonly treated as unsecure for RSA key length.
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.
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:
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 | --grpc | GRPC_URL | ||
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.
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:
select the user from "Users" page in Defguard web application (or go to "My Profile" if you're provisioning a key for yourself)
insert a YubiKey to machine that is running the provisioner client.
select "Add YubiKey" from the actions menu for a User in the list.
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
--privilegedoption. If you are using a docker container.The host that runs the provisioner can connect to the defguard GRPC endpoint.
Last updated
