Duo Directory Sync Guide: One-Way AD to Duo Provisioning

Duo Directory Sync delivers a practical, one-way bridge from on-premises Active Directory into Duo by importing users, phones, groups and administrators via the Duo Authentication Proxy — but getting it right requires careful attention to authentication, transport security, proxy placement, attribute mapping and sync ownership rules to avoid surprises in production.

Background / Overview​

Duo’s Directory Sync lets organizations import end-users and administrators from Active Directory (AD) or AD LDS into Duo using the on-premises Duo Authentication Proxy as the connector. The operation is one-way: Duo imports attributes from AD, but does not write anything back. Scheduled full user syncs run twice a day by default while admin syncs run every 30 minutes; both can also be started on-demand from the Duo Admin Panel or programmatically via the Admin API.
This article walks through prerequisites, installation and configuration of the Authentication Proxy, mapping attributes and groups, admin sync specifics, enrollment behavior, security hardening, common pitfalls, troubleshooting guidance and best-practice checklists for production roll‑outs.

---

Why this matters: the value and the risks​

Duo Directory Sync reduces manual administration and enforces consistent user and admin provisioning into Duo. Benefits include:

• Fast onboarding of large user populations via group-based imports.
• Centralized management based on authoritative AD attributes (email, displayName, phone).
• Role mapping for administrators using AD groups to assign Duo roles.

But the integration also introduces operational and security risks if misconfigured:

• Sync ownership and overwrite risk: existing Duo users or admins that match AD usernames or email addresses can be taken over by a sync and have Duo fields overwritten. Plan carefully before enabling a full sync.
• Certificate and transport strictness: LDAPS / STARTTLS certificates must meet modern crypto requirements (SHA256+ and 2048-bit key). Failure to meet these requirements will break secure LDAP connections.
• Proxy placement: installing the Authentication Proxy on DCs or role-conflicting hosts (e.g., NPS) can cause port conflicts or security issues. Use a dedicated host or VM where possible.

---

Prerequisites (what to prepare before you start)​

Before you create a Duo AD Sync, collect and verify the following:

• The AD domain controller hostname(s) or IP and LDAP/LDAPS port(s) to use (389 for LDAP/STARTTLS, 636 for LDAPS). Hostnames must be RFC-1034‑compliant (letters, digits, hyphen).
• The directory Base DN that sits above the users and groups you want to sync (example: DC=domain,DC=local).
• Duo Admin role: you need Owner, Administrator or User Manager to configure user sync; admin sync setup and management requires the Owner role.
• A machine (Windows 2016+ or modern Linux like Ubuntu 20.04+/RHEL/CentOS) for the Duo Authentication Proxy. If using Integrated (SSPI) authentication, the proxy must be a domain‑joined Windows 2016+ server.
• Ensure outbound HTTPS (TCP 443) to Duo is allowed; IP‑based allowlists are discouraged because Duo's public IP ranges may change.
• Cryptography: Duo no longer supports TLS 1.0/1.1; ensure your environment negotiates TLS 1.2+ and avoids weak ciphers. Duo’s guidance requires modern TLS and ciphers (effective June 30, 2023).

Security note: Duo Authentication Proxy v6.4.0+ requires LDAPS/STARTTLS certificates signed with SHA256 or stronger and a public key length of at least 2048 bits. If your DCs are using SHA1 certs, reissue them with SHA256 or use CLEAR transport temporarily (not recommended for production).

---

Installing the Duo Authentication Proxy​

The Authentication Proxy is the on-prem connector that performs LDAP lookups and runs the sync agent. Key points:

• Supported OS: Windows Server 2016 or later; CentOS/RHEL, CentOS Stream, Fedora, Ubuntu LTS, Debian — consult Duo release notes for exact supported versions.
• Minimum recommended host sizing: 1 CPU, 200 MB disk, 4 GB RAM recommended (1 GB often sufficient). Avoid installing the proxy on domain controllers or NPS servers to prevent port conflicts.
• Windows installer includes the Duo Authentication Proxy Manager (optional) that helps edit authproxy.cfg, validate configuration and start/stop the service. There is no Proxy Manager for Linux.

