Skip navigation
Documentation

Synchronizing Users from Azure Active Directory

Last Updated: November 25th, 2019

Learn how to synchronize Duo users and groups from your existing Azure Active Directory (AAD) domain.

Already using Azure Sync? Upgrade to the new sync now!

We've enhanced our Azure AD sync utility, adding new features like source attribute customization and improving performance for full and individual syncs. Experience these benefits today by enabling the new sync for your Azure directory.

Overview

Import Duo user information directly from your Azure Active Directory (AD) cloud service into Duo with Duo Security's Directory Sync feature. Directory attributes that may already be populated include name, email address, phone numbers, and group memberships.

The Directory Sync feature is part of the Duo Beyond, Duo Access, and Duo MFA plans.

Directory Sync Updates Existing Users

Before executing any directory synchronization with Duo, understand the effect that synchronization can have on accounts with the duplicate Duo usernames. Suppose that you already have some active Duo users, and one or more of these users have the same username in Azure. Performing a synchronization will cause the existing Duo users' information to be merged with, and in some cases overwritten by the Azure AD information, such as email addresses present in Duo changing to match the value stored in the synced directory.

Likewise, if you synchronize multiple directories and there are non-unique usernames among those directories, the net result is that there will be only one Duo user created with that username, and each sync will update that Duo user with different information.

The same potential conflict applies to Duo groups. If an existing Duo group has the same name as a synced group, the sync overwrites the group information and membership in Duo with the information from the synced directory. This could affect user access to applications if you previously applied permitted groups restrictions or group policies based on the group membership prior to running directory sync.

Multiple syncs with different source directories that use non-unique group or user names may also produce undesired results, as each sync process will overwrite the group or user with different information.

Prerequisites

Before setting up Azure AD sync, ensure you have the following:

  • A designated Azure admin service account to use for authorizing the sync. This account needs the Azure Global Administrator role during Duo setup, but you can reduce the service account's role privileges later. This service account may or may not require Azure MFA for admins at login (learn more about the baseline MFA policy for Azure admins).
  • Azure AD groups populated with users to sync.
  • Administrator access to the Duo Admin Panel as an owner, administrator, or user manager (see Admin Roles for more information).
  • An application where users sign in with an Azure AD UPN as their username.

Set Up Synchronization

Add the Directory

