Duo Multifactor for Okta

Overview

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

Prerequisites

Okta Requirements

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 to allow use of the Open ID Connect IdP identity provider:

  • 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. If unsure, confirm with Okta Support.

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.

Enable Automatic IdP Redirection

Okta's default external IdP login experience inserts a "Verify" button that users will need to click to be redirected to Duo to complete authentication. Streamline this experience by configuring your org to automatically redirect users to Duo when they log in. We recommend enabling this option before proceeding. This applies to both Okta Identity Engine and Okta Classic.

1. Log into your Okta account as an administrator and click the Admin button. The Admin Console opens in a new page.

2. Navigate to Settings → Features.

3. Locate the "Early access" feature Skip the verify screen and redirect to the IdP authenticator in the list and toggle it on to enable.

Duo Requirements

Duo MFA for Okta with Universal Prompt is available to Duo Premier, Duo Advantage, and Duo Essentials commercial plans.

Migration from Duo MFA Factor to Duo OIDC Factor

Plan to migrate your users to the new Duo OIDC IdP factor with Duo Universal Prompt 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 and disable the "Duo Security" legacy factor.

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.

First Steps

1. Sign up for a Duo account.

2. Log in to the Duo Admin Panel and navigate to Applications → Application Catalog.

3. Locate the entry for Okta with the "2FA" label in the catalog. Click the + Add button to create 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 with 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!

4. No users can log in to new applications until you grant access. Update the User access setting to grant access to this application to users in selected Duo groups, or to all users. Learn more about user access to applications. If you do not change this setting now, be sure to update it so that your test user has access before you test your setup.

Duo Universal Prompt

The Duo 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

If you created your Okta application before March 2024, 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, before you activate the Universal Prompt for your application.

New Okta Applications

When you configure Duo in Duo custom OIDC IdP in Okta for the first time, you're ready to use the Universal Prompt. Okta applications created after March 2024 have the Universal Prompt activated by default. If you're configuring Okta now, proceed with the installation instructions in this document.

The "Universal Prompt" area of the application details page shows this application as "Activation complete", with these activation control options:

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

Existing Okta Applications

You'll need to migrate to a different configuration in Duo custom OIDC IdP in Okta to use Duo Universal Prompt. Follow the directions.

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 "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.

In addition, the "Integration key" and "Secret key" property labels for the application update to "Client ID" and "Client secret" respectively. The values for these properties remain the same.

Enable the Universal Prompt experience by selecting Show new Universal Prompt if the traditional prompt is still selected, 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.

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. Keep in mind that support for the traditional Duo prompt ended for the majority of applications in March 2024.

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.

Duo Custom IdP Authenticator in Okta Identity Engine

Adding Duo as a custom IdP (identity provider) authenticator 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 in Okta Identity Engine

1. Log into your Okta account as an administrator and click the Admin button. The Admin Console opens in a new page.

2. Navigate to Security → Identity Providers and click + Add identity provider.

3. Click the OpenID Connect IdP tile to select it and then click Next. If you do not see OpenID Connect IdP on the Okta application page then stop and contact Okta Support to confirm your Okta tenant has the necessary features. You cannot continue with setup without the OpenID Connect IdP option.

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. If you do not see this option then stop and contact Okta support.
   Scopes	Remove the email and profile scopes, leaving only openid.
   Client ID	The Client ID or Integration key from your Duo Okta application.
   Authentication type	Leave set to Client secret.
   Client Secret	The Client secret or Secret key from your Duo Okta application.
   Authorize requests	Check the box to Enable signed requests and then select HS256 from the "Algorithm" drop-down that appears. If you do not see this option, you may be missing a required Okta feature and should contact Okta support before continuing.
   Proof key for code exchange (PKCE)	Do not enable this option.

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.

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. The optional "Authentication Settings" may or may not need changing depending on how you identify your Okta users in Duo. The default values will try to match Okta Username to the user in Duo by email address (from idpuser.email). You can adjust these to correctly identify your users in Duo with the value that matches a user value in Okta. See the Okta guide for Enterprise Identity Provider for more information.

8. Click Finish to create the new Duo custom factor-only IdP authenticator.

9. Navigate to Security → Authenticators.

10. Click Add authenticator and click Add under "IdP Authenticator". Select the Duo OIDC custom IdP you created earlier from the "Identity Provider (IdP)" drop-down. Click Add.

    

11. The new Duo OIDC custom IdP you created should now be shown in the list of authenticators on the "Setup" tab.

    

12. Click the Enrollment tab on the "Authenticators" page. Here you can choose to modify the default enrollment policy to set the Duo factor-only IdP authenticator to be required for all users, or create a custom enrollment policy by clicking Add a policy and specifying an Okta user group to receive the new policy requiring enrollment in the Duo IdP authenticator.

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

Update your Authentication Policies in Okta Identity Engine

