How to configure passbolt to use Yubikey OTP

Passbolt Pro Edition since v2.5 supports Yubikey OTP as a multi factor authentication option. Yubico OTP is a simple authentication mechanism that is supported by all YubiKeys out of the box.

fig. Using a Yubikey at login

Security considerations

It is important to enable and setup at least one additional multi factor authentication provider in case the user lose its Yubikey or the the Yubicloud service becomes temporarily not available.

During a login attempt the passbolt will check if the key ID used by the user is the same that was used during setup. To change key (if the key was lost for example) a user will need to first disable the Yubikey provider in their settings.

Get a Yubikey cloud api key

In order to use Yubikey OTP you need get an API key for Yubicloud, Yubico’s web service for verifying OTPs. Please note that while it is possible to host yourself the OTP validation server, this approach is not supported by Passbolt at the moment.

fig. Yubicloud registration

Before using YubiCloud, you need to get an API key from upgrade.yubico.com in order to prevent misuse of the service. You will need to authenticate yourself using a Yubikey One-Time Password and provide your e-mail address as a reference, as well as read and accept the terms of service.

Make sure YubiCloud urls are whitelisted

In order to verify a Yubikey OTP passbolt will need to connect to YubiCloud. If you prevent outgoing connection from Passbolt server to the following domains:

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

One or more of these domains may be used to try to validate an OTP.

Set the configuration in passbolt

You can configure Yubikey OTP using either the admin interface, config files or environment variables. If multiple settings providers are used the settings in the admin interface will override the one used in files. Similarly the settings in files will override environment variables.

Using admin user interface

Since v2.6 a user interface is provided for administrators to setup MFA providers. Click on “administration” in the top menu, then “multi factor authentication” on the left menu. You can then enable or disable the Yubikey provider by providing the user id and secret key that you gathered in the previous steps. Click “save settings” when you are done.

fig. MFA organization settings for Yubikey

Using environment variables

When you using docker to set these environment variable you can pass them as arguments, like other variables such as the database name, for example:

$ docker run --name passbolt \
             -p 80:80 \
             -p 443:443 \
             -e PASSBOLT_PLUGINS_MFA_YUBIKEY_CLIENTID=12345 \
             -e PASSBOLT_PLUGINS_MFA_YUBIKEY_SECRETKEY="xx/xxxxxx/xxxxxxxxxxxx=" \

Using config file

In your install directory you can add the following section in config/passbolt.php

'plugins' => [
    'multiFactorAuthentication' => [
        'providers' => [
            'totp' => true,
            'duo' => false,
            'yubikey' => true
        ],
        'yubikey' => [
            'clientId' => '01234',
            'secretKey' => 'xx/xxxxxx/xxxxxxxxxxxx='
        ]
    ]
]

Setting Yubikey for a given passbolt user account

Once you have a the Yubikey integration configured and Yubikey plugged in your computer you can proceed with enabling Yubikey as provider for your user account. It is important you test this to make sure the integration works.

fig. MFA provider selection for passbolt user

When logged in passbolt go to your profile section and click on “Multi factor authentication” in the left sidebar. You should see the list of providers that are enabled for this instance. Click on the Yubikey provider. Passbolt will then prompt your to touch your Yubikey to enter a one time password.

The next time you try login from a new device, you will be presented with a Yubikey authentication prompt.

fig. Login prompt