Skip to main content

How to configure passbolt to use Yubikey

Passbolt Pro Edition since v2.5 and CE since v3.9 support Yubikeys and more precisely Yubico OTP as a multi factor authentication option.

Yubico OTP is a simple authentication mechanism that is supported by all YubiKeys out of the box and it can be used in addition to another authentication method (such as username and password).

Using a Yubikey at login
fig. Using a Yubikey at login
important

Please note than only Yubikey 5 Series are supported. Security Keys with FIDO2/U2F/WebAuthN support are currently not supported.

important

Multi Factor Authentication requires HTTPS to work.

Security considerations

When using Yubikey as a form of multi-factor authentication, it is recommended to set up at least one additional multi-factor authentication method as a backup. Should users lose their Yubikeys, this measure guarantees that users can continue to access their accounts despite the malfunction of one authentication method.

Another key point to consider is that Passbolt verifies whether the key ID used during a login attempt matches the one used at setup. If a user needs to change their key, the second factor must be disabled in advance, either by the user in their User Profile or by an administrator in the Users workspace, especially if the device is lost.

Register to YubiCloud

In order to use YubiKey to authenticate to passbolt you first need get an API key for YubiCloud, Yubico’s web service for verifying one time passwords (OTPs).

Navigate to upgrade.yubico.com and signup to the service using your email and your Yubikey.

Please note that it is no longer possible to host yourself the OTP validation server.

Signup to YubiCloud
fig. Signup to YubiCloud

Allow connections to YubiCloud

To authenticate with Yubikey, passbolt will establish a connection with the YubiCloud service. Make sure that the passbolt server allows outgoing connections to the following domains:

  • api.yubico.com
  • api2.yubico.com
  • api3.yubico.com
  • api4.yubico.com
  • api5.yubico.com

Please note that one or more of these domains may be used to try to validate an OTP.

Enable Yubikey access

Yubikey can be set up through either the administration interface or environment variables. Should both settings providers be utilized, the configurations made in the administration interface will take precedence over those specified by environment variables.

Enable Yubikey access via the interface

To enable YubiKey via the interface, navigate to the multi-factor authentication administration page: Administration > Multi Factor Authentication.

Subsequently, enable the "YubiKey" provider by moving the adjacent toggle to the on position and inputs the information provided by YubliCloud at the previous step. Ensure you save these modifications to activate the provider.

Enable YubiKey in administration settings
fig. Enable YubiKey in administration settings

Enable Yubikey access via environment variables

If you are using docker, you can set these environment variables to enable YubiKey for your organization.

Variable nameDescriptionType
ASSBOLT_PLUGINS_MFA_YUBIKEY_SECRETKEYYubiCloud secret keystring
PASSBOLT_PLUGINS_MFA_YUBIKEY_CLIENTIDYubiCloud client idinteger

Setup YubiKey as a user

To setup YubiKey as multi-factor authentication method, navigate to the multi-factor authentication user settings page: Avatar > Profil > Multi Factor Authentication. Select the provider "YubiKey OTP" to continue.

The next step will require you to plug your YubiKey and touch it to release a Yubico OTP. Then click on "Validate" to ensure it functions correctly and complete the setup.

Register your Yubikey
fig. Register your Yubikey

Authenticate with YubiKey

After setting up YubiKey, each time you sign-in to Passbolt, you'll be prompted to plug your device and touch it to release a Yubico OTP. Additionally, if permitted by the "Multi-factor Authentication Policy", passbolt can remember your MFA authentication for a month.

Authenticate with YubiKey
fig. Authenticate with YubiKey