Duo Directory Sync from Okta for Duo Users

Overview

Import Duo end-users directly from your Okta cloud service into Duo with Duo Security's inbound SCIM integration.

Duo Directory Sync is a one-way operation. No information from Duo is imported into your Okta directory. Okta’s User Import feature is not supported.

The Directory Sync feature is part of the Duo Premier, Duo Advantage, and Duo Essentials plans.

Note that SCIM provisioning from Okta does not support import and management of Duo administrators.

Prerequisites

Before setting up Okta sync, ensure you have the following:

• A Okta directory account.
• A Okta admin account with sufficient privileges to create applications.
• You must have the Duo Owner, Administrator, or User Manager admin role to set up and manage import of Okta users into Duo.

Role required: Owner, Administrator, or User Manager.

Set Up SCIM Integration

You will need to create the inbound Okta SCIM integration in Duo and optionally map any additional user attributes. When your setup is complete, you'll receive API credentials you'll need to enter in the Okta Admin Console.

To start setting up an Okta SCIM integration:

1. Log in to the Duo Admin Panel.

2. Navigate to Users → External Directories or click the External Directories link on the "Users" page.

3. Click the Add External Directory button and select Okta from the list.

4. The new SCIM connection's name defaults to "New Okta SCIM Integration". Click the pencil icon to the right of the name if you'd like to change it to something different, clicking Save to apply the new name.

You can click Save progress at any time to save your configuration without creating the API credentials.

Attribute Mapping

Make changes here if you want to customize which Okta attribute values get imported to Duo. These Duo user attributes are required and have already been mapped to Okta SCIM attributes:

SCIM Attribute	Duo User Attribute
userName	Username
email	Email Address
givenName	First Name
familyName	Last Name

To import additional user attributes from Okta:

1. Click + Add mapping to open the "Add mapping" list of available attributes.

2. Select the additional user attributes you want to import from Okta into Duo. You can select individual attribute, or use Select all to add all SCIM attributes listed. Click Add mapping when done.

   

3. For each additional attribute, use the Duo user attribute drop-down to select a destination attribute in Duo for the imported information. If there's already a suggested Duo user attribute you can use the suggestion or change it to something else. Some attributes may already have a Duo user attribute defined which cannot be changed.

   

   If you don't already have a Duo user attribute created to map a given Okta attribute to, you can create a new user attribute to use for mapping by typing in the desired Duo user attribute name and clicking + Add.

Delete any added attribute you don't want to map by clicking the trash can icon to the right.

Enrollment Emails

Select the Send enrollment emails to synced users option if you want imported users to automatically receive an enrollment email. Only users imported with active status, a valid email address, and who do not already have any enrolled authentication devices in Duo receive an emailed link. The email address is populated from Okta.

Default: Not enabled.

The enrollment link sent when a user is first imported is valid for 30 days. Duo sends an emailed enrollment reminder if the user hasn't yet completed enrollment after two days, and then a second reminder if the user remains unenrolled eight days after the first reminder.

If the user does not complete the enrollment process after 30 days has elapsed, the original enrollment link expires and a new enrollment link is generated and sent to the user. This entire 30-day cycle repeats until the user completes Duo enrollment.

The contents of the enrollment email subject and body can be changed on the global Settings page. The enrollment email body should contain the placeholder text "<enrollment-link>", which will be replaced by the link to the enrollment form when the email is sent. The sent message will have a non-editable header added, informing the user it's an automated message sent by Duo and to contact their organization's Duo admins or IT support group with any questions.

If your organization uses e-mail filtering, be sure to allow the sender no-reply@duosecurity.com.

Finish Okta SCIM Setup

Click Complete Setup to finish creating the new Okta external directory SCIM integration in Duo. The page refreshes to show the information you need to enter in Okta in the "API Credentials" section.

Leave this page open in your browser.

Configure SCIM in Okta

Create the Duo SCIM Application

1. In a new browser tab or window, log into your Okta account as an administrator and click the Admin button. The Admin Console opens in a new page.

2. Navigate to Applications → Applications and click Browse App Catalog.

3. On the "Browse App Integration Catalog" page, search for the Duo Security SCIM Provisioning application. Click on it to view more details, and then click Add Integration.

