YubiKey Provisioning
Provisioner repository: https://github.com/DefGuard/YubiKey-Provision
Last updated
Was this helpful?
Provisioner repository: https://github.com/DefGuard/YubiKey-Provision
Last updated
Was this helpful?
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.
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 .
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.
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.
All of the available options are described in the help:
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 of working command to run a provisioner.
This will run the provisioner with an id of "example" for instance with GRPC endpoint on 50055.
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.\
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:
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.
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.
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 from Yubico.