Installation summary (high-level):

• Download the latest Windows or Unix package from Duo (the actual filename will reflect the version).
• Run the installer with admin/root rights.
• On Linux build/install flows, you may need build tools (gcc, make, libffi-devel, zlib-devel) and, if SELinux is present, selinux-policy-devel and chkconfig to build the SELinux module.

---

Configuring authproxy.cfg: the [cloud] section and secrets​

After installation, Duo provides a pre-configured authproxy.cfg snippet to paste into your proxy's config. The connection section appears as:

• ikey — integration key for the Directory Sync connection.
• skey or skey_protected — secret key (use protected form when possible).
• api_host — Duo API hostname (api-XXXXXXXX.duosecurity.com).
• For NTLMv2 or Plain authentication: service_account_username and service_account_password (or service_account_password_protected).

Encryption of secrets on Windows:

• Use authproxy_passwd.exe in the proxy bin folder to encrypt service_account_password and skey. The encrypted values are machine‑specific — run the tool on each proxy host that needs the encrypted secret. On Linux there is no built‑in secret encryption tool; secure the config file by OS-level protections.

Practical notes:

• If you add multiple [cloud] sections for multiple syncs on the same proxy, increment them as [cloud2], [cloud3], etc., when using proxy v5.2.0+. All syncs that share an api_host must belong to the same Duo customer account.

---

Directory configuration in the Duo Admin Panel​

After the proxy is reachable and the authproxy.cfg section is in place, configure the directory in the Duo Admin Panel:

• Enter domain controller IP/host and port. You can add fallback DCs (up to five total in the UI).
• Set the Base DN to include all users and groups you plan to import (example: DC=corp,DC=local).
• Choose Authentication Type:
• Integrated (SSPI) — requires a domain‑joined Windows proxy; no service account credential in authproxy.cfg required.
• NTLMv2 — requires service account credentials in authproxy.cfg and NTLM domain/workstation fields in the Admin Panel.
• Plain — basic bind; strongly prefer LDAPS or STARTTLS to protect the bind credentials.
• Transport Type: CLEAR, LDAPS, or STARTTLS. When using LDAPS or STARTTLS, supply the CA certificate chain in PEM format if the DC uses a non-public or private CA. If you enable “SSL verify hostname” make sure the hostnames match the certificate CN/SAN.

Security tip: Preference should be LDAPS or STARTTLS with certificate validation enabled; only use CLEAR in isolated test environments.

---

Groups, mappings and attribute sync​

Groups

• Select up to 400 groups to sync (members of those groups become Duo users). Nested AD groups are supported — Duo imports members of nested groups into the top-level Duo group. Do not configure the same AD group in multiple Duo directory syncs; ownership conflicts will occur.

Attributes

• You must choose a Username source attribute (default sAMAccountName). This attribute becomes the primary login identifier and cannot be changed after the first sync runs. Username alias attributes (up to eight) are supported and can be changed after initial sync.
• Required fields imported: Username, Display Name, Email Address. You can add extra attributes (phone numbers, notes) via the Synced Attributes UI. Duo does not import passwords from AD.

Enrollment and phones

• If you enable Import Phones, Duo creates phone objects (default platform: Generic Smartphone) for synced users. Directory sync will not send SMS activation to imported phones. If you also enable Enrollment Email, users without phone entries will receive an emailed enrollment link. Enrollment links expire after 30 days; Duo will resend reminders (at 2 and 8 days) during that period.

Admin sync specifics

• Admin Directory Sync maps AD groups to Duo admin roles. Select which AD groups correspond to which Duo roles (Help Desk, Administrator, Read-only, etc.). If an admin is in multiple role-mapped groups, the highest‑precedence role is applied. You cannot create or modify Owner role assignments via admin sync. Admin sync runs every ~30 minutes automatically.

---

Ownership, conflicts and lifecycle behavior — what to watch for​

Ownership

