Active Directory Sync for Duo Users and Admins

Overview

Import Duo end-users or administrators directly from your on-premises Active Directory (AD) forest or domain or Active Directory Lightweight Directory Service (AD LDS) instance into Duo with Duo Security's Directory Sync feature.

Duo Directory Sync is a one-way operation. No information from Duo is imported into your user directory.

Scheduled user synchronization of your full directory runs twice a day, and runs every 30 minutes for administrators. Run either type of full sync on-demand from the Duo Admin Panel. You can also run an individual user or administrator syncs on-demand from the Admin Panel or programmatically via Admin API.

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

Prerequisites

Prerequisites necessary for Active Directory synchronization are as follows:

• Know your Active Directory domain controller hostname or IP address, the LDAP or LDAPS port for communicating with that server, the authentication type you plan to use, and the directory search base DN.
• If you plan to secure communications between the Duo on-premises proxy and your directory server, have the LDAPS or STARTTLS information and the issuing CA certificate or CA certificate chain for the certificate used by your domain controller. Starting with Authentication Proxy version 6.0.0, the certificate issued to the domain controller(s) must use SHA256 or greater.
• A Windows 2016 or later, or modern Linux system (CentOS, Ubuntu, Red Hat), for running the Duo Authentication Proxy software.
• Duo Authentication Proxy installed on the target server. You will complete this installation as part of the setup steps described below.
• You must have the Owner, Administrator, or User Manager admin role to set up and manage directory sync of users into Duo. Duo Admin directory sync setup and management requires the Owner admin role.

Set Up User Sync

Role required: Owner, Administrator, or User Manager.

Please note that this video shows user sync configuration prior to the October 2022 D252 Duo release. Some concepts still apply.

Create or Choose a Connection for User Sync

To start setting up a user directory sync:

1. Log in to the Duo Admin Panel.

2. Locate Users in the left side bar and then click Directory Sync on the submenu or click the Directory Sync link on the "Users" page.

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

4. If this is the first Active Directory sync you've created for users or admins then you must first create a new connection to use for this sync. With Add new connection selected, click Continue to proceed to the next step.

   

   If you have previously created an Active Directory sync for users or administrators you can either create another new connection or reuse an existing connection to that directory for this new sync. User syncs and admin syncs can share connections to the same source directory.

   If you want to use an existing connection choose Reuse existing connection and use the drop-down to select one from the list, then click Continue.

   

   You'll proceed directly to the new sync's properties page, where you'll select groups to sync and configure the synced attributes.

Install Duo Authentication Proxy

If you chose to create a new connection then your next step is to install the Duo Authentication Proxy software on a machine that can connect to both Duo's cloud service and to your AD domain controller. Before proceeding, you should locate (or set up) a system in your environment on which you will install the Duo Authentication Proxy. This host needs LDAP connectivity to your AD domain controller (ports 389/636 or whichever ports accept Active Directory binds), as well as HTTPS/443 connectivity to Duo.

If you are already running an Authentication Proxy server in your environment, you can also use that host for directory synchronization. If your existing Authentication Proxy server is version 5.2.0 or later, and it's already running a directory sync, you can use the same proxy connection to run additional syncs as long as they are all for the same Duo customer account (identical api_host values).

Locate (or set up) a system on which you will install the Duo Authentication Proxy. We recommend the following 64-bit operating systems for the system hosting the Duo Authentication Proxy:

• Windows Server 2016 or later
• CentOS 7
• CentOS Stream 8 or later
• Fedora 37 or later
• Red Hat Enterprise Linux 7 or later
• Ubuntu 20.04 LTS or later
• Debian 11 or later

If you opt for Integrated authentication, the Authentication Proxy server must be a domain-joined Windows 2016 or later server.

The Duo End of Sale, Last Date of Support, and End of Life Policy states that Duo does not offer support for integrations running on operating system versions beyond the vendor’s stated Last Date of Support date.

If you will reuse an existing Duo Authentication Proxy server for this new application, you can skip the install steps and go to Configure the Proxy.

The Duo Authentication Proxy can be installed on a physical or virtual host. We recommend a system with at least 1 CPU, 200 MB disk space, and 4 GB RAM (although 1 GB RAM is usually sufficient). See additional Authentication Proxy performance recommendations in the Duo Authentication Proxy Reference.

We do not recommend installing the Duo Authentication Proxy on the same Windows server that acts as your Active Directory domain controller or one with the Network Policy Server (NPS) role. If you must co-locate the Duo Authentication Proxy with these services, be prepared to resolve potential LDAP or RADIUS port conflicts between the Duo service and your pre-existing services.

duoauthproxy-version.exe /S

duoauthproxy-version.exe /S /exclude-auth-proxy-manager

sudo ./duoauthproxy-build/install --install-dir /opt/duoauthproxy --service-user duo_authproxy_svc --log-group duo_authproxy_grp --create-init-script yes

Configure the Proxy

After the installation completes, you will need to configure the proxy with your connection information. Note that as of v4.0.0, the default file access for the conf directory is restricted to the built-in "Administrators" group during installation on Windows systems.

The Duo Authentication Proxy configuration file is named authproxy.cfg, and located in the conf subdirectory of the proxy installation.

Download the Authentication Proxy authproxy.cfg file for your AD domain sync by clicking the download a pre-configured file link in step 2 of the Duo Authentication Proxy section of the directory properties page. This file contains the values needed to set up the connection. You could also copy the values directly from the Admin Panel to paste into your server's config file.

The configuration file is formatted as a simple INI file. Section headings appear as:

[section]

Individual properties beneath a section appear as:

name=value

A first time Authentication Proxy install may include an existing authproxy.cfg with some example content. If this is the first time you're configuring this Authentication Proxy server, you should delete the existing sample content.

Duo Authentication Proxy Manager

The Duo Authentication Proxy Manager is a Windows utility for managing the Authentication Proxy installation on the Windows server where you install the Authentication Proxy. The Proxy Manager comes with Duo Authentication Proxy for Windows version 5.6.0 and later.

