Duo integrates with Okta to add two-factor authentication and self-service device management with Duo Universal Prompt.
Duo Security’s authentication platform secures access to Okta, extending two-factor protection to applications launched from an Okta browser session.
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:
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.
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.
Previously, the Client ID was called the "Integration key" and the Client secret was called the "Secret key".
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!
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 |
 |
 |
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.
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:
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.
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.
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.
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.
Log into your Okta account as an administrator and click the Admin button.
Navigate to Security → Identity Providers and click Add identity provider.
Click the Open ID Connect IdP to select it and then click Next.
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. |
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.
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. |
Click Finish to create the new Duo custom factor-only IdP.
Navigate to Security → Multifactor.
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.
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.
Click the Inactive button and select Activate to enable the Duo IdP factor.
For more information about Okta OIDC identity providers please see Create an Identity Provider in Okta in the Okta Developer reference.
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.
Navigate to Security → Authentication. Click the Sign On tab.
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.
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.
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 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.
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.
At the next step, click the Enroll button to be redirected to Duo.
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.
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 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.
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.
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.
Log into your Okta account as an administrator and click the Admin button.
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.
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.
While still viewing the Duo Security factory type, click the Inactive button and select Activate to enable Duo.
Click the Security menu at the top and go to Authentication. Click the Sign On tab.
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.
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.
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.
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.
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.