• The sync that creates a user or admin becomes the owner for that object in Duo. If the same username/email exists in multiple directories, only the first sync that created the object manages it; later syncs encounter a “belongs to another sync” error for that record. If you need to migrate ownership, pause the managing sync or remove the user from the old sync groups and let the new sync create the user.

Disabled and deleted users

• Duo does not allow manual disabling of synced users; the user’s AD account status is authoritative. If the AD account is disabled (userAccountControl set to 514), Duo will mark the user as Disabled on next sync (user remains read-only). If a user is removed from all synced groups they become “Pending Deletion” and are moved to Trash — they’ll be permanently deleted after 7 days unless re‑added.

Group removals

• Removing a group from a sync’s configuration will mark any users who are not members of other synced groups for deletion. Be cautious when editing group lists.

Attribute immutability

• Synced attributes (username, email, display name, imported phone numbers, and group membership) are read‑only in Duo — updates must be made in AD and re-synced. This prevents drift but means workflows for exceptions must be planned.

---

Operational behaviors and alerts​

Sync frequency

• Full user syncs: twice daily by default (12‑hour interval). Enabling high-frequency sync increases runs to roughly every 30 minutes after a prior sync finishes. Admin syncs: run automatically every ~30 minutes. You can also manually kick off full or individual user/admin syncs from the Admin Panel or Admin API.

Failure notifications and pauses

• Duo emails Owner/Admin/User Manager admins after consecutive sync failures — for user syncs notifications start after three days of failures; for admin syncs notifications begin after one day of failures. After extended failures Duo may pause scheduled syncs (final pause occurs after repeated failures). Resolve the connection issue in the Admin Panel and resume the sync.

Testing

• After configuring the proxy and saving directory settings, use the “Test Connection” and then perform a Sync Now to observe imported counts and confirm attribute mappings. Check the proxy authproxy.log for connectivity or ConfigError traces if the proxy won’t connect.

---

Security hardening checklist​

• Use LDAPS or STARTTLS with certificate validation and provide the issuing CA PEM chain to Duo when certificates are not public CA-signed. Enable SSL hostname verification if your cert CN/SAN matches the hostnames you configured.
• Ensure AD certificates use SHA256 or greater and 2048-bit keys (required by Auth Proxy v6.4.0+). Reissue older SHA1 certs.
• Upgrade Authentication Proxy versions promptly — Duo has called out a CA bundle replacement and a required minimum proxy version (check current Duo guidance and release notes; some actions may be time‑sensitive). The AD Sync doc now includes an action notice for certificate pinning with an expiration in 2026; verify proxy versions and plan upgrades.
• Encrypt skey and bind passwords with authproxy_passwd.exe on Windows and protect authproxy.cfg with strict file ACLs. On Linux, rely on OS file permissions plus host security controls. Remember encrypted secrets are machine‑specific — you must run the encryption tool on each proxy host.
• Block outbound connections only to Duo’s documented service endpoints — avoid static IP allowlists unless you have a process to update them; Duo publishes knowledge base guidance if IP-based rules are required.
• Confirm TLS 1.2+ and modern cipher suites on any client or proxy that communicates with Duo (Duo rejected TLS 1.0/1.1 after June 30, 2023).

---

Common pitfalls and how to avoid them​

• Accidentally taking over existing Duo users: always audit existing Duo usernames/emails and reconcile duplicates before enabling a full sync. Use individual user syncs for initial testing.
• Using CLEAR transport with Plain binds in production: exposes credentials; always prefer LDAPS/STARTTLS.
• Expecting immediate deletions: when a user is removed from all synced groups they go to Trash and are deleted after seven days — plan for that retention window.
• Forgetting encrypted secrets are machine-specific: encrypted skey/passwords won’t work if copied between hosts. Run the Windows encryption utility per host.
• Mixing group definitions across multiple syncs: do not select the same AD group across multiple directory syncs; a saved duplicate takes ownership and removes it from the other sync.

---

Troubleshooting quick guide​

