Multi-factor Authentication - Duo
Last modified on September 6, 2023
Duo Security is available as a multi-factor authentication (MFA) option for your StrongDM users. This guide describes how to set up and configure MFA using Duo.
Set Up Duo
The first part of the setup process takes place in the Duo Admin panel. Log in as an administrator of your Duo account and perform the following steps.
- Go to Applications and click Protect an Application.
Duo/Applications - From the list of application types, find Web SDK and click Protect.
Web SDK - Be sure to note the client ID, client secret, and API hostname, as they are needed later.
Details/Keys - Under Settings, set up the policy, name, voice greeting, and other options according to your organization’s preferences.
- Save changes.
You are done here. Keep this browser window open to copy the key and API information when setting up StrongDM in the next section.
Set Up StrongDM
The setup continues in the StrongDM Admin UI.
- Go to Settings, then Security, and scroll down to Multi-factor Authentication.
- Click to unlock the fields and allow changes. Then select Duo from the dropdown menu.
- Using the values you noted in the Duo Admin panel, paste the client ID into the Integration Key field, the client secret into the Secret Key field, and API hostname into the Duo API URL field.
- Click Test to test the MFA settings. This requires your admin account to be registered as a user in Duo.
Click Save to enable Duo MFA. This displays a warning message that users cannot log in without MFA enrollment going forward.
Ensure that Test MFA is successful before activating MFA or your admin account may become locked out!
Log in With Duo MFA Enabled
The login process once Duo MFA is enabled includes only one change. After entering the username and password, the login page contains a “Waiting for MFA…” message, which displays until the Duo challenge is accepted. The process of logging in to the desktop app or the CLI with Duo MFA enabled is similarly altered.
Register a New User With Duo MFA Enabled
When Duo MFA is enabled, the new user registration process halts when the user clicks the link in the invitation email, and then displays a link to the Duo self-enrollment process. Once the enrollment steps are complete, the user can return to the StrongDM window to finalize the login process.
Troubleshoot MFA With Duo
You may run into issues authenticating your StrongDM account with Duo MFA enabled. The following topics can help you troubleshoot any errors you receive while logging in.
MFA alongside SSO
When you set up an SSO provider to authenticate with StrongDM and also enable MFA in the Admin UI, MFA prompts during logins do not occur. In this scenario, your configured MFA only plays a role to re-authenticate users when the desktop app locks due to inactivity, not during normal login attempts.
If using SSO, we recommend setting up MFA through your SSO provider to also trigger MFA prompts during user logins.
Duo username mismatch with StrongDM username
If a username in Duo does not match a StrongDM username (which is typically an email address), you need to create an alias in Duo for that user. These usernames must match to take advantage of Duo MFA for a particular user.
Authentication errors with Duo
| Error | Description | Resolution |
|---|---|---|
| Could not find a valid MFA device | Your Duo-configured device cannot receive push alerts. | Contact your Duo administrator to register another device. |
| Could not push a notification to MFA device | Duo was not able to send a push to your device. | Contact your Duo administrator. |
| Invalid MFA configuration | Your organization’s MFA configuration is not correct. | Contact your StrongDM administrator. |
| MFA denied access | When the push alert arrived, you denied access. | Log in again and accept when the push arrives. |
| MFA did not return a response in time | Duo did not receive an accept/deny from your device in time. | Try logging in again and accept/deny when the push arrives. |
| MFA refused to authenticate this user | Duo has preemptively denied authentication. | Contact your Duo administrator. |
| User not enrolled in MFA | You are not enrolled with Duo. | Contact your Duo administrator. |
New device setup or reset
If you get a new mobile device or have to reset your existing device, you may be unable to log in to your Duo-protected account. If this situation occurs, please contact your organization’s Duo administrator to provision your device.