How to configure passbolt to use Duo OTP

Passbolt Pro Edition since v2.5 and CE since 3.9 support Duo as a multi factor authentication option. Duo is a proprietary solution that is free for up to 10 users, and supports a bundle of authentication channels (such as HOTP, mobile push, phone calls, etc.) configurable by the Duo account administrator.

fig. Duo website

Security considerations

It is important to enable and setup at least one additional multi factor authentication provider in case Duo service becomes temporarily not available.

In order to authenticate using Duo, the user will be redirected to Duo’s authentication page. Whether or not the authentication was successful, the user will be redirected back to passbolt. Make sure your users have access to internet or do not enable this authentication provider if you are running passbolt on a private network that is not connected to internet.

Install Duo app

In order to use this authentication provider, each of your users will need to have either:

• Duo Mobile for Android on google play store.
• Duo Mobile for iOS on apple itunes.
• TouchID fingerprint reader on MacOS laptops
• A security key
• A physical token
• A network administrator

fig. Duo mobile application

Register a Duo administrator account

If you do not have a Duo admin account, first sign up at https://signup.duo.com/ Then log in to the Duo Admin panel at https://admin.duosecurity.com/login

Configure your Duo policies as required by your organization.

Add a passbolt application

In order for passbolt to enable onboarding and authentication of new users with Duo, you will need to create a Web SDK application for passbolt in Duo.

Login to the Duo Admin page. In the left-hand side menu, click on “Applications”, then click on “Protect an Application”.

fig. Duo protect application

Find the “Web SDK” application and click on the “Protect” button.

fig. Duo administration

Note down the Client ID, Client secret, and API hostname details, as you will need them to configure the integration.

Generate a random salt

Generating a random salt to configure Duo is mandatory, a salt is a random piece of data that is generated and used in the hashing process to protect sentivite information. It is generated and combined with the secret key before hashing it.

To generate a random salt, you can use the passbolt interface, generate a new password as shown below and use it as the generated salt.

fig. Passbolt - Password Generator

Set the configuration in passbolt

You can configure Duo OTP using either the admin interface or environment variables. If multiple settings providers are used the settings in the admin interface will override the one in environment variables. Note that we recommend using the admin interface, since it is more secure.

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 Duo provider by providing the API Hostname, the Client ID and the Client Secret that you gathered in the previous steps. If you are running a Passbolt version below 3.11 you will also need the generated salt. Click “save settings” when you are done.

fig. MFA organization settings for Duo

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_DUO_API_HOSTNAME=api-26e9f2fce.duosecurity.com \
             -e etc.

Setting Duo for a given passbolt user account

Once you have the Duo integration configured and a Duo authentication device, you can proceed with enabling Duo as MFA provider for your user account. It is important that you test this to make sure the integration works.

When logged in on passbolt, go to your profile section and click on “Multi factor authentication” in the sidebar on the left. You should see the list of providers that are enabled for this instance. Click on the Duo provider.

fig. Passbolt Duo setup

Then, click on the “Sign-in with Duo” button to start the Duo authentication process. If this is the first time you are using Duo with this user and this server, you will be asked to link one or more device(s) to Duo to authenticate with.

fig. Duo welcome screen

fig. Duo authentication options

Follow the instructions provided by Duo and you should be all set. The next time you try login from a new device, you will be presented with a Duo authentication prompt.

fig. Login prompt