4. On the Duo integration's "General Settings" tab, do the following:

   1. Update the Application label if desired.

   2. Copy the Base URL from the "API Credentials" section of the Okta SCIM integration page in the Duo Admin Panel, and paste it into the Okta Base URL field.

      Example: https://api-nnnnnnnn.duosecurity.com/scim/v2

   3. Enable the Do not display application icon to users option.

   4. Click Done.

Configure Provisioning

1. Next, go to the "Provisioning" tab and do the following:

   1. Click Configure API Integration.

   2. Select Enable API integration to expose the credentials fields.

   3. Copy the Bearer Token from the "API Credentials" section of the Okta SCIM integration page in the Duo Admin Panel, and paste it into the Okta API Token field.

   4. Click Save to return to the "Provisioning" tab.

2. With To App selected under "Settings" on the left, click Edit on the right side of the "Provisioning to App" section.

3. We recommend enabling all the available provisioning options: Create Users, Update User Attributes, Deactivate Users, and Sync Password. Note that Duo does not import passwords from external directories.

4. Click Save to apply the provisioning options.

Assign Users or Groups and Push Groups

1. Go to the "Assignments" tab of the Duo SCIM application.

2. You can assign the Duo SCIM application to either individual users or groups.

   To assign the app to users:

   1. Click Assign → Assign to People.

   2. Click Assign to the right of each user you want to import to Duo. For each user you assign, you have the opportunity to enter or modify attribute values during the assignment step.

   3. Click Save and go back after reviewing each user's information, and then click Done to finish user assignment.

   To assign the app to groups:

   1. Click Assign → Assign to Groups.

   2. Click Assign to the right of each group of users you want to import to Duo. For each group you assign, you have the opportunity to override the default attributes sent during provisioning during the assignment step.

   3. Click Save and go back after reviewing each group's attribute settings, and then click Done to finish group assignment.

3. If you assigned the application to groups, go to the "Push Groups" tab.

4. Click Push Groups → Find groups by name.

5. Enter the name of the Okta group you assigned to the Duo SCIM application and select it from the list.

6. Leave the Push group memberships immediately option selected and the "Match result & push action" option set to Create Group.

7. If you assigned more than one Okta group to the Duo SCIM application, click Save & Add Another and repeat steps 5 and 6.

8. Click Save when all your assigned groups have been added to the list of groups to push. The "Push Groups" tab now shows information about the push status for the selected groups.

Learn more about Group Push in the Okta documentation.

Verify Provisioning

If you return to your Okta SCIM integration in the Duo Admin Panel, you should now see the groups you assigned and pushed to the Duo SCIM application in Okta have been created in Duo and show up in the "SCIM Managed Groups" section of the page.

User Enrollment and Activation

After importing users from your directory into Duo, your next step is to have them activate their devices for Duo authentication (if you chose not to send enrollment emails to synced users when creating your directory in Duo). On the Users page you'll see a notification bar indicating that users have not yet activated the Duo Mobile smartphone app. Click the link in the notification bar to begin the process of sending these users activation links via SMS message or email.

For more information on user activation, see Activating Duo Mobile After Enrollment.

If you did choose to send enrollment emails to synced users automatically, the Pending Enrollments table shows which users created by directory sync and SCIM integrations (or bulk enrollment) have not yet completed enrolling their 2FA devices in Duo, along with the user's email address and the expiration date for the enrollment link previously sent.

If you need to send a user another copy of the enrollment link email, click the Resend button on the right of that user's information, or click Resend All to send the email again to all users with outstanding enrollment links. Resending the email does not change the current enrollment link's expiration date and uses the same email address that was used when the original enrollment was sent.

Click Delete to remove a pending enrollment. Deleting a pending enrollment immediately invalidates any unexpired enrollment link previously sent to that user. The next time directory sync runs, a new enrollment link will be emailed to that user, as long as they remain a member of a synced group and the external directory configuration still has the "Enrollment Email" option enabled.

Manage User Sync

Role required: Owner, Administrator, or User Manager except where noted in the sections below.

Once configured, you can update the sync settings and attributes.

To access your configured sync:

1. Log in to the Duo Admin Panel. Navigate to Users → External Directories or click the External Directories link on the "Users" page.

2. The "SCIM Integrations" tab lists all your inbound SCIM external directory connections and shows their connection status, type, and last update time. Select the integration you want to manage by clicking on its name in the list.

