Skip navigation
Documentation

Duo Two-Factor Authentication for OneLogin

Last Updated: May 24th, 2023

Contents

Duo and OneLogin have partnered on a two-factor authentication solution, offering inline user enrollment, self-service device management, and support for a variety of authentication methods — such as passkeys and security keys, Duo Push, or Verified Duo Push — in the Duo Universal Prompt.

Duo and OneLogin

Duo Security’s authentication platform secures access to OneLogin, extending two-factor protection to web applications launched from a OneLogin browser session.

Connectivity Requirements

This application communicates with Duo's service on SSL TCP port 443.

Firewall configurations that restrict outbound access to Duo's service with rules using destination IP addresses or IP address ranges aren't recommended, since these may change over time to maintain our service's high availability. If your organization requires IP-based rules, please review Duo Knowledge Base article 1337.

Effective June 30, 2023, Duo no longer supports TLS 1.0 or 1.1 connections or insecure TLS/SSL cipher suites. See Duo Knowledge Base article 7546 for additional guidance.

First Steps

  1. Sign up for a Duo account.
  2. Log in to the Duo Admin Panel and navigate to Applications.
  3. Click Protect an Application and locate the entry for OneLogin in the applications list. Click Protect to the far-right to configure the application. and get your Client ID, Client secret, and API hostname. You'll need this information to complete your setup. See Protecting Applications for more information about protecting applications in Duo and additional application options.

    Previously, the Client ID was called the "Integration key" and the Client secret was called the "Secret key".

Treat your secret key like a password

The security of your Duo application is tied to the security of your secret key (skey). Secure it as you would any sensitive credential. Don't share it with unauthorized individuals or email it to anyone under any circumstances!

Configure Allowed Hostnames

If you plan to permit use of WebAuthn authentication methods (security keys, U2F tokens, or Touch ID) in the traditional Duo Prompt, Duo recommends configuring allowed hostnames for this application and any others that show the inline Duo Prompt before onboarding your end-users.

The Duo Universal Prompt has built-in protection from unauthorized domains so this setting does not apply.

Duo Universal Prompt

The new Universal Prompt provides a simplified and accessible Duo login experience for web-based applications, offering a redesigned visual interface with security and usability enhancements.

Universal Prompt Traditional Prompt
 Duo Push in Universal Prompt  Duo Push in Traditional Prompt

OneLogin has already updated their hosted Duo OneLogin application to support the Universal Prompt, so there's no installation effort required on your part to update the application itself. If you're setting up Duo with OneLogin for the first time you can activate the Universal Prompt experience immediately from the Duo Admin Panel.

If you already use Duo with OneLogin you need to make a configuration change in OneLogin, and then log in with Duo 2FA again so that Duo makes the Universal Prompt activation setting available in the Admin Panel. This first authentication after updating the OneLogin setting shows the traditional Duo prompt in a redirect instead of an iframe. After that, activate the Universal Prompt experience from the Duo Admin Panel for users of that Duo OneLogin application.

Before you activate the Universal Prompt for your application, it's a good idea to read the Universal Prompt Update Guide for more information about the update process and the new login experience for users.

Activate Universal Prompt

Activation of the Universal Prompt is a per-application change. Activating it for one application does not change the login experience for your other Duo applications.

Once a user authenticates to the updated OneLogin OIDC flow, the "Universal Prompt" section of the OneLogin application page reflects this status as "Ready to activate", with these activation control options:

  • Show traditional prompt: (Default) Your users experience Duo's traditional prompt when logging in to this application.
  • Show new Universal Prompt: Your users experience the Universal Prompt via redirect when logging in to this application.

Universal Prompt Info - Application Ready for Universal Prompt

Enable the Universal Prompt experience by selecting Show new Universal Prompt, and then scrolling to the bottom of the page to click Save.

Once you activate the Universal Prompt, the application's Universal Prompt status shows "Activation complete" here and on the Universal Prompt Update Progress report.

Universal Prompt Info - Universal Prompt Activation Complete

Should you ever want to roll back to the traditional prompt, you can return to this setting and change it back to Show traditional prompt. However, this will still deliver the Duo prompt via redirect, not in an iframe.

Universal Update Progress

Click the See Update Progress link to view the Universal Prompt Update Progress report. This report shows the update availability and migration progress for all your Duo applications. You can also activate the new prompt experience for multiple supported applications from the report page instead of visiting the individual details pages for each application.

Configure OneLogin

Enable Duo Authentication Factor

  1. Log into your OneLogin account. as an administrator.

  2. Navigate to SecurityAuthentication Factors and click the New Auth Factor button.

  3. Choose Duo Security from the "Partners" section to enable Duo.

  4. Fill out the form as follows and click Save when done.

    User description A descriptive name for Duo authentication factor i.e. "Duo Security".
    Integration Key Your Client ID or Integration key (i.e. DIXXXXXXXXXXXXXXXXXX) from the Duo Admin Panel.
    Secret Key Your Client secret or Secret key from the Duo Admin Panel.
    API Hostname Your API hostname (i.e. api-XXXXXXXX.duosecurity.com) from the Duo Admin Panel.
    Duo OTP Identifier Select the attribute from the list that contains values that match your end users' Duo usernames. In this example the OTP identifier is Email, so OneLogin sends the email attribute value to Duo as the username. Be sure to select an OTP attribute that has unique values populated for all OneLogin users who will log in with Duo.
    OneLogin Duo Application Information
  5. The OneLogin Authentication Factors page now lists Duo Security. You can configure policies that use the Duo factor next.

