Skip navigation

Effective October 28, 2019 Duo Security will be transitioning to Cisco's Privacy Statement. View the Duo Privacy Data Sheet.

Documentation

Directory Sync - Troubleshooting and FAQ

Last Updated: March 12th, 2019

Be sure to review these frequently asked questions and answers before using Duo's Azure, Active Directory, or OpenLDAP synchronization.

Can I use a Linux Duo Authentication Proxy for Active Directory 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.

What Active Directory attributes are synchronized to Duo?

The following table lists the default Active Directory attributes synchronized to Duo, along with their corresponding Duo attribute mappings:

AD Attribute Duo Attribute
CN Group name
sAMAccountName Username
displayName User real name
mail User email address
telephoneNumber* Phone (type Mobile, platform Generic Smartphone)
mobile* Phone (type Mobile, platform Generic Smartphone)
info** Notes

*Not synced unless the "Import phones" option is checked.

** Not synced unless the "Import notes" option is checked.

The Active Directory 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 syncing the user with the duplicated alias value.

​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.

What OpenLDAP attributes are synchronized to Duo?

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 real 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 syncing the user with the duplicated alias value.

​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.

What Azure directory attributes are synchronized to Duo?

The following table lists the Azure Active Directory attributes synchronized to Duo, along with their corresponding Duo attribute mappings:

Azure Attribute Duo Attribute
CN Group name
userPrincipalName Username*
displayName User real name
mail User email address
phone** Phone (type Mobile, platform Generic Smartphone)
mobile** Phone (type Mobile, platform Generic Smartphone)

* Duo username created as the full userPrincipalName ("narroway@example.onmicrosoft.com") 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.

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.

Can you customize the Azure attributes imported into Duo?

No, Azure attributes may not be customized to use a different source attribute. Only Active Directory sync allows attribute customization.

What happens when existing Duo users are synced with Azure, Active Directory, or OpenLDAP?

The Duo user cannot be deleted manually from the Admin Panel or with the Admin API. User attributes imported from the source directory become read-only and can only be updated in the source directory.

Directory synchronization overwrites real name, email address, and username aliases for any Duo user with a matching username in the external directory. The sync removes existing aliases if no source attributes for aliases were configured in the sync.

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. Therefore, the user is removed from any Duo groups not managed by the directory sync, and the user cannot be manually added to any groups from the Duo Admin Panel or with Admin API.

Policy settings based on the user's previous Duo group memberships no longer apply if the sync removes the user from the policy's target groups. Apply the Duo policies to the groups managed by directory sync to maintain the configuration previously applied to the users before the sync.

Can I sync multiple directories into Duo?

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 and groups you select for import have unique names.

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 update the group members to match the members in the source directory, removing any user who is not a member of the grou in that particular source directory. There is no merging of users from different source directories into the same Duo group.

Similarly, 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.

Why are no Active Directory users imported when Directory Sync runs?

User import via AD sync can fail for a few possible reasons:

  • 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).

    1. View the properties of the “Duo Security Authentication Proxy Service” service and go to the Log on tab.
    2. Click on This Account and enter an AD service account username and password.
    3. Click OK.
    4. Cycle the Duo Security Authentication Proxy service for the new rights to take effect.

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.

Why are no OpenLDAP users imported when Directory Sync runs?

User import via OpenLDAP sync can fail for a few possible reasons:

  • 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.

  • If using Integrated (SSPI) authentication, the machine account of the Authentication Proxy server lacks sufficient privileges to bind to OpenLDAP and retrieve user attributes.

  • 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.

How are synced users affected if I change the values of certain user attributes in Azure?

Changing synced attribute values in Azure Active Directory (AAD) has the following effects on imported users:

  • If you change a user's e-mail address, display name, or telephone numbers, those new values are imported to the Duo user at the next sync.
  • If the Azure UPN username value imported into Duo changes, the Duo username is updated accordingly (as determined by the "Normalize usernames" option).

You may run into issues if you try to swap usernames between two Azure users at the same time, such as changing "joe@example.onmicrosoft.com" to "bob@example.microsoft.com" 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.

How are synced users affected if I change the values of certain user attributes in Active Directory?

Changing synced attribute values in Active Directory (AD) has the following effects on imported users:

  • If you change a user's e-mail address, display name, telephone number, or notes, those new values are imported to the Duo user at the next sync.
  • If the AD username value imported into Duo changes (default is sAMAccountName), then a new Duo user is created with that username and the existing Duo user with the previous AD username is marked for deletion. 
  • Devices do not automatically transfer from the old Duo username to the new one, so phones and tokens will need to be transferred or re-enrolled.