3. Perform your management actions from the properties page.

Update Users or Groups

If you want to change the Okta users or groups you assigned to the application, or initiate an immediate push from Okta to Duo, log in to the Okta Admin Console and navigate to Applications → Applications → your Duo SCIM application.

When you update users in Okta, changes get pushed immediately to Duo.

To initiate a group push from Okta to Duo, go to the "Push Groups" tab of the Duo SCIM application. For the group you want to push, click on the status of that group and select Push now from the drop-down.

Regenerate Bearer Token

The Okta SCIM integration's bearer token expires every 90 days. When the Duo Okta integration's bearer token expires then pushes from Okta will fail. We'll send an "Action required" email to all the Duo administrators with the "Owner" role to let them know starting 15 days before the token expires.

When you visit your Okta external directory configuration page in the Duo Admin Panel, the bearer token will show it's expired. You'll need to regenerate the token and update Okta with the new token information to resume pushes.

1. Log in to the Duo Admin Panel.

2. Navigate to Users → External Directories or click the External Directories link on the "Users" page.

3. Go to the "SCIM Integrations" tab and click on the disconnected Okta SCIM integration.

4. The "API Credentials" section of the page shows that the token has expired. Click Regenerate token to create a new one. Keep this browser tab open.

5. Log into the Okta Admin Console in a new browser tab or window and navigate to Applications → Applications → your Duo SCIM application.

6. Go to the "Provisioning" tab, and in the "Settings" list on the left click on Integration.

7. Click Edit on the right. Copy the new Bearer token value from the Duo Admin Panel and paste it into the API Token field in Okta.

8. Click Save.

Delete External Directories

Deleting a directory from Duo doesn't delete or disable any of the previously imported objects. When you delete a directory from Duo, then the users, phones, and groups formerly managed by that directory remain available and get converted to unmanaged Duo objects that can be manually updated or deleted.

• Users previously imported remain available and retain the status previously assigned, whether applied to the synced group or to the individual user. Any authentication devices associated with the user remain available. The users retain their former group memberships.

• Groups previously synced remain available and retain the same members and status assigned when they were managed by the sync. The group name changes from Group name from type of sync "name of sync" to Group name (formerly from "name of sync").

• Phones previously imported remain in Duo attached to the same users. Activation status remains unchanged.

To delete an external directory SCIM integration, click Delete SCIM Integration at the top-right of that integration's details page and confirm that you want to delete that integration.

Manage Synced Users and Groups

Sync Multiple Directories in Duo

You can configure multiple syncs with different source directories of any type and import all those users and groups into Duo. If you do this, ensure that the users you select for import have unique names.

If the same username exists in two different sync directory sources, the first sync you create will create or manage the user. Subsequent syncs with the same username get a sync error preventing the sync from affecting those users with the message "Cannot sync a user belonging to another directory sync unless that sync is paused". You can view the error in the Administrator Actions report for that sync's "completed" event. This error only affects the user in question; it doesn’t halt the sync.

If you want a different sync to be allowed to manage those users (for example to migrate users from one sync to another), you will need to pause the automatic scheduled syncs on the directory sync which currently manages those users.

Update Synced User Information

User attributes imported from an external directory cannot be edited in Duo via the Admin Panel, Admin API, or CSV import. This always applies to the required attributes username, display name, email address, plus phone numbers (if you chose to import phones), and group memberships. Changes to these user attributes should be made in the external directory and then synced over to Duo.

You may edit Duo user properties that aren't imported from Okta via the Admin Panel, Admin API, or CSV import, including those that correspond with optional Okta sync attributes you chose not to import. However, if you update your SCIM integration to begin importing values for a previously unconfigured optional attribute, the sync will overwrite any previously configured values with the information imported from Okta.

Examples:

• You do not specify an attribute mapping for Notes when you create your Okta directory integration. The sync imports the username, email address, and name information from Okta, but imports no notes information. You can edit the "Notes" field for synced Duo users, but you may not edit the "Username", "Display Name", "First Name", "Last Name", or "Email Address" properties for synced users.

• You specify a source attribute for Username Alias 1 but not for the remaining aliases. The sync imports values for "Username Alias 1" from Okta, and no other aliases. You can't edit "Username Alias 1" for a synced user, but you can edit additional aliases beyond the first.