The Proxy Manager cannot manage remote Duo Authentication Proxy servers, nor can you install the Proxy Manager as a stand-alone application. There is no Proxy Manager available for Linux. The Proxy Manager only functions as part of a local Duo Authentication Proxy installation on Windows servers.

Learn more about using the Proxy Manager in the Duo Authentication Proxy Reference.

To launch the Proxy Manager utility:

• Open the Start Menu and go to Duo Security.
• Click the Duo Authentication Proxy Manager icon to launch the application. You must have administrative privileges on the Windows server and accept the prompt for elevation.
• The Proxy Manager launches and automatically opens the %ProgramFiles%\Duo Security Authentication Proxy\conf\authproxy.cfg file for editing.

Use the Proxy Manager editor on the left to make the authproxy.cfg changes in these instructions. As you type into the editor, the Proxy Manager will automatically suggest configuration options. Accepting these suggestions helps make sure you use the correct option syntax.

As you follow the instructions on this page to edit the Authentication Proxy configuration, you can click Validate to verify your changes (output shown on the right).

When you complete the Authentication Proxy configuration steps in this document, you can use the Save button to write your updates to authproxy.cfg, and then use the authproxy.cfg button to start the Authentication Proxy service before continuing on to the next configuration steps.

If you do not use the Proxy Manager to edit your configuration then we recommend using WordPad or another text editor instead of Notepad when editing the config file on Windows.

To add your new connection information to the Authentication Proxy:

1. Open the authproxy.cfg in your Authentication Proxy installation's conf directory in a text editor, or in the Proxy Manager utility if present on your Windows proxy server.

2. Download the Authentication Proxy authproxy.cfg file for your Active Directory sync by clicking the download a pre-configured file link in step 2 of the Duo Authentication Proxy section of the connection properties page.

3. Open the downloaded file in a text editor to copy its contents, and then paste the information from that authproxy.cfg file you downloaded into the installed Authentication Proxy's authproxy.cfg file (which you opened in a text editor or in the Proxy Manager on Windows).

The authproxy.cfg file for Active Directory sync contains a [cloud] section with the following properties:

Integrated authentication

If service account credentials are specified in Authentication Proxy v3.2.0 and later when the corresponding Active Directory sync config in the Duo Admin Panel uses "Integrated" authentication, then the proxy negotiates NTLM over SSPI authentication using the credentials instead of the machine account.

NTLMv2 or Plain authentication

Add your service account information (if necessary, depending on the authentication type you chose) to the information you downloaded and copied to your Authentication Proxy server's authproxy.cfg configuration file. Make sure to save your configuration file when done, or validate and then save in the Proxy Manager utility.

To configure an existing Authentication Proxy server for directory sync, append the [cloud] section of the config file downloaded from the Duo Admin Panel directory properties page to the current authproxy.cfg file located in the Duo Security Authentication Proxy conf folder. If you already have a [cloud] section present (and you are running proxy version 5.2.0 or later), increment the next section you're adding as [cloud2].

Save the configuration file then restart the Duo Authentication Proxy service for the change to take effect.

Here's a sample authproxy.cfg file for Plain authentication:

[cloud]
ikey=DIXXXXXXXXXXXXXXXXXX
skey=2v3O7uCJmdhFK6hsKS82HGyNUR5L1XGCRx44DjCQ
api_host=api-XXXXXXXX.duosecurity.com
service_account_username=duosync
service_account_password=Pass12345

Here's an example for multiple directory syncs using Integrated (SSPI) authentication. Notice the integration key differs but the API host is the same in both sections; this reflects the requirement that the multiple syncs must be for a single Duo customer account:

[cloud]
ikey=DIABCDEFGHIJKLMNOPQR
skey=2v3O7uCJmdhFK6hsKS82HGyNUR5L1XGCRx44DjCQ
api_host=api-12345678.duosecurity.com

[cloud2]
ikey=DISTUVWXYZABCDEFGHIJ
skey=2HGyNUR5L1XGCRx44DjCQ2v3O7uCJmdhFK6hsKS8
api_host=api-12345678.duosecurity.com

Encrypting Passwords

When running the Authentication Proxy on Windows, you may encrypt the directory user password for NTLMv2/Plain authentication stored in the [cloud] section if you do not want to store them as plain text. Use the authproxy_passwd.exe program, which can be found in the bin directory of your Authentication Proxy installation.

c:\>"C:\Program Files\Duo Security Authentication Proxy\bin\authproxy_passwd.exe"
Password:
Re-enter password:
AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAA5hII/4JlnEeB5xMBzB5D/wQAAAAeAAAAdwBpAG4AMwAyAGMAcgB5AHAAd
ABvAC4AcAB5AAAAA2YAAMAAAAAQAAAA5AHAAdABvAC4AcAB5AAAAA2YAAMAAAAAQAAAASApm6tif+wDKj+Rt0UtQ9
QAAAAAEgAlnEeB5xMBzB5D/wQAAAAeAAAAdwBpAG4AMwAyAGMAcgB5AHAAdABvQ8M7voQmwOOxqv91QmJs9QAAAAA
EgAAAoAAAABAAAACxWVslLxrlFOunUUeq+kg1CAAAAPFj+oygch2RFAAAAD9HgbRonCsy/GNx4M9FxSq/KJCq

Copy and paste the output into your configuration file as and remove any line breaks. You may find it easier to redirect the command output to a file and then open the file in Notepad.

When using encrypted passwords or secrets, use the "protected" version of the parameter:

Here's a sample authproxy.cfg file for Plain authentication with an encrypted secret key and service account password:

