Introduction
LogonBox supports user authentication using the service from Duo Security. This method of authentication works along with an app on a mobile phone to provide multi-factor authentication.
This article explains how to configure your LogonBox to use this method.
IMPORTANT: This article is valid for any LogonBox product versioned 2.3.8 or greater.
1. Configuring the Authentication Scheme
It is important to note that you can apply different authentication flows for different types of logon: User Logon, Password Reset, Client, Account Unlock, SSO, Windows Login, Password Vault and Admin Logon.
Each of these can have their own default authentication flow configured, but for this article we shall alter Password Reset.
Navigate to Authentication Flows->Schemes->Password Reset and click the Edit button. Note that by default this is configured with a blue Username module and a green User Selective 2FA one.
Duo is a green module, so it must exist along with either a blue or orange module, which we already have here.
Let’s keep the existing Username module and replace the Security Questions module. Click the delete icon on User Selective 2FA and add the Duo module by clicking the plus icon next to Duo to add it into the authentication flow.
Click Save at the bottom.
2. Creating a Duo Security account
You must now configure LogonBox to allow it to connect to Duo Security to check the authentication. Navigate to Authentication Flows->Authentication Options and select the Duo Tab.
You will need a Client ID, a Client Secret and an API Hostname, which you can get from Duo.
On this screen, click on the provided link to visit the Duo Security signup page.
Enter all of the information you are prompted for and click Create My Account.
Create a password and click Continue.
At this point, go to the App Store for your phone, find and install the Duo Mobile app, then launch it.
Click the Add Account button and accept any permissions the app may ask for.
The app should have now activated the camera, point the camera at the Duo account creation web page, which should have a QR code visible.
The account should be configured and you can click Continue on the web page to proceed.
Finally, set a backup number and click Finish.
Now, as you have the app open, click Duo Push which will cause your app to prompt for authorisation.
Click on Approve to log in.
3. Setting up the Duo application and completing configuration
After authorising in the last step above, you should now be logged on to the Duo Security web site. We now need to configure LogonBox as an application in Duo.
If you are not at this page already, navigate to Applications->Protect an Application and search for Web SDK.
Click Protect.
You can choose to use the default new Universal Prompt here, although we can work with Duo's old traditional prompt too.
You are shown the 3 items of information you need to configure your LogonBox at the top of this screen, the Client ID, a Client Secret and an API Hostname.
Make a note of these and click Save.
4. Disable Enrolment
The default configuration of Duo is to allow inline enrolment in the Duo service. However, for Password Reset this is a security risk and therefore you may wish to disable this.
We recommend that you set up the Global Policy to deny enrolment. To do this on the Duo web site, navigate to Policies and edit the Global Policy and change the New User policy from Require Enrollment to Deny Access.
Now go back to your LogonBox and edit the Duo settings in Authentication Flow->Authentication Options->Duo. Enter these above values in the relevant places and click Apply.
5. Supporting Enrolment (optional)
If you want to support enrolment of users whilst users are using LogonBox then you can do so. To do this, repeat the process to setup a new application to obtain a second set of Duo API keys. With this configuration you can add an application policy to allow enrolment.
Once you have setup the second Duo application integration. Goto Authentication Flows->Authentication Options and the Duo tab.
Toggle the Enable Enrolment switch to ON and you will see another set of API key fields made available where you can configure the second application integration. When enabled, LogonBox will use these keys on user login authentication schemes to support enrolment. For self-service schemes the first set of configuration items are used.
6. Configuring Duo enrolment status checks (optional)
By default, LogonBox will only be able to get the status of a particular user's Duo enrolment state when that user actually performs an authentication with Duo during a password reset.
This means that a user's profile state would be marked as incomplete until that user has done their first reset.
If you want LogonBox to actively check the Duo enrolment state during its daily profile checks, then you can do so. To do this, repeat the process to setup another new Duo application. This time, using the Admin API application.
Once you have setup the Admin API application, you will have yet another set of credentials, an Integration key, a Secret key and an API hostname.
Goto Authentication Flows->Authentication Options and the Duo tab.
For Admin SDK Client ID, enter the Integration key.
For Admin SDK Client Secret, enter the Secret key.
For Admin SDK API Hostname, enter the SPI hostname.
Note: At the moment you cannot have both the enrolment and the status checks configured at the same time. If you are checking the user enrolment status, then if a user doesn't already exist in Duo, you will not be able to enrol and will receive an Invalid Credentials error. This message can be configured in the End User Not Found Message field.
7. User authentication setup
The first time a user attempts to authenticate with Duo, if you have enrolment enabled they will be prompted to set up their account as soon as they get to the Duo step of the Authentication scheme.
The user should be prompted with this screen, click Next three times.
Select the option you will be using to authenticate with (in this case Duo Mobile).
Select your country and add your telephone number and click Add phone number then confirm by clicking Yes, it's correct.
Confirm ownership of your number by clicking Yes, it's correct, then Send me a passcode.
You will get a passcode delivered by SMS. Enter this code and click Verify.
The user is now prompted to install the app, which we have already done here. Click Next when ready.
In the Duo Mobile app, add a new account and scan in the QR code and press Save.
Duo is now activated for this user, click Continue.
Click Log in with Duo then Authorise the request that appears on your mobile device.
8. Testing
As we have configured this scheme for Password Reset, to test this click on the Reset Password link on the main LogonBox portal. We will show the usual authentication flow after a user has already set up their Duo account.
Enter the username of the user to be reset and click Next.
The Duo authentication then starts.
Approve the request that appears on the mobile app.
The authentication continues and the user is prompted to reset their password.
