Learn how to synchronize Duo users and groups from your existing Active Directory domain.
Import Duo user information directly from your on-premises Active Directory domain into Duo with Duo Security's Directory Sync feature. Directory attributes that may be populated include name, email address, phone numbers, and group memberships.
The Directory Sync feature is part of the Duo Beyond, Duo Access, and Duo MFA plans.
Before executing any Active Directory synchronization with Duo, understand the effect that synchronization can have on accounts with the same name. Suppose that you already have some Duo users, and one or more of these users have the same username on your Active Directory server. Performing a synchronization will cause the existing Duo users' information to be merged with, and in some cases overwritten by the Active Directory information, such as email addresses in Duo changing to match the value stored in the synced directory.
Likewise, if you are doing Active Directory synchronization from multiple directories and there are non-unique usernames among those directories, there will be only one Duo user with that username, and each sync will update that Duo user with different information.
The same potential conflict applies to Duo groups. If an existing Duo group has the same name as a synced group, the synced group will overwrite the group information and membership in Duo.
Prerequisites necessary for Active Directory synchronization are as follows:
Role required: Owner, Administrator, or User Manager.
To start setting up Directory Sync:
Click the New Directory button.
The "New Directory" page presents the "Azure Active Directory" tab by default. Click the On-premises Active Directory tab.
Enter the basic Directory Information required to create the AD domain in Duo.
Enter a descriptive name for the directory.
The IP address or hostname of your AD domain controller (DC).
The port on which to contact your domain controller. The typical port for unsecured LDAP or STARTTLS is 389, and LDAPS is usually 636.
Select the type of authentication the Authentication Proxy will use to connect to your AD domain controller. One of:
Enter the Directory Sync settings for your AD domain.
The base DN should be a level in your directory structure above both the users and groups you plan to synchronize.
Select the Send enrollment email to synced users option if you want an enrollment link email sent automatically to imported users when the sync process completes. Only users who are imported from Active Directory with active status, a valid email address, and who do not already have any registered authentication devices in Duo receive an enrollment link via email.
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
If your organization uses e-mail filtering, be sure to whitelist the sender firstname.lastname@example.org.
Enable this option if you want Directory Sync to create phones based on the user's telephoneNumber and mobile LDAP attributes.
If left disabled, phone information will not be imported or updated from Active Directory.
International phone numbers stored in your source directory must be prefixed with + and the country code, e.g. +4401617150105 for a UK number.
If you enable both the "Enrollment email" and "Import phones" options, enrollment links are only sent to users who do not have phone information populated in Active Directory.
Enable this option if you want Directory Sync to import notes based on the user's info LDAP attribute.
If left disabled, notes will not be imported or updated from Active Directory.
|Custom attribute mapping||
Select this option if you want to customize which Active Directory attributes are imported to Duo.
You can customize the following attributes:
The Duo attributes that have default Active Directory 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". The Username attribute cannot be changed after the first directory synchronization.
When finished entering these initial fields, click Add Directory to create the new directory in Duo and expose additional configuration options.
Duo Beyond and Duo Access Plan Users: Global Policy settings affect access to the enrollment portal. Do not apply any global restrictions that could prevent user enrollment if you chose to send enrollment emails. For example, if you configure the User Location policy setting to deny access to a country, then the policy will also block any of your users who attempt to enroll in Duo from that country via a bulk enrollment link. The New User Policy setting for the enrollment portal is always "Require Enrollment".
Once you save the directory you can add additional domain controllers. Duo selects any one of the servers in the list as the target when performing a sync. In the Directory Information section, click Add backup server and enter your additional Active Directory server IP or hostname and port information.
Additional configuration options for securing connectivity between the Duo Authentication Proxy and your AD domain controller appear in the Directory Sync Settings section after initial creation.
You may adjust the Transport type setting (CLEAR, LDAPS, or STARTTLS). This determines how the connection between the Duo Authentication Proxy software and the AD domain server is encrypted, if at all. Connectivity between the Duo Authentication Proxy software and the Duo Security cloud services is always HTTPS secured with SSL and is not affected by this setting.
If you selected Plain authentication for this directory, please avoid CLEAR and switch to a secure transport type to protect your AD domain lookup credentials.
The SSL verify hostname option requires that the AD domain's SSL certificate subject "common name" or "issued to" and the server hostname you entered when setting up your directory need to match. For instance, if the Active Directory SSL certificate is issued to
dc1.acme.corp and you entered the IP of that server when setting up the directory in Duo instead of the hostname
dc.acme.corp. If you then enable this option, the connection between your Authentication Proxy and your AD domain controller fails with the message "The directory server credentials were rejected".
In order to secure LDAP connections to your AD domain server using LDAPS or STARTTLS protocols, you'll need the PEM formatted certificate from the certificate authority (CA) that issued your AD domain controller's SSL certificate.
To obtain the PEM formatted version of the AD domain controller certificate's issuing CA certificate, view the "Certification Path" tab of the DC's certificate properties and double-click the issuing certificate to view it. Export the issuing CA certificate as a Base-64 encoded X.509 (CER) format.
Open the issuing CA certificate you exported in a text editor. Copy the file contents (including the BEGIN and END wrapper) and paste into the SSL CA certs field on your AD domain configuration page. You may need to export all the certs (such as root CA and intermediate CA) in the certification path and paste them all into this page.
When you have completed configuring backup servers or additional security settings that are relevant for your environment, click the Save Directory button at the bottom of the page.
The next step after saving the directory settings is to install the Duo Authentication Proxy software on a machine that can connect to both Duo's cloud service and to your LDAP server. 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.
The minimum Authentication Proxy version for Active Directory synchronization using Integrated authentication is 2.4.9, but we recommend installing or updating to the latest version. The minimum Authentication Proxy version for Active Directory synchronization using NTLMv1/v2 or Plain authentication is 2.6.0.
This application communicates with Duo's service on TCP port 443. Firewall configurations that restrict outbound access to Duo's service with rules using destination IP addresses or IP address ranges aren't recommended, since these may change over time to maintain our service's high availability. If your organization requires IP-based rules, please review this Duo KB article.
Locate (or set up) a system on which you will install the Duo Authentication Proxy. The proxy supports Windows and Linux systems (in particular, we recommend Windows Server 2012 R2 or later, Red Hat Enterprise Linux 6 or later, CentOS 6 or later, or Debian 6 or later).
If you opted for Integrated authentication, the Authentication Proxy server must be a domain-joined Windows 2008 R2 or later server.
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).
Ensure that Perl, Python 2.6 or 2.7 (including development headers and libraries), and a compiler toolchain are installed. On most recent RPM-based distributions — like Fedora, RedHat Enterprise, and CentOS — you can install these by running (as root):
$ yum install gcc make python-devel libffi-devel perl zlib-devel
On Debian-derived systems, install these dependencies by running (as root):
$ apt-get install build-essential python-dev libffi-dev perl zlib1g-dev
Download the most recent Authentication Proxy for Unix from https://dl.duosecurity.com/duoauthproxy-latest-src.tgz. Depending on your download method, the actual filename may reflect the version e.g. duoauthproxy-2.14.0-src.tgz. View checksums for Duo downloads here.
Extract the Authentication Proxy files and build it as follows:
$ tar xzf duoauthproxy-latest-src.tgz $ cd duoauthproxy-version-src $ make
Install the authentication proxy (as root):
$ cd duoauthproxy-build $ ./install
Follow the prompts to complete the installation.
If you ever need to uninstall the proxy, run
After the installation completes, you will need to configure the proxy.
The Duo Authentication Proxy configuration file is named
authproxy.cfg, and is located in the
conf subdirectory of the proxy installation. With default installation paths, the proxy configuration file will be located at
/opt/duoauthproxy/conf/authproxy.cfg on Linux,
C:\Program Files (x86)\Duo Security Authentication Proxy\conf\authproxy.cfg for Windows (64-bit) and
C:\Program Files\Duo Security Authentication Proxy\conf\authproxy.cfg for Windows (32-bit).
Download the Authentication Proxy
authproxy.cfg file for your AD domain sync by clicking the Duo Authentication Proxy Config link in step 2 of the Duo Authentication Proxy section of the directory properties page.
The configuration file is formatted as a simple INI file. Section headings appear as:
Individual properties beneath a section appear as:
A first time Authentication Proxy install may include an existing
authproxy.cfg with some example content. For the purposes of these instructions, however, you should delete the existing sample content and paste in the information from the
authproxy.cfg file download from the directory properties page.
authproxy.cfg file for Active Directory Sync contains a
[cloud] section with the following properties:
|ikey||your integration key|
|skey||your secret key|
|api_host||your API hostname (i.e.,
NTLMv1, NTLMv2, or Plain authentication
|ikey||Your integration key.|
|skey||Your secret key.|
|api_host||Your API hostname (i.e.,
|service_account_username||The account used to bind to Active Directory. This account needs read-only access to your directory.|
|service_account_password||The directory password for the service_account_username user.|
Add the information from your downloaded
authproxy.cfg to your Authentication Proxy server configuration file. Make sure to save your configuration file when done.
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. Save the configuration file then restart the Duo Authentication Proxy service. Note that there can only be one
[cloud] section in the
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
When running the Authentication Proxy on Windows, you may encrypt the directory user password for NTLMv1/v2/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 (x86)\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.
The encrypted password is specific to the server where it was generated, and will not work if copied to a different machine. If you have multiple Authentication Proxy servers with the same service account specified, be sure to run
authproxy_passwd.exe separately on each one.
Here's a sample
authproxy.cfg file for Plain authentication with an encrypted password:
[cloud] ikey=DIXXXXXXXXXXXXXXXXXX skey=2v3O7uCJmdhFK6hsKS82HGyNUR5L1XGCRx44DjCQ 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
To start the Duo Authentication Proxy service on Windows, launch an Administrator command prompt and run:
net start duoauthproxy
Or, open the "Services" console (services.msc), locate the "Duo Security Authentication Proxy Service" in the list of services and click on it to select, and then click the start button.
To start the Duo Authentication Proxy on Linux, run:
After setting up the Duo Authentication Proxy software, the next step in Active Directory synchronization is to select which groups should be synchronized from the AD domain to Duo.
Once the Duo Authentication Proxy service is running, click the refresh this page link in section 3 Choose Groups on the directory properties page to initiate the connection between the Duo service and the Authentication Proxy server.
If the directory properties page indicates the new directory is connected to Duo Authentication Proxy and you click in the Groups box, you should see a list of Active Directory groups that are available. If you don't see any of your groups listed, review the previous setup steps (especially the Base DN) and correct your configuration.
Once you see a list of groups, click to select the desired group or groups to sync, then click Save Groups. If you start typing a group name in the box the list of available groups will match the filter. You can select up to 400 groups to sync from the source directory. Members of the groups you choose here will be synced into Duo.
Nested groups are supported; Duo sync imports users from groups nested within your sync group, but creates only the top level group in Duo (the group explicitly selected for directory sync), with all nested group members as direct members of that Duo group.
If the base DN you specified when setting up the directory has more than 10,000 groups below it, you'll see a message stating this is the case, along with an Advanced Search button.
Click Advanced Search to open the search dialog. Enter all or part of the distinguished name (DN) for a group you want to sync with Duo and then click Search. Click on your desired sync groups in the search results to select then, then click Select group(s). This adds the selected groups to your directory configuration and closes advanced search.
You can repeat the search step until all your required groups have been added to the directory sync configuration. Click Save Groups when done.
Once you have configured the directory settings, installed the Duo Authentication Proxy software, and chosen the groups to synchronize, you are ready to perform the initial synchronization with your directory.
The Sync Now button appears in the upper right hand corner of the Duo Admin Panel after all three directory configuration steps have been completed successfully.
If you wish, you can click Sync Now immediately to begin importing users from your domain into Duo. When the directory sync completes, Duo reports its success to you. Otherwise, Directory Sync runs automatically once a day (at a set time chosen at random). You can always return to the Duo Admin Panel to initiate a manual sync.
When you just need to import information for a few users from Active Directory you can use the individual user sync feature instead of syncing the entire directory. For example, you may have a new employee account in AD who needs a corresponding Duo account, or you might have just disabled an account in AD and need that status carried over to Duo. Syncing these individual user accounts updates Duo immediately.
Type a single user name in the box at the top of the directory's properties page and click the Sync This User button. The user must be a member of an AD group specified in the "Choose Groups" section of your directory's configuration. If you try to sync an individual user who is not a member of a selected group then no update occurs (and an existing user just removed from a synced group in the source directory gets disabled in Duo but won't be put into Pending Deletion status).
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.
When initiated, the individual user sync verifies that the user is a member of a group currently synced with Duo and then imports information for that user into Duo. If the user doesn't already exist in Duo, the sync creates them using the information imported from the source directory. If you enabled the option to send enrollment emails when adding the directory and the new user has the email address attribute populated, then a new user created by the individual user sync receives an emailed enrollment link.
Individual user sync updates an existing user with information from the source directory. The sync can change attribute values (except the username), modify group memberships, or disable the user in Duo if they are disabled in the source directory.
If you run an individual user sync against a user that is no longer a member of any group synced into Duo, then the sync marks the user for deletion.
Use the AdminAPI directory key from the "Directory Settings" section of the page to perform a sync operation on an individual user using Duo's Admin API.
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.
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 the user another copy of the enrollment link email, click the Resend button. Resending the email does not change the current enrollment link's expiration date.
User attributes synced from an external directory cannot be edited in Duo via the Admin Panel, Admin API, or CSV import. This includes Duo username and username aliases, real name, email address, phone numbers (if you chose to import phones), notes, and group memberships. Changes to these user attributes should be made in the external directory and then synced over to Duo.
Admins can't disable individual Duo users managed by directory sync from the Duo Admin Panel, Admin API, or CSV import. Directory sync disables users removed from the selected synced groups and puts those users in the Trash "Pending Deletion" when a full sync runs. A single-user sync disabled users removed from the sync groups (and the next full sync moves the users into the Trash).
You can restore the disabled Duo account to active status by adding the account back to the synced group 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.
You may not delete a synced user from Duo as long as directory sync is actively managing that user. If a synced directory user is removed from all external directory groups that sync to Duo (or if the user account is deleted from the source directory), the user's status changes to "Pending Deletion" at the next full directory sync or individual sync for that user, and the user can no longer authenticate to Duo. The user's properties are read-only and you are no longer billed for that user.
Locate users pending deletion in the Trash view, accessed by clicking the Trash link underneath the total user 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.
Be sure to review frequently asked questions and answers before using Duo's Active Directory synchronization.
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.