[cloud]
ikey=DIXXXXXXXXXXXXXXXXXX
skey_protected=AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAAEK80Kg76BUKI63ApctGZ/wQAAAAeAAAAdwBpAG4AMwAyAGMAcgB5AHAAdABvAC4AcAB5AAAAA2YAAMAAAAAQAAAAMlqARKe+pLNcFwVWWzLfrwAAAAAEgAAAoAAAABAAAAAe+ADzHx0OmowXFu+95w4ACAAAAC+9Hae0HWbNFAAAAA/94/UTD1iB2vnlGcVvDaqKtdcu
api_host=api-XXXXXXXX.duosecurity.com
service_account_username=duosync
service_account_password_protected=QAAANCMnd8BFdERjHoAwE/Cl+sBAAAA5hII/4JlnEeB5xMBzB5D/wQAAAAeAAAAdwBpAG4AMwAyAGMAcgB5AHAAdABvAC4AcAB5AAAAA2YAAMAAAAAQAAAA5AHAAdABvAC4AcAB5AAAAA2YAAMAAAAAQAAAASApm6tif+wDKj+Rt0UtQ9QAAAAAEgAlnEeB5xMBzB5D/wQAAAAeAAAAdwBpAG4AMwAyAGMAcgB5AHAAdABvQ8M7voQmwOOxqv91QmJs9QAAAAAEgAAAoAAAABAAAACxWVslLxrlFOunUUeq+kg1CAAAAPFj+oygch2RFAAAAD9HgbRonCsy/GNx4M9FxSq/KJCq

See additional password/secret encryption options in the Authentication Proxy Reference.

Start the Proxy

net start DuoAuthProxy

authproxyctl start

net stop DuoAuthProxy & net start DuoAuthProxy

authproxyctl restart

# /opt/duoauthproxy/bin/authproxyctl start

# /opt/duoauthproxy/bin/authproxyctl status

# /opt/duoauthproxy/bin/authproxyctl restart

Once you've started the Authentication Proxy service, return to the AD Sync Connection page in the Duo Admin Panel and click the Test Connection link in step 5 of the "Authentication Proxy" section. The connection's status still says "Not connected", but the "Add Authentication Proxy" step should now show as checked. You're ready to move on to the next setup step, Directory Configuration.

If the "Add Authentication Proxy" status information doesn't update when you test the connection, double-check the information in your authproxy.cfg and make sure the proxy service is running, then test the connection again.

You can view information about your Authentication Proxy in the Authentication Proxy Dashboard.

Directory Configuration

Enter the required directory connection information:

Click Save at the top of the page after entering the Directory Configuration information. If the Duo Authentication Proxy was able to contact the specified directory server and perform a search for groups using the given Base DN, then the status shown on the right will show as Connected.

Your connection is ready to use. Click the "Back to your sync name" link or the link for your sync under "Connected Directory Syncs" to return to the properties page of your new AD Sync. You will finish configuring the directory sync there with your selected Groups and Synced Attributes information.

To change the name of this sync connection to something more descriptive, click the Rename link to the right of the current name. Enter your new name and then click Save. You can always return to the sync connection properties page later to rename the sync or make other changes.

Groups

Once you've returned to the new AD Sync page the next step is selecting groups from your source directory to sync into Duo.

Click in the Groups box and start typing an 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 directory, Duo limits the search results to 100 groups, so you may need to type in most of your desired sync group's name or enter a complete DN for the group (like CN=Duo-Users,OU=Groups,DC=domain,DC=local) to locate it.

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

Once you see your intended group (or a list of groups), click to select the desired group to sync. Repeat this until you've added all the groups you want to import. You can select up to 400 groups to sync from the source directory. Members of the groups you choose here will be synced as users 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 AD 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 AD domain on the Duo Admin Panel and delete the recreated group from your sync configuration, then re-add the group and save the directory.

If you save the sync without selecting any groups, or if you remove all the groups selected from the sync config in the future, Duo pauses your scheduled sync upon detecting the missing information and updates the sync status to alert you that no groups have been selected. Correct the issue by selecting one or more groups to sync from the source directory and resuming scheduled synchronization.

Synced Attributes

Make changes here if you want to customize which AD attribute values get imported to Duo. The Duo attributes that have default 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 AD source attributes for these Duo user properties:

Enrollment Email

Select the Enrollment Email 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 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. 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 User Sync Setup

Click Complete Setup to finish creating the new Active Directory sync in Duo.

The directory page shows the status as "Connected to Duo" and the "Sync status" indicates when the next scheduled sync will run now that all directory configuration steps have been completed successfully. If you wish you can click the Sync Now button to perform the first import of users from your directory into Duo.

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

User Enrollment and Activation

After adding new users to Duo through Active Directory synchronization, your next step is to have them activate their Duo access (if you chose not to send enrollment emails to synced users when creating your directory in Duo). Because a phone created by directory sync defaults to the "Generic Smartphone" platform, on the Users page you'll see a notification bar indicating that users have not yet activated the Duo Mobile smartphone app. This bar provides a link to click to send 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 (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 sync 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 run manual syncs, update the sync settings, and perform other sync management operations.

To access your configured sync:

1. Log in to the Duo Admin Panel. Locate Users in the left side bar and then click Directory Sync on the submenu or click the Directory Sync link on the "Users" page.

2. The "Directory Sync" tab lists all your configured syncs and shows their type, scheduled sync status, and the time a full sync was last run. Select the sync you want to manage by clicking on its name in the list.

3. Perform your management actions from the sync's properties page.

Perform a Full Sync

A full users directory sync runs automatically twice a day (at a set 12-hour interval chosen at random).

Perform a manual full sync of the users in your directory to Duo by clicking Sync Now in the "Sync Controls" section. This immediately imports all members of your selected AD groups into Duo, creating and updating users and groups as necessary.

When the full sync completes, you'll see a count of users and groups synced into Duo.

Cancel a Full Sync

If you need to cancel a full sync in progress then click the Cancel sync action that appears while the sync is running. This will stop the sync, but any user and group updates already applied by the sync before you canceled it remain in place.

We recommend running another full sync at the earliest opportunity to address any user or group inconsistencies from the canceled sync.

Sync Individual Users from the Duo Admin Panel

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

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

To sync individual users:

