Skip navigation

Synchronizing Users into Duo from OpenLDAP

Last Updated: May 23rd, 2022

Learn how to synchronize Duo users and groups from your existing OpenLDAP directory via the Authentication Proxy.


Import Duo user names and other identity information directly from your on-premises OpenLDAP directory 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 synchronization of your full directory runs twice a day, or on-demand when initiated from the Admin Panel. You can also run an individual user sync on-demand from the Admin Panel or programmatically via Admin API.

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

Directory Sync Updates Existing Users

Before executing any OpenLDAP 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 OpenLDAP server. Performing a synchronization will cause the existing Duo users' information to be merged with, and in some cases overwritten by the OpenLDAP information, such as email addresses in Duo changing to match the value stored in the synced directory.

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

Multiple directory syncs that use non-unique user names or the same selected groups may also produce undesired results, as each sync process could overwrite the user with different information or update the group memberships for a given user unexpectedly.


Prerequisites necessary for OpenLDAP synchronization are as follows:

  • Know your OpenLDAP server 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 CA certificate for providing local network security.
  • A Windows 2012 or later, or modern Linux system (CentOS, Ubuntu, Red Hat) for running the Duo Authentication Proxy software.
  • Duo Authentication Proxy v2.6.0 or later (installation steps below).

In addition to the items above, Duo's OpenLDAP sync also has these directory requirements:


  • Synced groups must have the groupOfNames object class.
  • Synced groups must list their members by DN (directoryName) via the member attribute.
  • Synced groups must have a cn attribute, used as the Duo group name after import.
  • Synced groups must also have the attributes entrydn (used as the distinguished name) and entryuuid (the group unique identifier).


  • Synced users must list group memberships by DN using the memberOf attribute (via the memberOf overlay).
  • Synced users must have the organizationalPerson object class.
  • Synced groups must also have the attributes entrydn (used as the distinguished name) and entryuuid (the user unique identifier).

Verify that your OpenLDAP directory satisfies all the class and attribute requirements before attempting the sync. LDAP variants other than OpenLDAP may require additional configuration or modules to provide the necessary attributes to Duo.

Set Up Synchronization

Role required: Owner, Administrator, or User Manager.

Add the Directory

To start setting up Directory Sync:

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

To start setting up Directory Sync:

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

  2. Click the OpenLDAP tab heading, and then click the Add New OpenLDAP Sync button.

    Add new OpenLDAP directory
  3. You'll be taken to the details page for your new directory sync in the Duo Admin Panel. The new directory's name defaults to OpenLDAP Sync (and increments for each additional directory added i.e. "OenLDAP Sync (2)"). Click the Rename link if you'd like to change the directory sync's name to something different, clicking Save to apply the new name.

  4. The "Status" section of the page shows you the current state of your directory sync. When your OpenLDAP sync setup is complete, you'll be able to verify the connection here.

    Newly Added OpenLDAP Sync Status

    As you have just created the new directory, the status indicates your next step is to deploy and configure the Duo Authentication Proxy.

