Be sure to review these frequently asked questions and answers before using Duo's Azure, Active Directory, or OpenLDAP synchronization.
Duo's directory sync runs automatically twice a day, at 12 hour intervals chosen at random when you create your sync.
Scheduled synchronization ran once every 24 hours prior to March 10, 2022. Duo began updating existing directory syncs to the new twice-daily schedule starting on March 10, with all customer sync schedules updated by March 17.
You can run a full sync at any time by visiting your directory sync's properties page in the Duo Admin Panel and clicking the Sync Now button.
Sync an individual user from the same directory sync by entering their username value from the source directory in the Sync Individual Users field on the directory sync's properties page and then clicking Sync User.
No, Duo's service does not need to contact your directory servers. When you configure Active Directory or OpenLDAP sync, the Duo Authentication proxy server you configure contacts your directory server to search for information about users and groups, and also makes an outbound connection to Duo's service to send the user and group information to perform the sync.
Yes, you can use a Linux server to sync Active Directory domains when you specify NTLMv1, NTLMv2, or Plain authentication when setting up directory sync. See the AD Sync instructions for more information.
Yes. You must have Authentication Proxy v5.2.0 or later installed. To run multiple syncs through a single proxy server, all the syncs must be configured for a single Duo customer account, i.e. the
api_host value for all the directory syncs is identical.
Here is an
authproxy.cfg example for multiple directory syncs using Integrated (SSPI) authentication. Note that the integration key (
ikey) differs but the API host is the same in both
[cloud] sections; this reflects the requirement that the multiple syncs must be for a single Duo customer account:
[cloud] ikey=DIABCDEFGHIJKLMNOPQR skey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX api_host=api-12345678.duosecurity.com [cloud2] ikey=DISTUVWXYZABCDEFGHIJ skey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX api_host=api-12345678.duosecurity.com
Authentication Proxy versions up to v5.1.1 can only run a single directory sync. Adding more than one
[cloud] section to
authproxy.cfg prevents the proxy service from starting due to this being an invalid configuration.
Yes, Duo supports importing users and groups from Active Directory Lightweight Directory Services (AD LDS) via Active Directory sync. Imported groups must be local to AD LDS, but the users may be either local to AD LDS or proxied from an underlying AD domain (with
The following table lists the default Active Directory attributes synchronized to Duo, along with their corresponding Duo attribute mappings:
|AD Attribute||Duo Attribute|
|displayName||User full name|
|User email address|
|telephoneNumber*||Phone (type Mobile, platform Generic Smartphone)|
|mobile*||Phone (type Mobile, platform Generic Smartphone)|
*Not synced unless the "Import phones" option is checked.
** Not synced unless the "Import notes" option is checked.
The Active Directory user attributes synchronized to Duo can be changed using custom attribute mapping.
Username aliases aren't imported unless you specify a source attribute; there are no default alias attributes. Username alias attribute values must be unique throughout the synced directory. If the sync process encounters an alias value that's already attached to another Duo user, then it skips updating properties of the user with the duplicated alias value (but will update that user's group memberships).
Imported values may not be changed from the Duo Admin Panel. To update any of the imported values, change the source attribute value in your directory and perform a sync. See How are synced users affected if I change the values of certain user attributes in Active Directory? for more information about updating synced attributes. You can edit user properties that aren't imported from the source directory, but if you add those attributes to the sync later, the information you added manually gets overwritten with information imported by AD sync.
There are no default source attributes for OpenLDAP sync. You must specify which directory attribute to use for each Duo user and associated phone property.
The following table lists the Duo properties that may be imported from OpenLDAP attributes:
| Duo Attribute | | ----- | ----- | | Group name | | Username | | User full name | | User email address | | Phone 1* (type Mobile, platform Generic Smartphone) | | Phone 2* (type Mobile, platform Generic Smartphone) | | Notes** |
*Not synced unless the "Import phones" option is checked and source attribute specified.
** Not synced unless the "Import notes" option is checked and source attribute specified.
Username aliases aren't imported unless you specify a source attribute. Username alias attribute values must be unique throughout the synced directory. If the sync process encounters an alias value that's already attached to another Duo user, then it skips updating properties of the user with the duplicated alias value (but will update that user's group memberships).
Imported values may not be changed from the Duo Admin Panel. To update any of the imported values, change the source attribute value in your directory and perform a sync. See How are synced users affected if I change the values of certain user attributes in Active Directory? for more information about updating synced attributes. You can edit user properties that aren't imported from the source directory, but if you add those attributes to the sync later, the information you added manually gets overwritten with information imported by OpenLDAP sync.
The following table lists the default Azure Active Directory attributes synchronized to Duo, along with their corresponding Duo attribute mappings:
|Azure Attribute||Duo Attribute|
|displayName||User full name|
|User email address|
|businessPhone**||Phone (type Mobile, platform Generic Smartphone)|
|mobilePhone**||Phone (type Mobile, platform Generic Smartphone)|
* Duo username created as the full userPrincipalName ("firstname.lastname@example.org") or as the unique username without domain information ("narroway") depending on whether "Normalize usernames" is checked.
** Not synced unless the "Import phones" option is checked.
The Azure AD attributes synchronized to Duo can be changed in the directory's synced attributes configuration.
Username aliases and notes aren't imported unless you specify a source attribute; there are no default alias attributes. Username alias attribute values must be unique throughout the synced directory. If the sync process encounters an alias value that's already attached to another Duo user, then it skips updating properties of the user with the duplicated alias value (but will update that user's group memberships)
Imported values may not be changed from the Duo Admin Panel. To update any of the imported values, change the source attribute value in your directory and perform a sync. See How are synced users affected if I change the values of certain user attributes in Azure? for more information about updating synced attributes. You can edit user properties that aren't imported from the source directory, but if you add those attributes to the sync later, the information you added manually gets overwritten with information imported by Azure sync.
Yes, when creating a new Azure AD directory sync you can once you modify the synced attributes. Note that you cannot modify the Duo username source attribute after the first Azure sync runs, but you can specify up to four source attributes for username aliases.
The Duo user cannot be deleted manually from the Admin Panel, with the Admin API, or via CSV import. User attributes imported from the source directory become read-only and can only be updated in the source directory.
Active Directory, OpenLDAP, and Azure AD directory synchronization overwrites information for any required or specified optional attribute, such as full name, email address, and username aliases, for any Duo user with a matching username in the external directory. The sync doesn't modify or remove information for attributes that aren't configured in the sync. Additionally, you can edit the values for optional custom attributes not configured in your sync (like aliases and notes), manually from the Admin Panel, programmatically via Admin API, or by CSV import.
Any phones or tokens that were attached to the Duo user before the directory sync remain intact. Phone numbers imported from the source directory are attached to the user as additional phones.
The user's Duo group memberships are updated to match the user's group memberships in the source directory. Groups managed by directory sync are identified as such when viewed (the group's description notes the type and name of the sync managing the group i.e. from Azure Sync "Acme AAD"). The user cannot be manually added to any groups from the Duo Admin Panel, with Admin API, or via CSV import.
Policy settings and permitted groups access based on the user's previous Duo group memberships no longer apply if the sync removes a user from the policy's target groups. Apply the Duo policies and permitted groups config to the groups managed by directory sync to maintain the configuration previously applied to the users before the sync.
Yes, 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, each sync will overwrite details for that user with the information from that sync's source directory. Duo will not merge information from multiple source directories into a single user's details.
If you were to configure both an AD and an Azure sync to import a group with the same name — for example, "Duo Users" — then each sync will create a "Duo Users" group in Duo, identified in the group's description by which sync manages it. Each sync populates the group it manages with the members from that source directory, so the "Duo Users" group managed by Azure sync would contain only members synced from that Azure directory, and the "Duo Users" group managed by AD sync would only contain members synced from that AD directory. There is no support for merging of users from different source directories into a single Duo group.
If you create more than one directory sync with the same source directory, and configure them to sync the same group from that directory, then when each sync runs it will "take over" management of that group and remove it from the other sync config. We do not recommend this.
User import via AD sync can fail for a few possible reasons, even when the directory status is "Connected":
The base DN used to configure Active Directory sync does not include any user accounts. The base DN specified should be at a level above all the organizational units or containers that hold users and groups you want to synchronize with Duo. You may find it easiest to set this to the top level of your domain.
If syncing groups via the global catalog that reside in a child domain of a multi-domain forest, set the child AD group scope to Universal.
The Domain Users group (or any group that is set as the primary group for one or more users) cannot be used by directory sync to import users. Please create another domain group that is not any user's primary group to use with the sync.
The machine account of the Authentication Proxy server lacks sufficient privileges to query Active Directory and retrieve user attributes. Try changing the “Log on as:” setting of the “Duo Security Authentication Proxy Service” to use a domain service account. You can do this from the Services management console (services.msc).
The account you use typically does not require Domain Admin privileges, but it does need at least the “Log on as a service” right on the Authentication Proxy server and read access to Active Directory.
IMPORTANT: When you upgrade the Duo Security Authentication Proxy software to a newer version the service will revert to running as "Local System." Repeat the process above to change the service back to using a named domain service account.
User import via OpenLDAP sync can fail for a few possible reasons, even when the directory status is "Connected":
The base DN used to configure OpenLDAP sync does not include any user accounts. The base DN specified should be at a level above all the organizational units or containers that hold users and groups you want to synchronize with Duo. You may find it easiest to set this to the top level of your domain.
The service_account_username specified for NTLMv1, NTLMv2, or Plain authentication does not have sufficient privileges to bind to OpenLDAP and lookup user and group information.
Changing synced attribute values in Azure Active Directory (AAD) has the following effects on imported users:
You may run into issues if you try to swap usernames between two Azure users at the same time, such as changing "email@example.com" to "firstname.lastname@example.org" while also changing the original "bob" Azure AD account to "joe". We recommend changing the source Azure usernames to something new and unique to avoid a renaming conflict in Duo.
Changing synced attribute values in Active Directory (AD) has the following effects on imported users:
Changing synced attribute values in OpenLDAP has the following effects on imported users:
User information synced from an external Azure Active Directory, on-premises Active Directory, or OpenLDAP directory cannot be edited in Duo. This includes username, username aliases (if you imported aliases), full name, email address, phone numbers (if you imported phones), notes (if you imported notes), and group memberships. Changes to these user attributes should be made in the source directory and then synced over to Duo.
Directory sync permits editing values for optional custom attributes not configured in your sync (
notes). If you do configure those attributes in your sync later, then imported values overwrite those you added manually. See Updating Synced User Information (Azure), Updating Synced User Information (AD), or Updating Synced User Information (OpenLDAP) for detailed examples.
You can attach hardware tokens and additional phones to synchronized users. These are retained after the next directory sync.
To change the name of a group managed by directory sync you must rename the group in the source directory. The group's name will update in Duo when the next scheduled sync runs, or when a Duo admin visits that directory's page in the Duo Admin Panel (whichever happens first).
No, the username attribute can only be modified before the first directory synchronization. After the directory has been synced, the username field will be disabled. The only way to change the Duo username source attribute is to create a new directory using the desired username attribute. This may affect your licensed user count and impact or prevent user authentications. Please contact Duo Support for more information and guidance.
Yes, you may change the source attribute for username aliases one through four at any time. New values imported at the next sync overwrite the previous alias values. Be sure to select source attributes for aliases that have unique values in your directory.
Yes, if you imported the
userPrincipalName from Azure as the Duo username then you can enable or disable the "Normalize usernames" option after performing the initial sync. Duo usernames will be updated by adding or removing the domain suffix accordingly.
Yes, you can change the device name, type, and platform, and activate a smartphone for Duo Mobile. However, you cannot change the phone number or extension while the phone is managed by Directory Sync.
If you disable the sync phones option in the directory sync's configuration, then Duo directory sync no longer adds or updates phones with information from the source directory. The previously synced phones become unmanaged by sync, and you may change the phone number or extension, or delete the phone from Duo.
No, group attributes cannot be edited in Duo once the group is synced. Duo imports the group name as well as the members of each group from the external directory. Duo users cannot be removed from a synced group, and non-synced Duo users cannot be added to a synced group via any means but directory sync. When viewing group information, you'll see from AD Sync "name of sync" appended to the group's name or as the group's description.
To change the name of a synced group, change the name in the source directory. Duo will update the group's name to the new value the next time a sync is run, or when an admin views the directory's details page in the Duo Admin Panel (whichever happens first).
You can set the status of a synced group to Active, Bypass, or Disabled, which changes the status for all members of that group. You can also select which authentication methods are available to members of that group.
For more information on using groups to control status and authentication methods, see Group Settings.
If a synced directory user is removed from all external directory groups that sync to Duo (or if the AD/OpenLDAP or Azure user account is deleted in the source directory), the next full directory sync or individual sync of that user moves the user to the Trash and marks the account as "Pending Deletion". At this point, the user can no longer authenticate to Duo. The user's properties are read-only and you are no longer billed for that user.
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.
You can permanently delete a formerly synced user from the Trash at any time during the seven day waiting period by clicking into the Trash view from the Users page in the Duo Admin Panel and using the Permanently Delete action. See Permanently Deleting Users for detailed instructions.
If a synced directory user account is disabled in Azure or Active Directory, the user will be disabled in Duo automatically when the next directory sync occurs. The disabled Duo user is still tagged as a directory user, is read-only, and cannot be manually enabled.
When a user is synced from an external directory to Duo, new phones will be created using the mobile and telephone numbers present for each user if a phone with that number does not already exist in Duo. These devices cannot be deleted from the Duo interface and their phone numbers can't be changed, but the device name, type, and platform can be modified by Duo administrators.
A synced phone can be attached to another Duo user (thereby having the phone attached to multiple users simultaneously). You can also remove synced phones from AD synchronized users, but if the phone number is still present in the user's external directory properties the phone will be reattached after the next sync.
The Active Directory attribute
telephoneNumber and the Azure AD attribute
phone maps to Duo attribute
phone1 and sets the Duo attributes type and platform to
Unknown. The Active Directory attribute mobile maps to Duo attribute
telephoneNumber is blank, in which case
mobile maps to Duo attribute
phone1. If a user already exists in Duo with an attached phone before the sync and that same phone does not exist in the source directory, that pre-existing phone will be
phone1 in Duo and additional phones created by the sync will start at
New phone devices, whether the number is in the
mobile source directory field, are created in Duo with type set to
Mobile and platform set to
International phone numbers stored in the source directory must be prefixed with + and the country code, e.g. +4401617150105 for a UK number.
If a phone number imported by the external directory synchronization already exists in Duo, the external directory information is merged in with the existing Duo phone number information. The Duo device name, type, and platform are retained, and the corresponding user is attached to the phone if that is not already the case. If the existing phone was attached to a different user before the directory sync, that attachment is retained after the sync as well.
If a phone number is deleted from a directory user and is not attached to any other Duo users when it is removed, the phone is deleted from Duo at the next sync. If the phone is attached to more than one user in Duo then the phone will still exist and remain attached to the users from whom the phone was not removed. You can manually delete that phone from the Admin Panel.
Hardware tokens can be added to a synchronized Duo user, and the information for these tokens won't be overwritten by the sync process.
A Duo user has one of four possible statuses: Active, Bypass, Disabled, and Locked Out. A user's status can be changed in Duo interactively from the Admin Panel, programmatically via Admin API, or by CSV import if the corresponding external directory user is enabled in Azure or Active Directory with these additional considerations:
Duo status settings are not imported or updated by a sync from an OpenLDAP directory, so "Active", "Bypass", or "Disabled" status may be set in Duo as needed.
If a directory group is deleted from the external directory or removed from the directory configuration in Duo, the Duo users from that group will be marked for deletion if they are not members of another synchronized group. Any phones imported for those users by the sync will also be removed unless they are attached to a remaining user.
Groups that were previously synced from the external directory will still exist in Duo. However, they will be changed to regular groups, whose attributes can all be modified and who can also be 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 type of sync "name of sync" to Group name (formerly from "name of sync").
If you delete the entire Azure or AD directory from Duo, then the previously synced users, phones, and groups get converted to regular Duo objects and can be manually updated. Deleting the directory doesn't delete any of the previously imported objects.
Duo emails admins with privileges to manage directory sync in the event of consecutive failures, pausing the sync, or other issues.
Some reasons an Active Directory and LDAP directory scheduled sync might fail and trigger a notification email include:
An Azure Active Directory sync might fail and trigger a notification email when the Duo Sync application needs reauthorization in Azure.
Note that a failure to run the scheduled synchronization process is not the same as if the sync completes with success indicators but does not sync your expected users, groups, or attributes. In these situations, double-check your group and synced attribute selections, and the rest of your directory sync configuration to ensure your settings match your expected results.