1. Type up to 50 Active Directory user names as a comma-separated list into the Sync individual users text box found in the "Sync Controls" section on the directory's properties page. If you used a different source attribute than sAMAccountName for the Duo username, you must type each username exactly as it is shown (or will be shown) in Duo i.e. if you opted to use mail as the username attribute, you must enter the values of the mail attribute as the usernames to sync.

   Additionally, individually synced users must be members of a group specified in your directory sync's configuration. If you try to sync an individual user who is not a member of a selected group then no update of that user occurs.

2. Click the Sync Users button to import information about the specified user or users.

When initiated, the individual user sync verifies that each specified user is a member of a group currently synced with Duo and then imports information for that user into Duo. If a specified 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 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 specified 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 include a specified user that is no longer a member of any group synced into Duo, then the sync marks the user for deletion.

In addition to syncing individual users by username from the directory's details page, 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.

Individual User Sync using Admin API

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

Pause Directory Sync

Should you want to put your directory sync on hold to prevent it from making changes to your imported users, you can do so without removing your Active Directory configured sync from Duo. Use the pause functionality to stop scheduled syncs from running until you want to resume them.

To pause or resume synchronization of a directory:

1. From the Directory Sync page click on the directory for which you want to pause or resume scheduled syncs to view its configuration page.

2. Click the Pause automatic syncs or Resume automatic syncs action in the "Sync Status" section to perform the stated action. The sync status updates to reflect the effective state of the scheduled sync.

You can perform manual full and individual syncs at any time from the Admin Panel or via Admin API while the scheduled sync remains paused.

If your AD sync has no selected groups in the configuration then we'll pause scheduled syncs right away and the sync's status will show an alert for no groups selected. Select a group or groups and save the change to resume the sync.

Sync Failure Notifications

Duo tracks failures of your scheduled directory synchronizations. We'll send a notification email to all Duo administrators with the Owner, Administrator, or User Manager roles after three (3) days of consecutive sync failures. If the failure persists, we'll send additional notification emails after seven (7) and 14 days. Duo will send a final email notification after 30 days of consecutive sync failures and pause the scheduled sync automatically.

Visit your Active Directory sync's page in the Admin Panel to correct the issues preventing sync success, or delete the directory sync if you no longer wish to use it.

To resume the paused sync after correcting any issues, click the Resume automatic syncs action in the "Sync status" section.

Update Sync Connection

To view or modify the connection used by a given directory sync, either locate the connection on the "Connections" tab of the directory sync page in the Admin Panel and click on it, or click the Edit connection link shown on the right side of a sync's properties page, in the "Active Directory Connection" information.

You can change the connection's name, reset the secret key (be sure to update the secret key value in your Authentication Proxy's authproxy.cfg immediately and restart the proxy service to reestablish the connection), or update directory configuration information for your connection at any time.

If you want to switch a sync from one connection to another, click the Change connection link on the right side of the sync's page. You'll see the same options to reuse an existing connection or to create a new connection that you saw when you first created the sync. Make your choice and proceed.

Delete Synced Directories

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

• Users previously synced 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 synced remain in Duo attached to the same users. Activation status remains unchanged.

When you delete a directory sync and the connection used by that sync is not used by any other sync you can optionally delete the connection at the same time.

To delete a synced directory, click the Delete Directory Sync link at the top-right of that sync's details page and confirm that you want to delete that directory. If this is the last or only directory sync using the associated connection and you don't want to delete that connection, be sure to uncheck the Delete connection box before clicking the Delete button (option not shown if the connection is used by another sync).

Manage Synced Users and Groups

Update 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 Active Directory via the Admin Panel, Admin API, or CSV import, including those that correspond with optional AD sync attributes you chose not to import. However, if you update your 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 Active Directory.

Examples:

• You do not enable import of Notes when you create your AD directory sync. The sync imports the username, email, and name from AD, 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 the remaining aliases. The sync imports values for "Username Alias 1" from AD, 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 AD sync to add a source attribute for Username alias 1. The next sync updates the "Username Alias 1" value for all synced users to match the value in AD, 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 user is disabled in the source Active Directory (userAccountControl set to 514), on the next sync Duo updates the user's status to "Disabled" but does not send that user to the trash, and retains the user's group memberships. The user remains read-only, and cannot be manually enabled. Disabling a user invalidates existing remembered device sessions.

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.

Delete 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 is sent to the Trash and marked as "Pending Deletion", 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 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.

Manage Synced Groups

Duo groups created by directory sync 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 sync-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 Active Directory sync are identified as such in the Admin Panel and Admin API output. When viewing groups in the Admin Panel, you'll see from AD Sync "name of sync" 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 Entra ID 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 AD Sync "name of sync" to Group name (formerly from "name of sync").

Set Up Admin Sync

Role required: Owner.

Review the Prerequisites information before setting up Admin Directory Sync.

Create or Choose a Connection for Admin Sync

To start setting up an admin directory sync:

1. Log in to the Duo Admin Panel.

2. Navigate to Users in the left side bar and then click Administrators → Admin Directory Sync on the submenu.

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

4. If this is the first Active Directory sync you've created for users or admins then you must first create a new connection to use for this sync. With Add new connection selected, click Continue to proceed to the next step.

   

   If you have previously created an Active Directory sync for users or administrators you can either create another new connection or reuse an existing connection to that directory for this new sync. User syncs and admin syncs can share connections to the same source directory.

   If you want to use an existing connection choose Reuse existing connection and use the drop-down to select one from the list, then click Continue.

   

   You'll proceed directly to the new sync's properties page, where you'll perform role mapping and configure the synced attributes.

Install Duo Authentication Proxy

If you chose to create a new connection then your next step is to install the Duo Authentication Proxy software on a machine that can connect to both Duo's cloud service and to your AD domain controller. Before proceeding, you should locate (or set up) a system in your environment on which you will install the Duo Authentication Proxy. This host needs LDAP connectivity to your AD domain controller (ports 389/636 or whichever ports accept Active Directory binds), as well as HTTPS/443 connectivity to Duo.