• You do not specify a source attribute for Username Alias 1. The sync creates users with no aliases, and you manually add values for "Username Alias 1" to some Duo users from the Admin Panel. You update your configured Okta sync to add a source attribute for Username Alias 1. The next push updates the "Username Alias 1" value for all provisioned users to match the value in Okta, overwriting the aliases you added manually.

Bypass Status for Synced Users

Users imported from an external directory may have bypass status assigned individually or at the group level. See the Using Groups and User Status Administration documentation for more information.

Disabled Status for Synced Users

Duo does not import suspended status from Okta directories, so suspending a user in Okta will not also disable the user in Duo. Administrators may update an Okta user's status to "Disabled" from the Duo Admin Panel or Admin API.

You may disable a group of provisioned users by changing the status of that group to Disabled. This prevents any user who is a member of that group from logging in with Duo, regardless of that individual user's status. See the Using Groups and Group Status Administration documentation for more information.

Delete Synced Users

You may not delete a synced user from Duo as long as the external directory is actively managing that user. If a synced directory user is removed from all external directory groups that sync to Duo (or if the user account is deleted from the source directory), the user is sent to the Trash and marked as "Pending Deletion" at the next full directory sync or individual sync for that user, and the user can no longer authenticate to Duo. The user's properties are read-only and you are no longer billed for that user.

Locate users pending deletion in the Trash view, accessed by clicking the Trash count shown at the top of the Users page.

If the user marked for deletion is not reconnected to an external directory account via provisioning within seven days the user is automatically deleted from Duo. The user's properties show the target date for deletion. A Duo admin can manually delete a synced user from the Trash via the Permanently Delete link at any time during those seven days.

Manage Provisioned Groups

Duo groups provisioned from an external directory may only be managed by the sync. You can't change the group's members interactively from the Admin Panel interface, via CSV import, or programmatically with the Admin API.

To update the members of a managed group, make the necessary changes in the source directory and import them into Duo by running a full or single-user sync.

Groups managed by Okta are identified as such in the Admin Panel and Admin API output. When viewing groups in the Admin Panel, you'll see from Okta Sync "name of SCIM integration" appended to the group's name or as the group's description. In Admin API output the sync information is appended to the group's name.

You can have multiple syncs managing groups with the same name (such as a "Duo Users" group managed by AD sync and also a "Duo Users" group managed by Okta sync), or even a manually created "Duo Users" group not managed by any sync. Each sync-managed group only contains Duo user members managed by the same directory sync, and an unmanaged group can only contain users also not managed by any directory sync.

Removing a group from the directory's configuration in Duo marks any members of that group for deletion if they are not members of another synchronized group, and converts the group to unmanaged so it can be modified or deleted from the Duo Admin Panel or Admin API. Duo updates the group's name to indicate it was once managed by directory sync, changing from Group name from Okta Sync "name of SCIM integration" to Group name (formerly from "name of SCIM integration").

Delete Provisioned Groups

To delete a group from Duo that is managed by Okta:

1. Log in to the Duo Admin Panel.

2. Navigate to Users → External Directories or click the External Directories link on the "Users" page.

3. Go to the "SCIM Integrations" tab and click on the disconnected Okta SCIM integration.

4. The "API Credentials" section of the page shows that the token has expired. Click Regenerate token to create a new one. Keep this browser tab open.

5. Log into the Okta Admin Console in a new browser tab or window and navigate to Applications → Applications → your Duo SCIM application.

6. Go to the "Push Groups" tab. Click on the status of the group you want to delete from Duo and select Unlink pushed group from the drop-down.

7. In the "Unlink Pushed Group" confirmation, select the Delete the group in the target app option and click Unlink.

   If you instead choose to leave the group this will create undesired behavior in Duo, where you will not be able to modify or delete the group because it will still be considered managed by Okta.

Okta will delete that group from Duo, but not the users that were in the group. Neither the group nor its users will be deleted from Okta.

Troubleshooting

Need some help? Take a look at the Okta Sync Frequently Asked Questions (FAQ) page or try searching our Okta Directory Sync Knowledge Base articles or Community discussions. For further assistance, contact Support.

You can also learn more about Okta SCIM provisioning concepts in the Okta Developer documentation.

Network Diagram

1. Duo requests directory information from Okta.
2. Users and groups imported to Duo's service.