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.
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
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.
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
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
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
--privileged
option. If you are using a docker container.The host that runs the provisioner can connect to the defguard GRPC endpoint.
Last updated
Was this helpful?