If you are already running an Authentication Proxy server in your environment, you can also use that host for directory synchronization. If your existing Authentication Proxy server is version 5.2.0 or later, and it's already running a directory sync, you can use the same proxy connection to run additional syncs as long as they are all for the same Duo customer account (identical api_host values).

Locate (or set up) a system on which you will install the Duo Authentication Proxy. We recommend the following 64-bit operating systems for the system hosting the Duo Authentication Proxy:

• Windows Server 2016 or later
• CentOS 7
• CentOS Stream 8 or later
• Fedora 37 or later
• Red Hat Enterprise Linux 7 or later
• Ubuntu 20.04 LTS or later
• Debian 11 or later

If you opt for Integrated authentication, the Authentication Proxy server must be a domain-joined Windows 2016 or later server.

The Duo End of Sale, Last Date of Support, and End of Life Policy states that Duo does not offer support for integrations running on operating system versions beyond the vendor’s stated Last Date of Support date.

If you will reuse an existing Duo Authentication Proxy server for this new application, you can skip the install steps and go to Configure the Proxy.

The Duo Authentication Proxy can be installed on a physical or virtual host. We recommend a system with at least 1 CPU, 200 MB disk space, and 4 GB RAM (although 1 GB RAM is usually sufficient). See additional Authentication Proxy performance recommendations in the Duo Authentication Proxy Reference.

We do not recommend installing the Duo Authentication Proxy on the same Windows server that acts as your Active Directory domain controller or one with the Network Policy Server (NPS) role. If you must co-locate the Duo Authentication Proxy with these services, be prepared to resolve potential LDAP or RADIUS port conflicts between the Duo service and your pre-existing services.

duoauthproxy-version.exe /S

duoauthproxy-version.exe /S /exclude-auth-proxy-manager

sudo ./duoauthproxy-build/install --install-dir /opt/duoauthproxy --service-user duo_authproxy_svc --log-group duo_authproxy_grp --create-init-script yes

Configure the Proxy

After the installation completes, you will need to configure the proxy with your connection information. Note that as of v4.0.0, the default file access for the conf directory is restricted to the built-in "Administrators" group during installation on Windows systems.

The Duo Authentication Proxy configuration file is named authproxy.cfg, and located in the conf subdirectory of the proxy installation.

Download the Authentication Proxy authproxy.cfg file for your AD domain sync by clicking the download a pre-configured file link in step 2 of the Duo Authentication Proxy section of the directory properties page. This file contains the values needed to set up the connection. You could also copy the values directly from the Admin Panel to paste into your server's config file.

The configuration file is formatted as a simple INI file. Section headings appear as:

[section]

Individual properties beneath a section appear as:

name=value

A first time Authentication Proxy install may include an existing authproxy.cfg with some example content. If this is the first time you're configuring this Authentication Proxy server, you should delete the existing sample content.

Duo Authentication Proxy Manager

The Duo Authentication Proxy Manager is a Windows utility for managing the Authentication Proxy installation on the Windows server where you install the Authentication Proxy. The Proxy Manager comes with Duo Authentication Proxy for Windows version 5.6.0 and later.

The Proxy Manager cannot manage remote Duo Authentication Proxy servers, nor can you install the Proxy Manager as a stand-alone application. There is no Proxy Manager available for Linux. The Proxy Manager only functions as part of a local Duo Authentication Proxy installation on Windows servers.

Learn more about using the Proxy Manager in the Duo Authentication Proxy Reference.

To launch the Proxy Manager utility:

• Open the Start Menu and go to Duo Security.
• Click the Duo Authentication Proxy Manager icon to launch the application. You must have administrative privileges on the Windows server and accept the prompt for elevation.
• The Proxy Manager launches and automatically opens the %ProgramFiles%\Duo Security Authentication Proxy\conf\authproxy.cfg file for editing.

Use the Proxy Manager editor on the left to make the authproxy.cfg changes in these instructions. As you type into the editor, the Proxy Manager will automatically suggest configuration options. Accepting these suggestions helps make sure you use the correct option syntax.

As you follow the instructions on this page to edit the Authentication Proxy configuration, you can click Validate to verify your changes (output shown on the right).

When you complete the Authentication Proxy configuration steps in this document, you can use the Save button to write your updates to authproxy.cfg, and then use the authproxy.cfg button to start the Authentication Proxy service before continuing on to the next configuration steps.

If you do not use the Proxy Manager to edit your configuration then we recommend using WordPad or another text editor instead of Notepad when editing the config file on Windows.

To add your new connection information to the Authentication Proxy:

1. Open the authproxy.cfg in your Authentication Proxy installation's conf directory in a text editor, or in the Proxy Manager utility if present on your Windows proxy server.

2. Download the Authentication Proxy authproxy.cfg file for your Active Directory sync by clicking the download a pre-configured file link in step 2 of the Duo Authentication Proxy section of the connection properties page.

3. Open the downloaded file in a text editor to copy its contents, and then paste the information from that authproxy.cfg file you downloaded into the installed Authentication Proxy's authproxy.cfg file (which you opened in a text editor or in the Proxy Manager on Windows).

The authproxy.cfg file for Active Directory sync contains a [cloud] section with the following properties:

Integrated authentication

NTLMv2 or Plain authentication

Add your service account information (if necessary, depending on the authentication type you chose) to the information you downloaded and copied to your Authentication Proxy server's authproxy.cfg configuration file. Make sure to save your configuration file when done, or validate and then save in the Proxy Manager utility.

To configure an existing Authentication Proxy server for directory sync, simply append the [cloud] section of the config file downloaded from the Duo Admin Panel directory properties page to the current authproxy.cfg file located in the Duo Security Authentication Proxy conf folder. If you already have a [cloud] section present (and you are running proxy version 5.2.0 or later), increment the next section you're adding as [cloud2].

