Configure Duo Security authenticator

You can add Duo Security as a multifactor authentication (MFA) option in Okta. When enabled as an authenticator, Duo Security is the system of record for MFA and Okta delegates secondary verification of credentials to your Duo Security account.

If you have a Duo Security deployment with existing enrollments, make sure that your Duo Security usernames match the Okta usernames or email addresses of your Okta users. When an end user signs in to Okta or accesses an Okta-protected resource, Okta looks up the user in your Duo Security account according to the user’s Okta username or email address. You can change username mapping as described in this topic.

End users without an existing Duo Security enrollment can self-enroll during sign in or through their Duo Security account page. Depending on your Okta integration settings in Duo Security, end users can enroll with a smartphone, tablet, telephone, Touch ID, and security keys.

Before you begin

In Duo Security, integrate your Duo Security account with Okta. Integration generates the following values, which you’ll enter in the Okta Admin Console later:

  • An integration key
  • A secret key
  • An API hostname

Add Duo Security as an authenticator

  1. In the Admin Console, go to Security > Authenticators.
  2. On the Setup tab, click Add Authenticator.
  3. Click Add on the Duo Security tile.
  4. In Settings, enter the values you generated in Duo Security when you integrated with Okta:
    • Integration key
    • Secret key
    • API Hostname
  5. From the Duo Security username format dropdown list, select a format:
    • Okta username
    • Email
    • SAM Account Name
  6. Click Add.
  7. Enroll Duo Security in a multifactor policy.

Enroll Duo Security in a multifactor policy

  1. In the Admin Console, go to Security > Authenticators.
  2. On the Enrollment tab, add a new or edit an existing multifactor policy:

    Add a policy:

    1. Click Add Multifactor Policy.
    2. Enter a name.
    3. Assign the policy to groups.
    4. Set Duo Security to Optional or Required.
    5. Click Create Policy.

    Edit a policy:

    1. Select the policy you want to edit, and then click Edit.
    2. In the Eligible authenticators list, set Duo Security to Optional or Required.
    3. Click Update Policy.
  1. To add one or more rules to the policy, see Configure an authentication enrollment policy rule.

End-user experience

The end-user experience depends on whether users are already enrolled in Duo Security before you configure it as an authenticator in Okta.

New Duo Security enrollments

  1. After you configure Duo Security as an authenticator in Okta, end users signing in to Okta or accessing an Okta-protected app are guided to enroll themselves in Duo Security.
  2. The end user clicks Set up and is prompted to select the type of device they're adding. Here's the user experience for two commonly-chosen device types:
    • Mobile phone: The user is prompted to enter their phone number and select a country and their device type (for example, Android or iOS). The user may also be prompted to receive a text or a phone call to verify their ownership of the phone number. Then the user is prompted to install the Duo Mobile app or indicate that it's already installed. Lastly, the user is prompted to activate their enrollment by scanning a QR code or clicking the option Email me an activation link instead.
    • Touch ID: The user follows onscreen prompts to enroll with Touch ID. During the flow the user is prompted to scan their fingerprint. Depending on the Okta authentication policy, the user may also be prompted to set up another authenticator such as a security question.

After choosing a device during self-enrollment, end users can add devices if the option Add a new device appears in Duo Mobile settings. To enable that option, the Duo admin must select the Self-service portal in the Duo Admin Panel.

Existing Duo Security enrollments

  1. After you configure Duo Security as an authenticator in Okta, an end user signing in to Okta or accessing an Okta-protected app sees an option to verify their identity using Duo Security as an authenticator.
  2. The end user selects the Duo Security option.
  3. During sign-in, the end user may be prompted for additional verification depending on your authentication policy or settings in your Duo Security deployment. End users verify their identity by selecting an authentication type that is supported by their device.

End user settings in the Duo Mobile app

When enrolling in or authenticating with Duo Security, end users can access the Settings menu in the Duo Mobile app for the following options:

Important considerations

  • Okta denies access to any end user (including Okta admins) whose Duo Security account is in a Disabled or Locked Out status. Depending on your Okta authentication policy, these end users may not be able to sign in to Okta-protected resources using a different authenticator.
  • Okta Support can’t reset Duo Security devices for their users. Only a Duo Security administrator can reset the status of Duo Security accounts. As a best practice, make sure that you have multiple Duo Security administrators and that your Okta admins have multiple registered devices.
  • Resetting an authenticator in an end user’s Okta profile doesn’t reset their account in Duo Security. Likewise, if users remove Duo Security from Extra Verification in their End-User Settings page in Okta, the enrollment remains in Duo Security. In this case, to allow the end user to enroll in a different Duo Security authentication method, delete their enrollment in the Duo Security Admin Panel. Otherwise, the end user continues to be prompted with the same method they were using before the authenticator was reset or removed in Okta.
  • If the user is on a Windows device, the Touch ID option is grayed out in the Duo Security app.