Skip navigation
Documentation

Duo Multifactor for Okta

Last Updated: September 23rd, 2021

Contents

Duo integrates with Okta to add two-factor authentication and self-service device management with Duo Universal Prompt.

Overview

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

Prerequisites

Ensure your Okta tenant has the features necessary for Duo as an OIDC factor. Without these features in place you may not see all the options and settings needed for configuration.

  • Okta Classic customers - Contact Okta Support and request that they enable these features in your Okta tenant:

    • TOP_WINDOW_REAUTH_FROM_ENDUSER_SETTINGS
    • STATE_TOKEN_ALL_FLOWS
    • CLAIMS_AS_FACTOR
    • GENERIC_OIDC_IDP
  • Okta Identity Engine customers - You should already have the required features enabled in your Okta tenant.

Custom factor-only identity providers and sign-on policies created for Duo in Okta Classic should remain intact through an Okta Identity Engine tenant migration. If you have concerns about your upcoming platform migration please contact Okta support.

Connectivity Requirements

This application communicates with Duo's service on 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 this Duo KB article.

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 Okta 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!

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

Okta has already updated their hosted Duo Okta application to support the Universal Prompt, so there's no action required on your part to update the application itself. You can activate the Universal Prompt experience for users of new and existing Duo Okta applications from the Duo Admin Panel.

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 Duo custom OIDC IdP in Okta, the "Universal Prompt" section of the Okta application page reflects this status as "New Prompt Ready", 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 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 "Update 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.

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 in-scope for Universal Prompt support. 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.

Duo Custom IdP Factor

Adding Duo as a custom IdP (identity provider) factor lets you use it as a step in your sign-on policies so that users log in to Okta with the Duo Universal Prompt. You will need to copy several values from your Okta application in the Duo Admin Panel to the Okta Admin Console.

Create the Duo OIDC IdP

  1. Log into your Okta account as an administrator and click the Admin button.

  2. Navigate to SecurityIdentity Providers and click Add identity provider.

  3. Click the Open ID Connect IdP to select it and then click Next.

  4. Configure the following "General settings" and "Client details" information, copying and pasting information from the "Details" section of your Okta application in the Duo Admin Panel as needed:

    Name Give this custom provider a descriptive name ("Duo OIDC MFA" in the example).
    IdP usage Use the drop-down to select Factor Only.
    Scopes Remove the email and profile scopes, leaving only openid.
    Client ID The Client ID or Integration key from your Duo Okta application.
    Client Secret The Client secret or Secret key from your Duo Okta application.
    Authorize requests Check the box to Enable signed requests and select HS256 from the "Algorithm" drop-down. If you do not see this option, you may be missing a required Okta feature and should contact Okta support before continuing.
  5. Return to the Okta application page in the Duo Admin Panel. Click + Show More shown underneath the "API hostname" value to view additional values. If you do not see + Show More on the Okta application page then stop and contact Duo Support. Do not continue with setup until you can view the additional information.

  6. Configure the "Endpoints" information in Okta, using the additional information from the Duo Admin Panel:

    Issuer The Issuer URL from your Duo Okta application.
    Authorization endpoint The Authorization endpoint URL from your Duo Okta application.
    Token endpoint The Token endpoint URL from your Duo Okta application.
    JWKS endpoint The JWKS endpoint URL from your Duo Okta application.
    Userinfo endpoint (optional) Leave blank.
  7. Click Finish to create the new Duo custom factor-only IdP.

  8. Navigate to SecurityMultifactor.

  9. Click On IdP Factor in the list of factory types. IMPORTANT: Do not click the "Duo Security" factor type. This is the legacy traditional Duo Prompt application.

  10. Verify that the new Duo OIDC custom IdP is shown in the "IdP Factor Settings". If it is not shown, click Edit and select it, clicking Save when done.

  11. Click the Inactive button and select Activate to enable the Duo IdP factor.

    Okta IdP Duo OIDC Factor

For more information about Okta OIDC identity providers please see Create an Identity Provider in Okta in the Okta Developer reference.

Update your Sign On Policies

