Help Search

How to configure passbolt to use Duo OTP

Passbolt Pro Edition since v2.5 supports 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.

Duo website fig. Duo website

Important: Multi Factor Authentication is part of Passbolt Pro only and is not available in the Community Edition.

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 use Duo authentication the user will need to interact with an iframe with content served by 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 install the Duo mobile app on their phone or tablet.

Duo mobile application fig. Duo mobile application

Get a Duo account

If do not have one 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 passbolt application in Duo.

Duo administration fig. Duo administration

When login in Duo Admin panel in the left menu, click on “Applications”, then click on “Protect an Application”. Find the “Web SDK” application and click on “Protect this Application”.

Note down the Integration Key, Secret Key, and API Hostname details, as you will need them to configure the integration.

Set the configuration in passbolt

You can either configure Duo in passbolt using the user interface, or files or environment variables. If multiple settings provider are used the settings in the UI will override the one used in files. Similarly The settings in files will override environment variables.

You will need to generate a random 40 character string to be used as salt, to help secure your integration.

Using admin user interface

Since v2.6 a user interface it 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.

MFA organization settings for Duo fig. MFA organization settings for Duo

Using environment variables

Variable name Description Type
PASSBOLT_PLUGINS_MFA_DUO_SALT Random salt string (40 chars min.)
PASSBOLT_PLUGINS_MFA_DUO_INTEGRATIONKEY Integration key string
PASSBOLT_PLUGINS_MFA_DUO_SECRETKEY Secret key string
PASSBOLT_PLUGINS_MFA_DUO_HOST Host string


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

Using config file

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

 'plugins' => [
        'multiFactorAuthentication' => [
            'providers' => [
                'totp' => true,
                'duo' => true,
                'yubikey' => false
            ],
            'duo' => [
                'salt' => 'THIS_MUST_BE_AT_LEAST_FOURTY_CHARACTERS',
                'integrationKey' => 'CCCCPRC95FF3FW21FR5SJ',
                'secretKey' => '7tkYNgxxXaGAuv3KWYYqhsJLfIc1NBnHDYC1siNYX',
                'hostName' => 'api-21e9fcfce.duosecurity.com'
            ]
        ]
    ]
]

Setting Duo for a given passbolt user account

Once you have a the Duo integration configured and Duo app installed on your mobile you can proceed with enabling Duo as provider for your user account. It is important you test this to make sure the integration works.

Passbolt duo setup fig. Passbolt duo setup

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 Duo provider. Passbolt will then display an iframe that will help you setup your device if this is the first time you are using Duo with this instance. 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.

Login prompt fig. Login prompt

Last updated

This article was last updated on November 15th, 2018.

Are you experiencing issues with Passbolt Pro Edition?

Contact Pro support

or ask the community