To start setting up Azure AD synchronization:

  1. Log in to the Duo Admin Panel and click Users in the left side bar. Then click Directory Sync on the submenu or click the Directory Sync button on the Users page.

    If you have any existing on-premises AD or Azure AD directories configured to sync with Duo, they'll be shown here.

  2. Click the New Directory button to begin the process of adding a directory to Duo.

  3. The "New Directory" page presents the Azure Active Directory tab by default. Click the Authorize button to grant Duo access to read information from your Azure AD domain.

    Authorize Azure AD access

  4. Clicking the Authorize button takes you to the Azure AD portal. Sign in with the designated Azure service administrator account that has the global administrator role for this Azure Active Directory. If required, complete Azure MFA for that service account admin user.

    Sign in to Azure

    Duo does not see or store your Azure Active Directory administrator credentials.

    If you are already signed into to the Azure portal as the Duo service account, you may not be prompted to log in again here.

  5. Once you've signed in to Azure, you must click Accept to grant Duo the read rights needed to import users from your Azure AD domain.

    Grant Azure Permissions

  6. Authorizing the Azure application redirects you back to the "New Directory" page in the Duo Admin Panel. Verify that the "Authorization" section correctly shows your Azure AD organization name. If the page lists the wrong Azure AD domain, click the "Start over?" link to begin again.

    If the domain authorization is correct, enter the information required to create the directory in Duo.

    1. Directory name

      Provide a descriptive name for the directory. When you view imported users and groups in Duo, the will indicate that they are managed by the sync with the name you enter here.

    2. Enrollment email

      Select this option if you want imported users to automatically receive an enrollment link email when the sync process completes. 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 by Azure AD sync.

      Default: Do not send enrollment emails to imported users.

      The enrollment link sent when the sync first imports a user 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 at the next sync 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.

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

    3. Synced Attributes

      Select this option if you want to customize which Azure AD attribute values get imported to Duo. The Duo attributes that have default Azure AD attributes defined indicate those defaults as helper text. You can change these default attributes to custom attributes of your choice. Return to using the default attributes by clicking Revert all attributes to default.

      You may customize the Azure AD source attributes for these Duo user properties:

      Username

      Required. The source attribute for the Duo username. The attribute selected should match the primary authentication login name your users submit to Duo. This attribute cannot be customized after the first directory synchronization occurs.

      Default: userPrincipalName

      Limitation: The onPremisesSamAccountName and onPremisesDistinguishedName Azure AD attributes aren't allowed as source attributes for the username. If your users log in to Duo-protected applications with those username formats, you can specify them as username alias source attributes to import them into Duo.

      Normalize usernames

      When creating a new user from Azure, Duo defaults to using the entire Azure userPrincipalName (UPN) as the Duo username (e.g. "narroway@example.onmicrsoft.com"). Enable the username normalization option to use only the unique username portion of the UPN as the Duo username ("narroway" in the example).

      If you enable this option after performing your first sync, the next sync updates all managed users to remove the UPN suffix from their usernames.

      Specifying a different source attribute for Username removes the normalization option.

      Note that you still need to specify the user's full UPN Azure username to perform an individual user sync from the Admin Panel. The Duo username remains normalized.

      Username Aliases

      Specify up to four directory attributes to import as additional usernames for each Duo user. For example, if the Username source attribute is userPrincipalName and Username Alias 1 is set to sAMAccountName, then the resulting Duo user may log in with either username format while consuming a single Duo user license.

      Be sure to choose directory attributes that have unique values (email address, employee ID, etc.). If any of the username or username alias attribute values is the same for two or more users, those users will be skipped by the sync process.

      Unlike the Username, the attributes used for username aliases may be changed after the first directory synchronization.

      Default: No aliases imported. Aliases may be defined manually from the Admin Panel or programmatically via [Admin API](/docs/adminapi) on a per-user basis.

      Full Name

      Required. The user's name.

      Default: displayName

      Email

      Required. The user's email address. This is used as the destination address for enrollment emails from Duo.

      Default: mail

      Notes

      Additional information about the users.

      Default: No notes imported. Notes information may be defined manually from the Admin Panel or programmatically via [Admin API](/docs/adminapi) on a per-user basis.

      Import phones

      Enable this option if you want Directory Sync to create phones in Duo using your Azure AD users' Office Phone and Mobile Phone property values. Imported devices default to the "Generic Smartphone" platform.

      If you enable both the Enrollment email and Import phones options, enrollment links are only sent to users with email addresses who do not have phone information populated in Azure AD.

      Default: Import no phone information from Azure AD.

      Primary phone

      Required. Create a phone in Duo with the attribute value as the phone number, attached to the imported user as a generic smartphone 2FA devide. Non-US numbers must be stored in Azure using the format +(country code)(phone number) e.g. +442079460316 for a United Kingdom phone number.

      Only configurable if Import phones is selected.

      Default: businessPhone

      Secondary phone

      Create a phone in Duo with the attribute value as the phone number, attached to the imported user as an additional generic smartphone 2FA device. Non-US numbers must be stored in Azure using the format +(country code)(phone number) e.g. +442079460316 for a United Kingdom phone number.

      Only configurable if Import phones is selected.

      Default: mobilePhone

    When you save the directory settings, Duo validates any non-default source attributes you customized against Azure, and flags any invalid attributes. Correct the Azure source attribute name and save again.

  7. Click in the Groups box and start typing an Azure AD group name; the list of available groups to sync returned will match the filter. If you have a very large number of groups in your Azure directory, Duo limits the search results to 100 groups, so you may need to type in most if your desired sync group's name to locate it.

    If you don't see any of your Azure groups listed, review the previous setup steps and correct your configuration.

    Once you see a list of groups, click to select the desired group or groups to sync, then click Save Groups. You can select up to 400 groups to sync from the source directory. Members of the groups you choose here will be synced into Duo.

    Nested groups are supported; Duo sync imports users from groups nested within your sync group, but creates only the top level group in Duo (the group explicitly selected for directory sync), with all nested group members as direct members of that Duo group.

    If you delete and recreate any of the Azure groups saved in the sync properties (even if you reused the same group name and members), then you'll need to return to the directory sync property page for your Azure domain on the Duo Admin Panel and delete the recreated group from your sync configuration, then re-add the group, and save the directory.

  8. When finished entering these initial fields, click Add Directory to create the new Azure AD directory in Duo and expose additional configuration options.

    Directory Sync

Duo Beyond and Duo Access Plan Users: Global Policy settings affect access to the enrollment portal. Do not apply any global restrictions that could prevent user enrollment. For example, if you configure the User Location policy setting to deny access to a country, then the policy will also block any of your users who attempt to enroll in Duo from that country via a bulk enrollment link. The New User Policy setting for the enrollment portal is always "Require Enrollment".

Perform a Sync

The directory page shows the status as Connected once all directory configuration steps have been completed successfully. You'll also see options to Reauthorize, Sync Full Directory Now, and Sync Single User.