Configure and Apply User Policy

  1. Navigate to SecurityPolicies in OneLogin and click the New User Policy button.

  2. Give the new policy a descriptive name, such as Duo MFA Policy, and click the checkmark button next to the policy name field to apply.

  3. Navigate to the MFA settings in the policy editor navigation and check the checkbox next to OTP Auth Required in the "One-time passwords" section.

  4. Scroll to the "MFA Device Registration" section. Choose whether you want all users without an MFA device to register one at login (Users without a MFA device must register one before being able to login.), or another option that lets users choose to register an MFA device at login or not.

  5. Scroll down further to the "Enforcement Settings" section and change the OTP required for pull down menu to All users if you want to require everyone who receives this policy to enroll with Duo at login time. If you would like users to be able to optionally enroll with Duo from their OneLogin settings after logging in, Change the OTP required for pull down menu to Configured users only.

    If you want your users to complete Duo authentication at every login leave the OTP required at setting as At every login. Changing the OTP required for pull down menu setting to Unknown browser will present your users with a "Browser not recognized" message after completing Duo two-factor authentication.

    If the user chooses to remember the browser, the next login using that same browser will not prompt for Duo authentication.

  6. Click the Save button to create the new policy.

  7. You can apply the new Duo MFA policy to users in a few different ways.

    • To make the new MFA policy the default for all users, click the More Actions button and choose Set as default policy.

    • To apply the new Duo MFA policy to individual users, navigate to UsersAll Users. Click on a listed user to open the User Info page, and change the Security Policy pull down menu setting to your new Duo MFA policy. Click the Save User button to apply the change.

    • To apply the new Duo MFA policy to a subset of users, you can create a group, add those users to the new group, and apply the policy to just that group. To create a new OneLogin group, navigate to navigate to UsersGroups. Click the NEW GROUP button. Give the new group a descriptive name, such as Duo Users, and click the checkmark button next to the group name field to apply. In the Group Security Policy section change the Security policy pull down menu option to the new Duo MFA group created earlier.

    Navigate back to the All Users page and edit the properties of individual users to add them to the new Duo group so they receive the new MFA policy.

Enable OIDC Flow

The setup steps completed to this point enable the traditional Duo Prompt experience for OneLogin in an iframe. Use of the Duo Universal Prompt in OneLogin requires an additional settings change.

Existing OneLogin and Duo customers also need to complete this step and authenticate once with Duo after saving before you can activate the Universal Prompt for your OneLogin application in the Duo Admin Panel.

If you do not see this option in your OneLogin settings, contact OneLogin support. Once enabled, it affects all users of a Duo auth factor.

  1. Navigate to SettingsAccount Settings in OneLogin.

  2. Locate the "Duo Universal Prompt" setting on the "Basic" page and check the box next to Enable Duo Universal Prompt (OIDC flow).

  3. Click Save.

See the OneLogin online documentation for additional information about configuring Duo authentication.

Test Your Setup

Test your Duo factor by logging in to OneLogin as a user subject to a policy that requires Duo for multi-factor authentication. OneLogin prompts users who have not yet registered use of the Duo auth factor to setup 2-factor authentication after entering the primary username and password.

  1. Click Begin Setup when prompted by OneLogin to be redirected to Duo.

    OneLogin Redirect to Duo
  2. OneLogin redirects to the Duo Universal Prompt, where a user new to Duo can complete first-time Duo enrollment, or an existing Duo user can authenticate using an available method.

    OneLogin Redirect to Duo

    If this is your first login since enabling the Duo OIDC flow in OneLogin then you may still see the traditional Duo Prompt in OneLogin instead of the Universal Prompt. Completing at least one OneLogin Duo OIDC authentication to a pre-existing Duo OneLogin application using the traditional Duo Prompt is required before you can enable the Universal Prompt experience for that OneLogin application in Duo.

    OIDC Duo Universal Prompt
  3. After completing Duo enrollment or authentication, Duo redirects back to OneLogin to complete the login attempt.

Future logins to OneLogin will automatically redirect to Duo for authentication and back to OneLogin when successfully completed.

If you saw the traditional Duo Prompt when you tested Duo as an OIDC factor, then you should now be able to go to that OneLogin application in the Duo Admin Panel and activate the Universal Prompt for future logins.

Legacy Experience

If you did not enable the Duo OIDC flow in your OneLogin settings then your users have this experience.

  1. Click Begin Setup when prompted by OneLogin to be redirected to Duo.

    OneLogin Redirect to Duo
  2. If the user is new to Duo they'll see the Duo new enrollment prompt. The user can follow the instructions to enroll an authentication device in Duo for use with OneLogin.

    OneLogin Duo Enrollment
  3. The next time a user logs in after completing enrollment, Duo Security's two-factor authentication will be ready to use! Users can approve a Duo Push authentication request from a smartphone or tablet, approve authentication over the phone, or enter a passcode generated via the Duo Mobile app, text message, or hardware token.

    OneLogin Duo Authentication

If your MFA user policy is set to require OTP for configured users only, your OneLogin users will need to manually configure Duo after login by clicking on the username in the top right side of the OneLogin window, and selecting Profile from the menu.

Once on the Profile page, the user sees that no Duo device exists in the "2-Factor Authentication"section, and clicks the plus sign icon to Add Device.

OneLogin presents the Duo enrollment or authentication prompt to the user.

OneLogin Duo Enrollment

After completing enrollment or authenticating with a previously enrolled device, the user's profile shows Duo as a registered 2-Factor authentication device.

The next time the user logs on to OneLogin the Duo two-factor authentication prompt is shown after primary username and password submission.

Troubleshooting

Need some help? Reach out to Duo Support for assistance with creating the OneLogin application in Duo, enrolling users in Duo, Duo policy questions, or Duo authentication approval issues. For assistance configuring or managing OneLogin please contact OneLogin support.