• Proxy not connecting: verify authproxy.cfg cloud section ikey/skey/api_host and restart the proxy. Check authproxy.log and Windows Event Viewer for DuoAuthProxy errors.
• LDAPS handshake errors: confirm DC cert uses SHA256+, 2048-bit key and that your SSL CA certs PEM chain is entered correctly in the Admin Panel. If using self-signed DC certs, ensure key usage includes “Certificate Signing” per Duo’s guidance.
• Sync skips users: ensure the username and alias source attributes are unique across the AD population; duplicate alias values cause those users to be skipped by sync.
• Enrollment emails not delivered: Duo sends enrollment from [email]no-reply@duosecurity.com[/email]. If email filtering is in place, whitelist this sender. Enrollment links are valid 30 days and reminders are sent at day 2 and day 8.

---

Migration and cutover recommendations​

• Start with a staging sync into a test Duo account or a test group to validate attribute mappings, enrollment behavior and phone imports.
• Run individual user syncs for key pilot users (up to 50 usernames at once) before doing a full sync. This exposes mapping errors at a small scale.
• Audit existing Duo accounts for name/email collisions. Plan a remediation or staggered migration if collisions are found — pause the old sync if needed to allow new ownership to take effect.
• If your AD uses SHA1 certs or weak TLS, schedule certificate reissuance and proxy upgrades (ensure Authentication Proxy versions meet Duo’s minimums for CA pinning and TLS/cipher requirements). Duo has announced root CA bundle changes that require proxy upgrades before Feb 2, 2026; verify your proxy versions and patch timeline.

---

Minimal production checklist (ready-to-use)​

• [ ] Inventory AD groups and confirm membership, nested groups and naming uniqueness.
• [ ] Confirm AD certs are SHA256+ with 2048+ key lengths.
• [ ] Provision a dedicated proxy host (Windows domain‑joined if using Integrated auth) and install Duo Authentication Proxy latest stable release.
• [ ] Paste the supplied authproxy.cfg [cloud] section and run authproxy_passwd.exe on Windows hosts to protect secrets (and repeat per proxy host).
• [ ] Configure directory Base DN and DC entries in Duo Admin Panel; add CA PEM chain if required; test connection.
• [ ] Create selected group list (≤ 400), map attributes and confirm username source attribute (irreversible after first sync).
• [ ] Run Sync Now for an initial import, validate imported users, enrollment links, and group membership.
• [ ] Monitor authproxy logs and Duo Admin Panel sync status; configure notifications for sync failure recipients.

---

Final analysis and recommendations​

Duo Directory Sync is a powerful automation feature that reduces administrative overhead and centralizes identity management into Duo when used correctly. The most notable strengths are the granular control over attribute mapping, group‑based imports and administrator role mapping via AD groups. These let enterprises align Duo provisioning with existing AD lifecycle processes and role-based access controls.
The most significant risks come from ownership and overwrite semantics (duplicate usernames or email collisions), cryptographic and transport misconfigurations, and proxy misplacement. These are operational rather than architectural problems and are addressable with a staged rollout, rigorous testing, and adherence to Duo’s crypto and proxy version guidance. Always test with individual user syncs before running a full sync and ensure your Authentication Proxy and AD certificates meet Duo’s modern TLS and certificate requirements.
Cautionary note: Duo has announced a certificate authority pinning bundle change and associated deadlines (including proxy version requirements) that can affect Authentication Proxy connectivity. Confirm your environment’s proxy versions and apply updates as directed by Duo to avoid service disruption. Also note that some encryption tools and behaviors (for example, secret encryption on Windows) are machine‑specific; do not assume encrypted secrets are portable between hosts.
By following the configuration, security hardening checklist and staged migration approach outlined here, organizations can minimize surprises, meet compliance needs and achieve a reliable AD → Duo sync flow that supports enterprise-scale user and admin provisioning.

---

Conclusion: treat Directory Sync as an extension of your identity source, not a replacement — design ownership, lifecycle and emergency plans around the fact that AD is authoritative. With the right planning (certificate and proxy upgrades, careful attribute mapping, and staged testing) Duo Directory Sync will reliably and securely bring your Active Directory users and admin teams into Duo with minimal administrative overhead.

---

Source: Duo Security Synchronizing Users and Admins into Duo from Active Directory | Duo Security