Directory Sync Actions

Click Sync Full Directory Now to run your first sync and immediately import all members of your selected Azure AD groups into Duo.

Directory Sync in Progress

When complete, you'll see a count of users and groups synced into Duo.

Directory Sync Complete

Whether you run your first sync immediately after setup or not, directory sync runs automatically once a day (at a set time chosen at random). You can always return to the Duo Admin Panel to initiate a manual sync.

Note that once you import users from Azure into Duo you may not change the Azure username source attribute, but you can enable or disable username normalization. See the FAQ for more information.

Reduce Privileges for the Service Account

When setup is complete you may edit the Duo service account in Azure that you used to authorize the Duo application to drop the account's role privileges to a role with lesser privileges. Once you've authorized the sync the account no longer requires the Global Administrator role.

Individual User Sync from the Duo Admin Panel

Role required: Owner, Administrator, User Manager, or Help Desk.

When you just need to import information for a few users from Azure AD you can use the individual user sync feature instead of syncing the entire directory. For example, you may have a new employee account in Azure who needs a corresponding Duo account, or you might have just disabled an Azure user and need that status carried over to Duo. Syncing these individual user accounts updates Duo immediately.

Type a single Azure user name into the "Sync single user" text box on the directory's properties page. If you used userPrincipalName as the Duo username source attribute (the default), then you must enter the username in full UPN format, such as "narroway@example.onmicrosoft.com", even if you enabled username normalization in the sync configuration. If you used a different source attribute for the Duo username, you must type the username exactly as it is shown in Duo.

Additionally, the user must be a member of a group specified in the "Choose Groups" section of your directory's configuration. If you try to sync an individual user who is not a member of a selected group then no update occurs. Click the Sync This User button to import information about that specified user.

You can also perform an individual sync on an existing Duo user by visiting that user's properties page in the Duo Admin Panel and clicking the Sync this user link at the top-right. If you enabled the "Normalize usernames" option when configuring the Azure sync in Duo, (so that the usernames don't include the Azure domain information) then user pages won't show the option to sync, and you'll need to visit the directory sync page to perform the individual sync as previously described.

When initiated, the individual user sync verifies that the user is a member of a group currently synced with Duo and then imports information for that user into Duo. If the user doesn't already exist in Duo, the sync creates them using the information imported from the source directory. If you enabled the option to send enrollment emails when adding the directory and the new user has the email address attribute populated, then a new user created by the individual user sync receives an emailed enrollment link.

Individual user sync updates an existing user with information from the source directory. The sync can change attribute values (except the username), modify group memberships, or disable the user in Duo if they are disabled in the source directory.

If you run an individual user sync against a user that is no longer a member of any group synced into Duo, then the sync marks the user for deletion.

Individual User Sync using Admin API

Use the AdminAPI directory key from the "Directory Settings" section of the page to perform a sync operation on an individual user using Duo's Admin API.

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.

Activation Links

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

If you did choose to send enrollment emails to users synced users automatically, the Pending Enrollments table shows which users created by directory sync or bulk enrollment have not yet completed enrolling their 2FA devices in Duo, along with each user's email address and the expiration date for the enrollment link previously sent. If you need to send the user another copy of the enrollment link email, click the Resend button. Resending the email does not change the current enrollment link's expiration date.

Pending Enrollments

Managing Synced Users

Updating Synced User Information

User attributes synced 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, full 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 synced from Azure AD, including those that correspond with optional Azure AD sync attributes you chose not to import. However, if you update your Azure AD sync to begin importing values for a previously unconfigured optional attribute, the sync will overwrite any previously configured values with the information imported from Azure.

Examples:

  • You do not specify a source attribute for Notes when you created your Azure AD directory sync. The sync imports the username, email, and name from Azure, but imports no notes information. You can edit the "Notes" field for synced Duo users. but you may not edit the "Username", "Full Name", or "Email" properties for synced users.

  • You specify a source attribute for Username alias 1 but not for aliases 2-4. The sync imports values for "Username Alias 1" from Azure, and no other aliases. You can't edit "Username Alias 1", but you can edit the values for aliases 2-4.

  • 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 Azure AD sync to add a source attribute for Username alias 1. The next sync updates the "Username Alias 1" value for all users to match the value in Azure, overwriting the aliases you added manually.

Bypass Status for Synced Users

Users synced 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

Admins can't disable individual Duo users managed by directory sync from the Duo Admin Panel, Admin API, or CSV import. Directory sync checks the user account status in the source directory and uses that information to determine whether the corresponding Duo account should remain enabled.