Authentication Proxy

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 LDAP server (ports 389/636 or whichever ports accept LDAP 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 to run additional syncs as long as they are all for the same Duo customer account (identical api_host values).

Connectivity Requirements

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.

Install the Duo Authentication Proxy

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

  1. Download the most recent Authentication Proxy for Windows from Note that the actual filename will reflect the version e.g. duoauthproxy-5.7.3.exe. View checksums for Duo downloads here.
  2. Launch the Authentication Proxy installer on the target Windows server as a user with administrator rights and follow the on-screen prompts.

    When installing, you can choose whether or not you want to install the Proxy Manager. The Proxy Manager is a Windows utility that helps you edit the Duo Authentication Proxy configuration, determine the proxy's status, and start or stop the proxy service. Learn more about using the Proxy Manager. Installing the Proxy Manager adds about 100 MB to the installed size.

    If you do not want to install the Proxy Manager, you may deselect it on the "Choose Components" installer screen before clicking Install.

Silent Install

To perform a silent install on Windows, issue the following from an elevated command prompt after downloading the installer (replacing version with the actual version you downloaded):

duoauthproxy-version.exe /S

Append /exclude-auth-proxy-manager to install silently without the Proxy Manager:

duoauthproxy-version.exe /S /exclude-auth-proxy-manager
  1. Ensure that Perl 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 libffi-devel perl zlib-devel diffutils

    On Debian-derived systems, install these dependencies by running (as root):

    $ apt-get install build-essential libffi-dev perl zlib1g-dev

    If SELinux is present on your system and you want the Authentication Proxy installer to build and install its SELinux module, include selinux-policy-devel in the dependencies:

    $ yum install gcc make libffi-devel perl zlib-devel diffutils selinux-policy-devel
    $ apt-get install build-essential libffi-dev perl zlib1g-dev selinux-policy-devel
  2. Download the most recent Authentication Proxy for Unix from From the command line you can use curl or wget to download the file, like $ wget --content-disposition Depending on your download method, the actual filename may reflect the version e.g. duoauthproxy-5.7.3-src.tgz. View checksums for Duo downloads here.

  3. Extract the Authentication Proxy files and build it as follows:

    $ tar xzf duoauthproxy-5.7.3-src.tgz
    $ cd duoauthproxy-version-src
    $ make
  4. Install the authentication proxy (as root):

    $ cd duoauthproxy-build
    $ ./install

    Follow the prompts to complete the installation. The installer creates a user to run the proxy service and a group to own the log directory and files. You can accept the default user and group names or enter your own.

    If SELinux is present on the target server, the Duo installer will ask you if you want to install the Authentication Proxy SELinux module. Your selection affects whether systemd can start the Authentication Proxy after installation.

    If you choose to install the Authentication Proxy SELinux module and the dependency selinux-policy-devel is not present then the installer fails to build the module.

    SELinux Mode Default Response Result
    Enforcing Yes Choose 'yes' to install the Authentication Proxy's SELinux module. This permits start of the Authentication Proxy service by systemd. If you choose 'no' then the SELinux module is not installed, and systemd cannot start the Authentication Proxy service.
    Permissive No Choose 'no' to decline install of the Authentication Proxy's SELinux module. The Authentication Proxy service can be started by systemd. However, if you change SELinux from permissive to enforcing mode after installing the Duo proxy, systemd can no longer start the Authentication Proxy service. If you plan to enable SELinux enforcing mode later, you should choose 'yes' to install the Authentication Proxy SELinux module now.
Silent Install

To install the Duo proxy silently with the default options, use the following command:

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

Append --enable-selinux=yes|no to the install command to choose whether to install the Authentication Proxy SELinux module.

Configure the Proxy

After the installation completes, you will need to configure the proxy. 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.

Operating System Authentication
Proxy Version
Windows v5.0.0 and later C:\Program Files\Duo Security Authentication Proxy\conf
Windows v4.0.2 and earlier C:\Program Files (x86)\Duo Security Authentication Proxy\conf
Linux All /opt/duoauthproxy/conf

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

Add Directory Information to the 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 OpenLDAP sync by clicking the Duo Authentication Proxy Config link in step 2 of the Duo Authentication Proxy section of the directory 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 OpenLDAP sync contains a [cloud] section with the following properties:

NTLMv1, NTLMv2, or Plain authentication

Field Value
ikey Your integration key.
skey Your secret key.
api_host Your API hostname (i.e.,
service_account_username The account used to bind to OpenLDAP. This account needs read-only access to your directory.
service_account_password The directory password for the service_account_username user.

Add your service account information 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:


Here's an example for multiple directory syncs using Plain 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:



Encrypting Passwords

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\Duo Security Authentication Proxy\bin\authproxy_passwd.exe"
Re-enter password:
Encrypted values are machine-specific

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.

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:

Instead of... Use...
service_account_password service_account_password_protected
skey skey_protected

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


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

Start the Proxy

If you installed the Duo Authentication Proxy Manager utility (available with 5.6.0 and later), click the Start Service button at the top of the Proxy Manager window to start the service.

To start the service from the command line, open an Administrator command prompt and run:

net start DuoAuthProxy

Alternatively, open the Windows Services console (services.msc), locate "Duo Security Authentication Proxy Service" in the list of services, and click the Start Service button.

Authentication Proxy v5.1.0 and later includes the authproxyctl executable, which shows the connectivity tool output when starting the service. The installer adds the Authentication Proxy C:\Program Files\Duo Security Authentication Proxy\bin to your system path automatically, so you should not need to specify the full path to authproxyctl to run it.

From an administrator command prompt run:

authproxyctl start

If the service starts successfully, Authentication Proxy service output is written to the authproxy.log file, which can be found in the log subdirectory.

If you see an error saying that the "service could not be started", open the Application Event Viewer and look for an Error from the source "DuoAuthProxy". The traceback may include a "ConfigError" that can help you find the source of the issue.

Stop and restart the Authentication Proxy service by either clicking the Restart Service button in the Duo Authentication Proxy Manager or the Windows Services console or issuing these commands from an Administrator command prompt:

net stop DuoAuthProxy & net start DuoAuthProxy

To stop and restart the Authentication Proxy using authproxyctl, from an administrator command prompt run:

authproxyctl restart

Open a root shell and run:

# /opt/duoauthproxy/bin/authproxyctl start

To ensure the proxy started successfully, run:

# /opt/duoauthproxy/bin/authproxyctl status

Authentication Proxy service output is written to the authproxy.log file, which can be found in the log subdirectory.

To stop and restart the Authentication Proxy, open a root shell and run:

# /opt/duoauthproxy/bin/authproxyctl restart


View video guides for proxy deployment at the Authentication Proxy Overview or see the Authentication Proxy Reference for additional configuration options.

Once you've started the Authentication Proxy service, return to the directory sync configuration page and click the Test Connection link in step 4 of the Authentication Proxy section. The directory status will indicate the proxy is connected and you're ready to move on to the next setup step, Directory Configuration. If you don't see the proxy connected, double-check the information in your authproxy.cfg and make sure the proxy service is running, then test the connection again.

OpenLDAP Sync Status with Authproxy Connected

Directory Configuration

Enter the required directory connection information:

Directory Server(s)

Enter the IP address or hostname of your OpenLDAP directory server, followed by the port the Authentication Proxy server should use to contact the directory server.

The typical port for unsecured LDAP or STARTTLS is 389, and LDAPS is usually 636.

Click Add Directory Server to add additional hosts. If the first server in the list doesn't respond when performing a sync, the next server is used as a fallback. If you decommission any of your directory servers be sure to return to Duo and remove it from the list.

Base DN

The base DN should be a level in your directory structure above both the users and groups you plan to synchronize.

Example: OU=CorpUsers,DC=domain,DC=local

Authentication Type

Select the type of authentication the Authentication Proxy will use to connect to your LDAP server. One of:

  • NTLMv1 - Performs Windows NTLMv1 authentication. If you select this option you'll need to enter the NTLM domain and NTLM workstation names on the new directory page in the Admin Panel, and also ensure you have specified the username and password used to connect to your LDAP server in the authproxy.cfg when you configured your Duo Authentication Proxy server.
  • NTLMv2 - Performs Windows NTLMv2 authentication. If you select this option you'll need to enter the NTLM domain and NTLM workstation names on the new directory page in the Admin Panel, and also ensure you have specified the username and password used to connect to your LDAP server in the authproxy.cfg when you configured your Duo Authentication Proxy server.
  • Plain - Performs basic authentication. This option provides the widest compatibility and is the default selected option. Ensure you have specified the username and password used to connect to your LDAP server in the authproxy.cfg when you configured your Duo Authentication Proxy server. We recommend using secure LDAPS or STARTTLS to protect sensitive credentials if you select this option.

Transport Type

The transport type selected determines how the connection between the Duo Authentication Proxy software and the LDAP 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. One of:

    Clear - LDAP communication between your LDAP server and the Authentication Proxy will not be encrypted. If you selected **Plain** authentication for this directory, please avoid CLEAR and switch to a secure transport type to protect your LDAP server lookup credentials.
  • LDAPS - Encrypts LDAP communication using SSL over a dedicated secure port distinct from the port used for unsecured transport.
  • STARTTLS - Opens an unencrypted connection on the unsecured LDAP port then secures the connection with TLS.

Selecting LDAPS or STARTTLS exposes additional settings:

    SSL verify hostname - Requires that the LDAP server'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 OpenLDAP directory server's 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 dc1.acme.corp, and you then enable this option, the connection between your Authentication Proxy and your LDAP server fails with the message "The directory server credentials were rejected" because the IP address of the LDAP server is not present in the certificate it uses for SSL.
  • SSL CA Certs - In order to secure LDAP connections to your LDAP server using LDAPS or STARTTLS protocols, you'll need the PEM formatted certificate from the certificate authority (CA) that issued your LDAP server's SSL certificate.

    Open the issuing CA certificate in a text editor. Copy the file contents (including the BEGIN and END wrapper) and paste into the **SSL CA certs** field on your OpenLDAP sync configuration page. You may need to export all the certs in the CA (such as root CA and intermediate CA) in the certification path and paste them all into this page. It is not required that you provide the actual certificate issued to the LDAP directory server, unless it is using a self-signed certificate (where the cert is issued to and issued by the same host).

    If you do use a self-signed certificate to secure LDAPS communications to your directory server, the certificate's key usage must include "Certificate Signing".

Click Save Directory 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 in the Directory Sync section will show as Connected.

OpenLDAP Sync Connected Status

Continue configuring the directory sync by updating the Synced Attributes.

Synced Attributes

No default source attributes are defined for OpenLDAP sync. You'll need to specify the source attributes from your LDAP directory for these Duo user properties:


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

Username Aliases

Specify up to eight directory attributes to import as additional usernames for each Duo user by clicking Add a username alias attribute, choosing which alias number to define, and entering the desired source attribute from your directory.

For example, if the Username source attribute is uid and Username alias 1 is set to mail, then the resulting Duo user may log in with either username format while consuming a single Duo user license.

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

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

Default: No aliases imported. Aliases may be defined manually from the Admin Panel or programmatically via Admin API on a per-user basis.

Full Name

Required. The user's name.


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

Import notes

Enable this option if you want Directory Sync to import notes information for your users.


Populate the "Notes" field for a Duo user with information from the specified OpenLDAP directory attribute.

Only configurable if Import notes is selected.

Import phones

Enable this option if you want Directory Sync to create phones for your users. Imported devices default to the "Generic Smartphone" platform.

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

Default: Import no phone information from OpenLDAP.

Primary phone

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

To import a landline with an extension, append x and the extension to the number stored in the source directory; +7345559876x123 when imported creates a landline with phone number 734-555-9876 and extension 123.

Only configurable if Import phones is selected.

Secondary phone

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

To import a landline with an extension, append x and the extension to the number stored in the source directory; +7345559876x123 when imported creates a landline with phone number 734-555-9876 and extension 123.

Only configurable if Import phones is selected.

Click the Save Directory button and proceed to group selection.

Selected Groups

Do not configure the same selected groups from your source directory in multiple Duo directory syncs. Each sync process may update the group memberships for a given user with undesirable effects on your configured custom application group policies, permitted groups restrictions, or administrative unit assignments.

Click in the Selected Groups box and start typing an OpenLDAP 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 DN (like CN=Duo-Users,OU=Groups,DC=domain,DC=local) to locate it.

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

Once you see your intended group (or a list of groups), click to select the desired group or groups to sync, then click Save Directory once 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 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 LDAP 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 OpenLDAP directory 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.

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 OpenLDAP 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

Click Save Directory to complete the new OpenLDAP setup in Duo.

Configured LDAP Directory Sync

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

Perform a Sync

Full Synchronization

The directory page shows the status as Connected once all directory configuration steps have been completed successfully. You'll also see options to Sync directory and Sync individual users.

Directory Sync Actions

Click Sync Now to run your first sync and immediately import all members of your selected OpenLDAP groups into Duo.

Directory Sync in Progress

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

Directory Sync Complete

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

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

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, or Help Desk.

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

To sync individual users:

  1. Navigate to the directory's details page in the Duo Admin Panel.

  2. Type up to 50 OpenLDAP user names as a comma-separated list into the Sync individual users text box found in the "Directory Sync" section on the directory's properties page. 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 as a "Selected Group" in your directory'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.

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

    Sync Specified Individual Users

When initiated, the individual user sync verifies that 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) and modify group memberships.

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.

Sync Single User

Individual User Sync using Admin API

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

User Enrollment and Activation

After adding new users to Duo through OpenLDAP 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.

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 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 users, as long as they remain a member of a synced group and the sync configuration still has the "Enrollment Email" option enabled.

Pending Enrollments

Managing Synced Users

Updating Synced User Information

User attributes synced from an external directory cannot be edited in Duo via the Admin Panel, Admin API, or CSV import. This always applies to the required attributes username, full name, email address, plus phone numbers (if you chose to import phones), and group memberships. Changes to these user attributes should be made in the external directory and then synced over to Duo.

You may edit Duo user properties that aren't synced from OpenLDAP via the Admin Panel, Admin API, or CSV import, including those that correspond with optional OpenLDAP sync attributes you chose not to import. However, if you update your OpenLDAP sync to begin importing values for a previously unconfigured optional attribute, the sync will overwrite any previously configured values with the information imported from OpenLDAP.


  • You do not enable import of or specify a source attribute for Notes when you create your OpenLDAP directory sync. The sync imports the username, email, and name from OpenLDAP, 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 Azure, 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 OpenLDAP 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 LDAP, 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

Duo does not import enabled/disabled status from OpenLDAP directories. Administrators may update an OpenLDAP user's status to "Disabled" from the Duo Admin Panel or Admin API.

You may disable a group of synced users by changing the status of that group to Disabled. This prevents any user who is a member of that group from logging in with Duo, regardless of that individual user's status. See the Using Groups and Group Status Administration documentation for more information.

Deleting Synced Users

You may not delete a synced user from Duo as long as directory sync is actively managing that user. If a synced directory user is removed from all external directory groups that sync to Duo (or if the user account is deleted from the source directory), the user 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.

Users in Trash Pending Deletion

If the user marked for deletion is not reconnected to an external directory account via the sync within seven days the user is automatically deleted from Duo. The user's properties show the target date for deletion. A Duo admin can manually delete a synced user from the Trash via the Permanently Delete link at any time during those seven days.

User in Trash

Managing 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 OpenLDAP sync are identified as such in the Admin Panel and Admin API output. When viewing groups in the Admin Panel, you'll see from OpenLDAP 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.

Group Managed by OpenLDAP Sync

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 Azure 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 OpenLDAP Sync "name of sync" to Group name (formerly from "name of sync").

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 OpenLDAP 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. In the Duo Admin Panel, navigate to UsersDirectory Sync and click the OpenLDAP Directory tab.

  2. Click on the directory for which you want to pause or resume scheduled syncs to view its configuration page.

  3. Click the Pause Scheduled Syncs or Resume Scheduled Syncs button 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 OpenLDAP 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 OpenLDAP 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 Scheduled Syncs button in the Directory Sync "Status" section.

Deleting Synced Directories

Deleting a directory 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.

To delete a synced directory:

  1. In the Duo Admin Panel, navigate to UsersDirectory Sync and click the OpenLDAP Directory tab.

  2. Click on the directory you want to delete to view its configuration page.

  3. Click the Delete Directory link at the top-right and confirm that you want to delete that directory.

Frequently Asked Questions

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


Need some help? Take a look at the OpenLDAP Sync Frequently Asked Questions (FAQ) page or try searching our OpenLDAP 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 Full 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 OpenLDAP over LDAP, LDAPS, or STARTTLS.
  2. Duo Authentication Proxy contacts Duo's service over HTTPS/443 to complete user and group synchronization.