Now that you have created the Duo factor-only custom OIDC IdP authenticator you can add it to your global or application sign-on policies (depending on your Okta tenant's platform). If migrating from the legacy Okta "Duo Security" factor to a replacement IdP factor then you should have policy rules guiding your users to the desired factor experience. Okta Identity Engine tenants can specify an IdP in a global sign-on policy from the Okta Admin Console, but 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 a simple example of adding the Duo IDP factor in a new authentication policy in Okta Identity Engine.

1. Navigate to Security → Authentication Policies. Click Add a policy.

2. Enter a descriptive name and description for the new policy and then click Save.

3. Determine whether you want to edit the "Catch-all" rule to require the Duo factor-only IdP authenticator or if you want to create a new rule in the policy to apply Duo IdP authentication to users based on conditions you specify, like group membership, IP address, or device platform.

   If you do want to create a new rule in the new policy for Duo authentication, click Add rule. Enter a name for the new rule and configure the "IF" conditions for the rule as desired.

4. To add Duo authentication using the Duo OIDC IdP factor, in the "THEN" section of the rule editor set User must authenticate with to Password / IdP + Another Factor (from the "2 factor Types" selections in the drop-down).

5. Next, in the "Authentication methods" rule, you should ensure that the "Your org’s authenticators that satisfy this requirement" box shows the Duo factor-only IdP authenticator you created as the Additional factor types selection. The first authenticator could be Password or some other authenticator that is not the Duo IdP.

6. Finally, make your re-authentication frequency selections. Choose how often you want users subject to this policy to have to log in with Duo by changing the Prompt for all other factors of authentication setting in the "When to prompt for authentication" section.

7. When you have finished editing the rule, click Save. The new authentication policy reflects your configured Duo IdP requirement.

Here is an example of a simple authentication policy with a rule requiring password plus Duo IdP authentication at every sign-in attempt by members of the "Duo Users" group, while the catch-all rule allows any users not targeted by the Duo rule to sign in with only a password.

Learn more about creating Okta OIE authentication policies 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 or creating sign-on policies incorporating a Duo factor. Contact Duo Support for assistance with the Duo service.

Duo Custom IdP Factor in Okta Classic

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 in Okta Classic

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

2. Navigate to Security → Identity Providers and click Add identity provider.

3. Click the Open ID Connect IdP to select it and then click Next. If you do not see Open ID Connect IdP on the Okta application page then stop and contact Okta Support to confirm your Okta tenant has the necessary features. You cannot continue with setup without the Open ID Connect IdP option.

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. If you do not see this option then stop and contact Okta support.
   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.

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 Security → Multifactor.

9. Click On IdP Factor in the list of factor 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.

    

12. After activating the IdP factor go to Security → Multifactor → Factor Enrollment to set the new IdP Duo factor to either Optional or Required.

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 in Okta Classic

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). If migrating from the legacy Okta "Duo Security" factor to a replacement IdP factor then you should have policy rules guiding your users to the desired factor experience. Okta Classic and tenants can specify an IdP in a global sign-on policy from the Okta Admin Console.

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

1. Navigate to Security → 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. 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.

   

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.

   

4. The Okta sign-on policy shows your new Duo 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 or creating sign-on policies incorporating a Duo factor. 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.

   

2. At the next step, click the Enroll button to be redirected to Duo.

   

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.

   If you had set up Duo as an Okta MFA factor and opted to reuse the same Duo Okta application when creating a Duo OIDC factor in Okta then you may still see the traditional Duo Prompt in Okta instead of the Universal Prompt. Completing at least one Okta OIDC factor authentication to a pre-existing Duo Okta application using the traditional Duo Prompt is required before you can enable the Universal Prompt experience for that Okta application in Duo.

   

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.

   

Future logins to Okta will redirect you to complete verification with the Duo OIDC MFA factor after you enter your Okta credentials. You'll return to Okta after Duo 2FA success. If more than one factor is activated, Okta remembers the last one used and should default to it next time.

If your users have to click a "Verify" button before proceeding to Duo authentication, double-check that you enabled the Skip the verify screen and redirect to the IdP authenticator feature in your Okta org's settings.

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 Okta application in the Duo Admin Panel and activate the Universal Prompt for future logins.

Grant Access to Users

If you did not already grant user access to the Duo users you want to use this application be sure to do that before inviting or requiring them to log in with Duo.

Duo MFA Factor

Configure the Duo Factor

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

2. Navigate to Security → Multifactor. 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.

   

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.

   

4. While still viewing the Duo Security factor 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.

   

3. The Okta sign-on policy shows your new Duo 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

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.

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

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

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.

Network Diagram

1. Okta client connection initiated
2. Primary authentication at Okta cloud service.
3. OIDC redirect to Duo's service.
4. Secondary authentication and client access device checks via Duo Universal Prompt.
5. Okta receives Duo authorization response.
6. Okta user login complete.