Configure the 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 a 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. This generates the following values. Record these values and enter them 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, select a format:
    • Okta username
    • Email
    • SAM Account Name
  6. Click Add.
  7. Enroll Duo Security in a multifactor policy. See Create an authenticator enrollment policy for instructions.

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 that 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 authenticator 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, users see Duo Security as an authentication option when they sign in to Okta or access an Okta-protected app.
    or
  2. The user selects Duo Security.
  3. During sign-in, the user may be prompted for additional verification, depending on how your authentication policy or Duo Security deployment are configured. To verify their identity, users select an authentication type that their device supports.

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 disabled or locked. 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 the Security Methods section on their Okta Settings page, 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 uses a Windows device, the Touch ID option isn't available in the Duo Security app.

  • MFA for Remote Desktop Protocol (RDP) doesn't support the Duo Security authenticator.

  • The third-generation Sign-In Widget doesn't support the Duo Security authenticator.