Save the configuration file then restart the Duo Authentication Proxy service for the change to take effect.

Here's a sample authproxy.cfg file for Plain authentication:

[cloud]
ikey=DIXXXXXXXXXXXXXXXXXX
skey=2v3O7uCJmdhFK6hsKS82HGyNUR5L1XGCRx44DjCQ
api_host=api-XXXXXXXX.duosecurity.com
service_account_username=duosync
service_account_password=Pass12345

Here's an example for multiple directory syncs using Integrated (SSPI) authentication. Notice the integration key differs but the API host is the same in both sections; this reflects the requirement that the multiple syncs must be for a single Duo customer account:

[cloud]
ikey=DIABCDEFGHIJKLMNOPQR
skey=skey=2HGyNUR5L1XGCRx44DjCQ2v3O7uCJmdhFK6hsKS8
api_host=api-12345678.duosecurity.com

[cloud2]
ikey=DISTUVWXYZABCDEFGHIJ
skey=2v3O7uCJmdhFK6hsKS82HGyNUR5L1XGCRx44DjCQ
api_host=api-12345678.duosecurity.com

Encrypting Passwords

When running the Authentication Proxy on Windows, you may encrypt the directory user password for NTLMv2/Plain authentication stored in the [cloud] section if you do not want to store them as plain text. Use the authproxy_passwd.exe program, which can be found in the bin directory of your Authentication Proxy installation.

c:\>"C:\Program Files\Duo Security Authentication Proxy\bin\authproxy_passwd.exe"
Password:
Re-enter password:
AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAA5hII/4JlnEeB5xMBzB5D/wQAAAAeAAAAdwBpAG4AMwAyAGMAcgB5AHAAd
ABvAC4AcAB5AAAAA2YAAMAAAAAQAAAA5AHAAdABvAC4AcAB5AAAAA2YAAMAAAAAQAAAASApm6tif+wDKj+Rt0UtQ9
QAAAAAEgAlnEeB5xMBzB5D/wQAAAAeAAAAdwBpAG4AMwAyAGMAcgB5AHAAdABvQ8M7voQmwOOxqv91QmJs9QAAAAA
EgAAAoAAAABAAAACxWVslLxrlFOunUUeq+kg1CAAAAPFj+oygch2RFAAAAD9HgbRonCsy/GNx4M9FxSq/KJCq

Copy and paste the output into your configuration file as and remove any line breaks. You may find it easier to redirect the command output to a file and then open the file in Notepad.

When using encrypted passwords or secrets, use the "protected" version of the parameter:

Here's a sample authproxy.cfg file for Plain authentication with an encrypted secret key and service account password:

[cloud]
ikey=DIXXXXXXXXXXXXXXXXXX
skey_protected=AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAAEK80Kg76BUKI63ApctGZ/wQAAAAeAAAAdwBpAG4AMwAyAGMAcgB5AHAAdABvAC4AcAB5AAAAA2YAAMAAAAAQAAAAMlqARKe+pLNcFwVWWzLfrwAAAAAEgAAAoAAAABAAAAAe+ADzHx0OmowXFu+95w4ACAAAAC+9Hae0HWbNFAAAAA/94/UTD1iB2vnlGcVvDaqKtdcu
api_host=api-XXXXXXXX.duosecurity.com
service_account_username=duosync
service_account_password_protected=QAAANCMnd8BFdERjHoAwE/Cl+sBAAAA5hII/4JlnEeB5xMBzB5D/wQAAAAeAAAAdwBpAG4AMwAyAGMAcgB5AHAAdABvAC4AcAB5AAAAA2YAAMAAAAAQAAAA5AHAAdABvAC4AcAB5AAAAA2YAAMAAAAAQAAAASApm6tif+wDKj+Rt0UtQ9QAAAAAEgAlnEeB5xMBzB5D/wQAAAAeAAAAdwBpAG4AMwAyAGMAcgB5AHAAdABvQ8M7voQmwOOxqv91QmJs9QAAAAAEgAAAoAAAABAAAACxWVslLxrlFOunUUeq+kg1CAAAAPFj+oygch2RFAAAAD9HgbRonCsy/GNx4M9FxSq/KJCq

See additional password/secret encryption options in the Authentication Proxy Reference.

Start the Proxy

net start DuoAuthProxy

authproxyctl start

net stop DuoAuthProxy & net start DuoAuthProxy

authproxyctl restart

# /opt/duoauthproxy/bin/authproxyctl start

# /opt/duoauthproxy/bin/authproxyctl status

# /opt/duoauthproxy/bin/authproxyctl restart

Once you've started the Authentication Proxy service, return to the AD Sync Connection page in the Duo Admin Panel and click the Test Connection link in step 5 of the "Authentication Proxy" section. The connection's status still says "Not connected", but the "Add Authentication Proxy" step should now show as checked. You're ready to move on to the next setup step, Admin Directory Configuration.

If the "Add Authentication Proxy" status information doesn't update when you test the connection, double-check the information in your authproxy.cfg and make sure the proxy service is running, then test the connection again.

Admin Directory Configuration

Enter the required directory connection information:

Click Save at the top of the page after entering the Directory Configuration information. If the Duo Authentication Proxy was able to contact the specified directory server and perform a search for groups using the given Base DN, then the status shown on the right will show as Connected.

Your connection is ready to use. Click the "Back to your sync name" link or the link for your sync under "Connected Directory Syncs" to return to the properties page of your new AD Admin Sync. You will finish configuring the directory sync there with your selected role mapping groups and Synced Attributes information.

To change the name of this sync connection to something more descriptive, click the Rename link to the right of the current name. Enter your new name and then click Save. You can always return to the sync connection properties page later to rename the sync or make other changes.

Duo Roles and Active Directory Groups

Admin directory sync imports admins and assigns Duo admin roles to your imported Duo admins based on their membership in the groups you define for each admin role in your admin sync's properties.