Now that you have created the Duo factor-only custom OIDC IdP you can add it to your global or application sign-on policies (depending on your Okta tenant's platform). Both Okta Classic and Okta Identity Engine tenants can specify an IdP in a global sign-on policy from the Okta Admin Console. Okta Identity Engine users should note that the Okta Admin Console UI does not support adding an IdP in an application policy today. Refer to the Okta Policy API documentation to learn how to add IdP to an application

Here is an example of adding the Duo IDP factor in a new sign-on policy in Okta Classic.

  1. Navigate to SecurityAuthentication. Click the Sign On tab.

  2. You can either add a new rule for Duo Authentication to an existing Okta sign-on policy, or create a new policy for Duo and assign it to specific groups. This example creates a new policy for Duo OIDC authentication and assigns it to a group.

    Click on the Add New Okta Sign-on Policy button, enter a descriptive name and description for the new policy, and select the group you want to target with this new policy. click Create policy and add rule.

    New Okta OIDC Sign On Policy
  3. Enter a name for your new Duo rule and exclude any users you don't want using Duo when logging in to Okta. Check the Prompt for Factor box to enable secondary authentication and determine whether you want 2FA required "Per Device", "Every Time", or "Per Session". Choose your desired options for the other rule settings and click Create Rule when finished.

    New Okta OIDC Sign On Rule
  4. The Okta sign-on policy shows your new Duo rule.

    Okta OIDC Sign On Policy with Duo OIDC Rule

Learn more about creating Okta policies or see additional information about configuring Duo authentication in the Okta online help center.

Please contact Okta support if you have any questions about the integration or need assistance configuring your authentication and multifactor settings. Contact Duo Support for assistance with the Duo service.

Test Your Setup

Test your new Duo OIDC factor-only IdP by logging in to Okta as a user subject to a sign-on policy that requires the Duo IdP factor.

  1. Okta prompts users who have not yet registered use of the Duo OIDC IDP factor to setup multifactor authentication at the first login to Okta after Duo OIDC is enabled. Click the Setup button for your Duo OIDC IDP factor.

    Okta User Duo OIDC Setup
  2. At the next step, click the Enroll button to be redirected to Duo.

    Okta User Duo OIDC Enroll
  3. Okta 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.

    OIDC Duo Prompt
  4. After completing Duo enrollment or authentication, Duo redirects back to Okta to complete Okta's multifactor setup. Click Finish to complete logging into Okta.

    Okta User Duo OIDC Finish

Future logins to Okta will prompt you to complete verification with the Duo OIDC MFA factor after you enter your Okta credentials. Click Verify to be redirected to Duo for two-factor authentication and you'll return to Okta after 2FA success. If more than one factor is activated then Okta remembers the last one used and should default to it next time.

Okta User Duo OIDC Login Verification

Migration from Duo MFA Factor to Duo OIDC Factor

Plan to migrate your users to the new Duo OIDC IdP factor from the legacy Duo Security MFA factor (with traditional Duo Prompt) in stages. When both the IdP factor and the Duo Security MFA factor are active, then users subject to an effective sign-on policy that requires multifactor will see both the traditional Duo Prompt factor and the new Duo OIDC factor available for them to use in Okta.

The recommendation from Okta is to leave your existing Duo Security MFA factor intact and create a new Okta application in Duo to use for the IdP factor. Then, pilot enrollment in both the legacy Duo Security factor and the new Duo OIDC IdP factor in Okta with expanding groups of users. When your users have completed registration of the new Duo OIDC factor in Okta, you can phase out the original Duo Security MFA integration.

Educating your users about what to expect during the migration period is essential to your success. Contact Okta support for assistance with planning sign-on policies and rules to support your migration.

Duo MFA Factor

The Duo MFA factor option for Okta shows the traditional Duo Prompt in an iframe. We encourage you to set up Duo as an OIDC factor-only IdP instead, which provides users with the Duo Universal Prompt experience. Existing users of the legacy Okta Duo MFA factor option should plan your migration to OIDC factor.

  1. Log into your Okta account as an administrator and click the Admin button.

  2. Navigate to SecurityMultifactor. Click on Duo Security then click the "Duo Security Settings" Edit button. If you don't see Duo Security listed, contact Okta Support to have it enabled on your account.

    Okta Authentication Settings
  3. Fill out the form with your Duo Okta application information as follows.

    Integration Key Your integration key (i.e. DIXXXXXXXXXXXXXXXXXX)
    Secret Key Your secret key
    API Hostname Your API hostname (i.e. api-XXXXXXXX.duosecurity.com)
    Duo Username Format Select the name format used to log in to Okta.

    Click the Save button when done.

    Enter Okta Duo Application Information
  4. While still viewing the Duo Security factory type, click the Inactive button and select Activate to enable Duo.

Update your Sign On Policies

  1. Click the Security menu at the top and go to Authentication. Click the Sign On tab.

  2. You can either add a new rule for Duo Authentication to an existing Okta sign-on policy, or create a new policy for Duo and assign it to specific groups. In this example, we'll turn on Duo for all users in the "Default Policy".

    Click on the Default Policy, and then click the Add Rule button. Enter a name for your new Duo rule and check the Prompt for Factor box to enable secondary authentication and determine whether you want 2FA required "Per Device", "Every Time", or "Per Session". Choose your desired options for the other rule settings and click Create Rule when finished.

    Okta Authentication Factors
  3. The Okta sign-on policy shows your new Duo rule.

    Okta Sign On Policy

Learn more about creating Okta policies or see additional information about configuring Duo authentication in the Okta online help center.

Please contact Okta support if you have any questions about the integration or need assistance configuring your authentication and multifactor settings. Contact Duo Support for assistance with the Duo service.

Test Your Setup

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.

Okta prompts new, unenrolled Duo users to setup multifactor authentication at the first login to Okta after Duo is enabled. Click the Setup button for Duo Security.

Okta User Duo Setup

A "Setup Duo Security" window displays the Duo enrollment prompt. Complete Okta's multifactor setup by stepping through Duo enrollment.

Okta Duo Setup Wizard

When Duo enrollment is completed, users can choose one of the Duo authentication options to access Okta.

Okta Duo Authentication

Troubleshooting

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