How are synced users affected if I change the values of certain user attributes in OpenLDAP?

Changing synced attribute values in OpenLDAP has the following effects on imported users:

  • If you change the value of the attributes you specified for a user's e-mail address, display name, telephone number, or notes, those new values are imported to the Duo user at the next sync.
  • If the OpenLDAP username value imported into Duo changes, then a new Duo user is created with that username and the existing Duo user with the previous OpenLDAP username is marked for deletion. 
  • Devices do not automatically transfer from the old Duo username to the new one, so phones and tokens will need to be transferred or re-enrolled.

Can I edit attributes for synced users from Duo?

No, user attributes synced from an external directory cannot be edited in Duo. This includes username, real name, email address, phone numbers, notes, and group memberships. Changes to these user attributes should be made in the source directory and then synced over to Duo.

You can attach hardware tokens and additional phones to synchronized users. These are retained after the next directory sync.

Can I change the username attribute synced from Active Directory or OpenLDAP after the initial sync?

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 AD or OpenLDAP 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.

Can I change the username alias attribute(s) synced from Active Directory or OpenLDAP after the initial sync?

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.

Can I change the format of the username synced from Azure after the initial sync?

Yes, 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.

Can I edit attributes for synced phones?

Yes, you can change the device name, type and platform. However, you cannot change the phone number or extension while the phone is managed by Directory Sync.

If the sync phones option is disabled in the Directory Settings then Directory Sync will no longer add or update phones from Active Directory and you may change the phone number and extension. If a synced phone is edited this way then it will no longer be considered an sync-managed phone and can be edited and deleted like any other phone.

Can I edit attributes for synced groups?

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 from within the Duo Admin Panel. The group's description is not imported from the directory, but it becomes a read-only field.

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.

What happens if a synced user is removed from synced groups?

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 account to the "Trash" view and changes the user's status to "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.

What happens if a synced user account is disabled in Azure or Active Directory?

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.

How are new phone devices created by the Directory Sync?

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 phone2, unless 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 phone2.

New phone devices, whether the number is in the telephoneNumber or mobile source directory field, are created in Duo with type set to Mobile and platform set to Generic Smartphone.

Why might international phone numbers not get imported into Duo?

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

What happens when existing Duo phone numbers are synced with a directory?

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.

What happens if a phone number is deleted from a directory?

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.

How does directory synchronization affect Duo users' hardware tokens?

Hardware tokens can be added to a synchronized Duo user, and the information for these tokens won't be overwritten by the sync process.

How are directory user statuses related to Duo user statuses?

A Duo user has one of four possible statuses: Active, Bypass, Disabled, and Locked Out. The user's status can be changed in Duo if the corresponding external directory user is enabled in Azure or Active Directory. Additional considerations include the following:

  • If an administrator changes a status to "Bypass", that status will not be overwritten by the sync as long as the user account stays enabled in the external directory.
  • If an external directory user account is disabled in Azure or AD but the user is still a member of a group synced to Duo, then the Duo user status is automatically set to "Disabled" and it cannot be changed in the Duo Admin Panel. The external directory's disabled status for an individual user also overrides any status assigned to a synced group in Duo.
  • If an external directory user account is removed from all Duo-synchronized groups or is deleted from the directory, then the corresponding Duo user is moved to the "Trash" view and automatically marked for deletion with "Pending Deletion" shown instead of one of the four user status values described above.
  • If a Duo user is in "Locked Out" status in Duo due to excessive failed login attempts, the Duo administrator can unlock the user. Account lockout in the external directory has no effect on Duo user status.

When a synced Duo user is marked for deletion, the user's status is shown as "Pending Deletion" in Duo's Users view. This is not a selectable status and can only be cleared by reconnecting the Duo user to a synced directory account (by adding the corresponding Azure, AD, or LDAP account to the group used for synchronization). Viewing the properties of that user shows the last effective status prior to being marked for deletion (e.g. "Active", etc.).

Duo status settings are not imported or updated by a sync from an OpenLDAP directory.

How does deleting the synchronized group from Duo Directory Sync affect synchronized Duo users, groups, and devices?

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.

How does directory deletion affect synchronized Duo users?

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.

Additional Troubleshooting

Need more help? Try searching our directory sync Knowledge Base articles or Community discussions. For further assistance, contact Support.