Check the box next to each role you would like to assign via sync. For each selected role, click in the Select AD groups field and start typing a 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 directory, Duo limits the search results to 100 groups, so you may need to type in most of your desired sync group's name or enter a complete DN for the group (like CN=Duo-Admins,OU=Groups,DC=domain,DC=local) to locate it.

If you don't see any of your 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. Members of the groups you choose here will be synced into Duo as administrators, with their assigned admin role corresponding to the selected mapping. You can sync multiple groups to the same role, and admins who are members of subgroups of the selected groups will also be synced.

If an existing administrator has the same email as an administrator in your selected groups, that administrator will be taken over by sync.

If an admin is a member of multiple synced groups that are mapped to multiple roles, the admin will receive the higher level role, for example, a user who is a member of both a group you select for the Administrator role and a group you select for the Help Desk role receives the Administrator role.

The available roles are listed in descending order of role precedence from Administrator to Read-only on the admin sync page. Admin directory sync cannot create new admins with the Owner role, nor can it update existing Duo admins with the Owner role.

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 AD groups saved in the sync properties (even if you reused the same group name and members), then you'll need to return to the admin directory sync property page for your AD domain in the Duo Admin Panel and delete the recreated group from your sync's role-mapping selections, then re-add the group and save the directory.

If you save the sync without selecting any groups, or if you remove all the groups selected from the sync config in the future, Duo pauses your automatic syncs upon detecting the missing information and updates the sync status to alert you that no groups have been selected. Correct the issue by selecting one or more groups to sync from the source directory and resuming scheduled synchronization.

Admin Synced Attributes

Make changes here if you want to customize which AD attribute values get imported to Duo. The Duo attributes that have default 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 AD source attributes for these Duo admin properties:

Communication Preferences

Use the "Communications Preferences" to determine what sync information is emailed to Duo Owner admins.

Choose one of these options in the Sync notifications section:

• Every time an administrator change occurs: receive separate, immediate notifications whenever a sync creates, deletes, or updates an administrator.

• Only if the sync stops working: receive an email only when a sync fails to run (default).

The Contact info setting lets you select certain Duo administrators with the Owner role to receive notifications. By default, Directory Sync sends notifications to all active admins with the Owner role.

Admin Activation

Select the Send activation emails to synced admins option in the "Admin Activation" section if you want imported admins to automatically receive an admin activation email with a link to set up a password and 2FA device. Emails are sent to the email address associated with the newly created admin.

The setup links contained in these emails are valid for seven (7) days. If the admin does not complete the setup process after seven days have elapsed, the original setup link expires and a new email is generated at the next sync and sent to the admin.

The pending admin setup link is displayed on an administrator’s page and can be directly provided to new admins. Admin activation emails can also be resent or pending admin activation links invalidated and recreated from the administrator’s details page.

Default: Send activation emails to imported admins.

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

Finish Admin Sync Setup

Click Complete Setup to finish creating the new Active Directory admin sync in Duo.

The directory page shows the status as "Connected to Duo" and the "Sync status" indicates when the next automatic sync will run once all directory configuration steps have been completed successfully.

If you wish you can click the Sync Now button to perform the first import of admins from your directory into Duo. Whether you run your first sync immediately after setup or not, admin directory sync runs automatically around every 30 minutes. You can always return to the Duo Admin Panel to initiate a manual sync.

Note that once you import admins from Active Directory into Duo you may not change the Email source attribute.

Manage Admin Sync

Role required: Owner.

Once configured, you can run manual admin syncs, update the sync settings, and perform other sync management operations.

To access your configured admin sync:

1. Log in to the Duo Admin Panel.

2. Navigate to Users in the left side bar and then click Administrators → Admin Directory Sync on the submenu.

3. The "Directory Syncs" tab lists all your configured admin syncs and shows their type, automatic sync status, and the time a full sync was last run. Select the sync you want to manage by clicking on its name in the list.

4. Perform your management actions from the admin sync's properties page.

Perform a Full Admin Sync

A full admin directory sync runs automatically every 30 minutes.

Perform a manual full sync of the admins in mapped admin groups in your directory to Duo by clicking Sync Now in the "Sync Controls" section. This immediately imports all members of your selected AD groups into Duo, creating and updating admins as necessary.

When the full sync complete, you'll see a count of admins and groups synced into Duo. Note that the groups synced by an admin sync are only used for admin role mapping, and do not show up on the Groups page in the Duo Admin Panel.

Cancel a Full Admin Sync

If you need to cancel a full admin sync in progress then click the Cancel sync action that appears while the sync is running. This will stop the sync, but any admin updates already applied by the sync before you canceled it remain in place.

We recommend running another full sync at the earliest opportunity to address any inconsistencies from the canceled sync.

Sync Individual Admins from the Duo Admin Panel

When you just need to import information for a few admins from Active Directory you can interactively sync selected admins instead of syncing the entire directory. For example, you may have some new employee accounts in AD who need a corresponding Duo admin account, or you might have just disabled an AD user and need that status carried over to their administrator account in Duo. Syncing these individual admin accounts updates Duo immediately.

To sync individual admins:

1. Type up to 50 email addresses as a comma-separated list into the Sync individual admins text box found in the "Sync Controls" section on the directory's properties page.

   Additionally, individually synced admins must be members of a group specified as a role group in the "Duo Roles and Active Directory Groups" section of your directory sync's configuration. If you try to sync an individual admin who is not a member of a synced group then no update of that admin occurs.

2. Click the Sync Admins button to import information about the specified admin or admins.

When initiated, the individual admin sync verifies that each specified admin is a member of a group currently synced with Duo and then imports information for that admin into Duo. If a specified admin 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 activation emails then a new admin created by the individual admin sync receives an emailed activation link.

Individual admin sync updates an existing specified admin with information from the source directory. The sync can change attribute values, modify the assigned Duo admin role, or disable the admin in Duo if they are disabled in the source directory.

If you include a specified admin that is no longer a member of any group synced into Duo, then the sync marks the admin for deletion. Admins pending deletion will be deleted in seven (7) days. In that time, if the admin is re-added to a synced group, the admin will be restored.