If a synced user account is disabled in the source directory, the user will be disabled in Duo automatically when the next full or single directory sync occurs. The disabled Duo user is still tagged as a directory user, is read-only, and cannot be manually enabled.

You can restore the disabled Duo account to active status by enabling the account in the source directory and running a sync.

You may disable a group of synced 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.

Deleting Synced Users

You may not delete a synced user from Duo as long as directory sync 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's status changes to "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.

Users in Trash Pending Deletion

If the user marked for deletion is not reconnected to an external directory account via the sync 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.

User in Trash

Reauthorizing the Sync

If the Duo Sync application's authorization in Azure expires then scheduled syncs stop running. We'll email the all the Duo administrators with the "Owner" role to let them know.

When you visit your Azure directory sync configuration page in the Duo Admin Panel, the Status information shows you the state of your directory connection.

If the status says "Could not connect to Azure: Reauthorization required", then click the Reauthorize button to repeat the authorization step you performed when you originally configured the sync. If the Azure account you'll use to reauthorize the sync had its privileges reduced after the first authorization, temporarily apply the Global Administrator role again before clicking Reauthorize.

Update to the New Sync

We've updated Azure AD sync with new features like customizable source attributes and improved performance. We encourage all existing Azure AD sync customers to update to the new sync now.

To update to the enhanced sync:

Role required: Owner, Administrator, or User Manager.

  1. Log into the Duo Admin Panel. Click UsersDirectory Sync to see your configured directories.

  2. Click the name of the Azure AD sync you want to update.

  3. Check the Use new sync option at the top of your Azure AD directory sync configuration page. When checked, the new Sync attributes configuration section appears, and the Normalize usernames and Import phones options relocate into the new section.

    The sync source attributes in the Sync attributes section reflect the default values Duo used before you enabled the new sync. Your previous selections for the Normalize usernames and Import phones are retained.

    You may modify the sync attributes at this time if you wish. No change is made to the directory until you save the configuration.

  4. Click Save Directory to complete updating to the new Azure AD sync.

  5. Reauthorize the sync's access to your Azure directory. Click the Reauthorize button to repeat the authorization step you performed when you originally configured the sync. If the Azure account you'll use to reauthorize the sync had its privileges reduced after the first authorization, temporarily apply the Global Administrator role again before clicking Reauthorize.

    If you skip the reauthorization step now your sync might stop working in the future. You can always repeat the authorization step if/when needed.

If you have multiple Azure AD directory syncs you'll need to update each one individually to the new sync.

Legacy AD Sync Options

Customers who do not update to the new Azure AD sync see these directory configuration options:

Enrollment email

Select this option if you want imported users to automatically receive an enrollment link email when the sync process completes. 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 by Azure AD sync from an on-premises Active Directory, or by an Office 365 tenant used with your Azure directory. Default: do not send enrollment emails to imported users.

The enrollment link sent when the sync first imports a user 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 at the next sync 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.

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

Import phones

Enable this option if you want Directory Sync to create phones in Duo using your Azure AD users' Office Phone and Mobile Phone property values. Imported devices default to the Generic Smartphone platform. Default: import no phone information from Azure AD.

International phone numbers stored in Azure must be prefixed with + and the country code, e.g. +4401617150105 for a UK number.

If you enable both the "Enrollment email" and "Import phones" options, enrollment links are only sent to users with email addresses who do not have phone information populated in Azure AD.

Normalize usernames

When creating a new user from Azure Duo defaults to using the entire Azure user principal name (UPN) as the Duo username (e.g. "narroway@example.onmicrsoft.com"). Enable the username normalization option to use only the unique username portion of the UPN as the Duo username ("narroway" in the example).

If you enable this option after performing your first sync, the next sync updates all managed users to remove the UPN suffix from their usernames.

Note that you still need to specify the user's full UPN Azure username to perform an individual user sync from the Admin Panel. The Duo username remains normalized.

Legacy Azure AD sync does not support importing custom attributes or username aliases. To customize the attribute information imported from Azure AD, first enable the Use new sync option to upgrade from legacy sync.

Frequently Asked Questions

Be sure to review frequently asked questions and answers before using Duo's Active Directory synchronization.

Troubleshooting

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

The new Azure Sync adds a Troubleshooting section under the “Sync Full Directory Now” button. Here you'll find tips to help your sync run as intended. If you are still having issues, you can click Sync Full Directory with Diagnostics to provide Duo Support with more information about your sync.

Additionally, sync reference code is now provided on every sync. This will be included on every Azure sync event captured in the Administrator Actions Log, as well as within any emails Duo sends you about sync errors. Duo Support will request this code to locate logs associated with your sync.

Network Diagram

Azure Sync Network Diagram

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