In addition to syncing individual admins by email from the directory's details page, you can also perform an individual sync on an existing Duo admin by visiting that admin's properties page in the Duo Admin Panel and clicking the Sync This Admin link at the top-right.

Individual Admin Sync using Admin API

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

Pause Admin Sync

Should you want to put your directory sync on hold to prevent it from making changes to your imported admins, you can do so without removing your Active Directory configured sync from Duo. Use the pause functionality to stop scheduled syncs from running until you want to resume them.

To pause or resume synchronization of a directory:

1. From the Admin Directory Sync page click on the directory for which you want to pause or resume scheduled syncs to view its configuration page.

2. Click the Pause automatic syncs or Resume automatic syncs action in the Directory Sync "Status" section to perform the stated action. The sync status updates to reflect the effective state of the scheduled sync.

You can perform manual full and individual syncs at any time from the Admin Panel or via Admin API while the scheduled sync remains paused.

If your admin sync has no mapped role groups in the configuration then we'll pause scheduled syncs right away and the admin sync's status will show an alert for no groups selected. Select a group or groups and save the change to resume the sync.

Sync Failure Notifications

Duo tracks failures of your automatic admin directory synchronizations. We'll send a notification email to the Duo Owners specified in the sync's Communication Preferences after one (1) day of consecutive sync failures. If the failure persists, we'll send additional notification emails after three (3). Duo will send a final email notification after seven (7) days of consecutive admin sync failures and pause the sync automatically.

Visit your admin sync's page in the Admin Panel to correct the issues preventing sync success, or delete the admin directory sync if you no longer wish to use it.

To resume the paused sync after correcting any issues, click the Resume automatic syncs action in the "Sync status" section.

Update Admin Sync Connection

To view or modify the connection used by a given admin directory sync, either locate the connection on the "Connections" tab of the Admin Directory Sync page in the Admin Panel and click on it, or click the Edit connection link shown on the right side of an admin sync's properties page, in the "Active Directory Connection" information.

You can change the connection's name, reset the secret key (be sure to update the secret key value in your Authentication Proxy's authproxy.cfg immediately and restart the proxy service to reestablish the connection), or update directory configuration information for your connection at any time.

If you want to switch a sync from one connection to another, click the Change connection link on the right side of the sync's page. You'll see the same options to reuse an existing connection or to create a new connection that you saw when you first created the sync. Make your choice and proceed.

Delete Admin Syncs

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

• Admins previously synced remain available and retain the status and role previously assigned.

• Any 2FA methods associated with the admin remain available.

When you delete an admin directory sync and the connection used by that sync is not used by any other sync you can optionally delete the connection at the same time.

To delete an admin sync, click the Delete Directory Sync link at the top-right of that sync's details page and confirm that you want to delete that directory. If this is the last or only directory sync using the associated connection and you don't want to delete that connection, be sure to uncheck the Delete connection box before clicking the Delete button (option not shown if the connection is used by another sync).

Manage Synced Admins

Update Synced Admin Information

Admin attributes synced from an external directory generally cannot be edited in Duo via the Admin Panel or Admin API. This applies to the attributes email, full name, role, and status. Changes to these attributes should be made in the external directory and then synced over to Duo.

You may edit Administrative units and 2FA devices, including phone numbers, for synced admins. Synced administrators may update their own password and 2FA devices from the "Edit Profile" page in the Duo Admin Panel.

Change a Synced Admin's Role

To update an admin’s assigned role, either update the admin’s group membership in your source directory to add the admin to a group which has been mapped to the desired role in the admin sync config, or modify the role-to-group mapping on the admin sync's details page to include the desired group.

To update a synced admin’s role to the Owner role, go to the properties page for that administrator and check the Upgrade to Owner checkbox in the "Role" section, and then click Save. This converts the synced admin to an unmanaged admin with the Owner role. Admins with the Owner role assigned in this manner cannot be managed or modified by Directory Sync, regardless of group membership.

Disabled Status for Synced Admins

Duo Owner admins can't disable individual Duo admins managed by directory sync from the Duo Admin Panel or Admin API. Directory sync checks the admin's user account status in the source directory and uses that information to determine whether the corresponding Duo admin should remain enabled.

If a synced admin is disabled in the source Active Directory (userAccountControl set to 514), on the next sync Duo updates the user's status to "Disabled" but does not delete the admin. The Duo admin account remains read-only, and cannot be manually enabled.

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

Delete Synced Admins

You may not delete a synced admin from Duo as long as directory sync is actively managing that admin. If a synced directory admin is removed from all external directory groups that sync to Duo (or if the admin's user account is deleted from the source directory), the admin is marked as "Pending Deletion" at the next sync, and the admin can no longer log in to the Duo Admin Panel.

View a list of admins pending deletion by navigating to the Administrators page in the Admin Panel and applying the "Pending Deletion" filter.

If the admin marked for deletion is not reconnected to an external directory account via the sync within seven (7) days, the admin is automatically deleted from Duo. The admin's properties show the target date for deletion. A Duo admin with the Owner role can manually delete a synced pending deletion admin via the Permanently Delete button at any time during those seven days. Synced Duo admins pending deletion can also be restored using the Restore Admin button, but will no longer be synced unless an account with the same email is added back to a synced admin group in the source directory.

Frequently Asked Questions

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

Troubleshooting

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

On the details page of your directory sync there is a Troubleshooting section under the "Sync Now" button. Here you'll find tips to help your sync run as intended. If you are still having issues and need to open a support case with Duo, you can click Sync Directory with Diagnostics to provide Duo Support with more information about your sync.

Additionally, a sync reference code is now provided on every sync. This will be included on every directory 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

1. Duo Authentication Proxy requests information from Active Directory over LDAP, LDAPS, or STARTTLS.
2. Duo Authentication Proxy contacts Duo's service over HTTPS/443 to complete user, group, and admin synchronization.