How Argo CD signs in against LDAP or Active Directory through Dex
When your organization has a directory but no OIDC provider, the supported path for Argo CD sign-in is the bundled Dex LDAP connector. Argo CD does not talk to LDAP or Active Directory on its own. Its bundled Dex component performs the directory work, and Argo CD receives the result as an OIDC-style login. The Argo CD user management documentation lists LDAP among the Dex connector types alongside SAML, GitHub and OIDC, so this is an officially documented route rather than a workaround.
The connector handles the authentication step: it binds to the directory with a service account, searches for the user, and checks the password against the directory. It can also query group membership so that group names can be matched to Argo CD RBAC roles. It does not provide single sign-on across other applications, does not manage users or groups in the directory, and does not replace a federation layer such as AD FS if you need SaaS sign-in. Because Dex sits between Argo CD and the directory, you are also running a second component with its own configuration, upgrades and logs that your team must own.
Before you build, confirm three things with your directory team: which service account Dex will bind with and what read rights it needs, whether group membership is stored on user objects or only on group objects, and whether the directory can be reached over TLS from the cluster. Ask whether the directory offers a supported integration path to an identity provider. If it does, that path often gives you a cleaner OIDC integration with Argo CD, and the rest of this section explains what the Dex route costs you in return.
What you need before configuring the LDAP connector
Most failed LDAP connections trace back to a missing prerequisite rather than a wrong setting. Confirm the Argo CD version and its bundled Dex, the bind account, network path, certificate chain and directory group model before you edit any connector configuration.
Argo CD version and bundled Dex
Confirm which Argo CD release you run, because the bundled Dex version and the RBAC claim behavior change between releases. Argo CD 3.0 changed Dex-based RBAC to use the federated_claims.user_id claim, so a configuration copied from older guides can silently map no groups. Check the upgrade notes for your starting version, and plan the connector change as a separate step from any Argo CD upgrade.
Dedicated read-only bind account
Create a service account that Dex uses only to bind and search the directory. Give it read access to the user and group containers it needs and nothing more, and store its password in the cluster as a Secret rather than in plain configuration. Confirm with your directory team whether the account can be locked out, expired or disabled by a password policy, because a silent expiry looks like a login outage.
Network path from Dex to the directory
The Dex pod must reach every domain controller or LDAP server it will be configured to use, on the port you choose. Test from inside the cluster, not from a workstation, since network policies, egress rules and firewalls often differ between the two. Ask the network team which controllers are reachable from the Argo CD namespace and whether a load balancer or DNS name fronts them.
CA certificate for TLS to the directory
Plan to validate the directory certificate against your internal certificate authority rather than disabling verification. Obtain the full chain, including any intermediate certificates, and confirm that the names in the certificate match the hostnames Dex connects to. Certificate rotation on domain controllers or LDAP servers is a recurring task, so record who owns it and how Dex receives the updated CA.
Directory schema and user attributes
Confirm the schema your directory uses, since Active Directory and OpenLDAP expose users and groups with different object classes and attribute names. Identify which attribute carries the login name, which carries the email address, and whether the group membership is stored on the group or on the user. Mismatches here produce logins that succeed with no groups attached.
Group model that drives RBAC
Decide which groups will grant Argo CD roles before you configure anything. Confirm whether groups are nested, whether users belong to groups through primary group membership, and who owns group membership changes. Groups that exist only in a spreadsheet or are inherited through several levels of nesting are the most common reason a role mapping does not take effect.
Configuring the Dex LDAP connector step by step
This sequence takes you from a directory bind account to a verified Argo CD login in which directory groups resolve to RBAC roles. Each step ends with a check you can run before moving on, so a failure is isolated to one layer.
Create the bind account and store its credential
Ask your directory team for a read-only service account that Dex can use to bind and search. Confirm the account can read the user and group objects under the search bases you plan to use, and that it has no write rights. Store the bind password in a Kubernetes Secret in the Argo CD namespace, never in a values file or in Git. Check that the Secret exists and that the Dex pod can read it by reviewing the pod's environment or mounted reference after the next rollout.
Configure the LDAP connector in Dex
In the Argo CD configuration, add an LDAP connector under the bundled Dex settings. Set the directory host and port, the bind DN and a reference to the Secret holding its password, the user search base and filter, and the attribute mapping that supplies the username, email and user ID. Keep the user ID attribute stable, because later RBAC rules depend on it. Apply the change and confirm Dex starts without connector errors in its logs.
Verify TLS to the directory before testing logins
Connect to the directory over LDAPS or StartTLS and confirm the server certificate chains to a CA that you add to Dex as a trusted root. Do not disable certificate verification to get a connection working, because the bind password travels on that channel. Confirm the hostname in the certificate matches the host you configured. The check is a successful TLS handshake from the Dex pod using the same host and CA settings.
Test the bind and user search
Use a directory client from the Dex network location to run the same bind DN and user search that the connector will run. Confirm the bind succeeds and that your test user is returned by the search filter, with the expected username and email attributes. If the search returns nothing, correct the search base or filter before changing anything in Argo CD. The check is one test user returned with every attribute Argo CD depends on.
Add the group search for RBAC
Configure the connector's group search so Dex collects the groups each user belongs to, and map them into the groups claim that Argo CD reads. Define the group search base, the filter that matches membership (for example by member or memberOf attributes, as your directory stores them), and the attribute that supplies the group name. Confirm which form of group name your directory returns, because the RBAC policy must match it exactly.
Map directory groups to Argo CD roles
In the Argo CD RBAC policy, bind each directory group to a role or project role using the exact group value confirmed in the previous step. Keep the first mapping narrow, for example one read-only group, so the blast radius of a mistake stays small. Check that the mapping works by confirming that Argo CD shows the expected permissions for a test user after login, and that a user outside the group sees no extra access.
Test a login and inspect the token claims
Sign in to the Argo CD UI as a test user through Dex and complete the LDAP login form. Then check that the groups claim in the token contains the expected directory group, using the Argo CD CLI session or a decoded token from a test session. Verify the user's effective permissions match the mapping. If the group claim is missing, the cause is in the group search; if the login fails before the claim appears, return to the bind or user search checks.
Confirm the admin fallback and remove shortcuts
Before rollout, confirm that at least one directory-backed administrator can sign in and that the built-in admin account is handled as the user management guidance recommends, with admin.enabled set to false once SSO works. Remove any temporary test accounts or permissive mappings used during setup. The check is a documented administrator login path that works without the built-in admin account.
How directory attributes and groups become Argo CD roles
Every Argo CD permission that comes from LDAP or Active Directory depends on two values the directory returns: a stable user identifier and the group membership attached to it. The first decision is which directory attribute Dex uses as the user identifier, because that value becomes the subject Argo CD matches against its RBAC policy. Choose an attribute that does not change when a person's display name or email address changes, such as a unique account identifier, and confirm with your directory team that it is populated for every account that will sign in. Then decide how group membership is returned: through the connector's group search, which queries the directory for group objects whose members include the user, and which group attribute carries the name Argo CD should see. Confirm the exact connector settings for your Dex version against the user management documentation before you write any policy.
Since Argo CD 3.0, Dex-based RBAC reads the federated_claims.user_id claim rather than relying on the older subject value. In practice, this means the identifier Dex places in that claim is what your policy rules must reference, so a rule written against a display name or a mismatched format will silently match nothing. Test this with a single account before you migrate existing rules: sign in, inspect the token claims, and confirm the value in the claim matches the subject in your policy.csv lines. The Argo CD 2.14 to 3.0 upgrade notes cover the change and should be read alongside any existing RBAC you carry forward.
Group names and group DNs must be confirmed against the policy definitions before rollout. Active Directory often returns groups as full distinguished names, while a policy line may expect a short common name, and the two forms do not match. Run a test sign-in for a user in each target group, record the exact group string Argo CD receives, and write the g lines using that string. Also confirm the group scope: a group that is nested inside another group may or may not appear in the returned list depending on how the search is configured, so test a nested membership explicitly. Keep one test account per role so a broken mapping is caught before a production team loses access or an administrator is granted more than intended.
Directory attributes mapped to Argo CD identity and RBAC
This table traces each directory attribute to the Dex LDAP connector setting that reads it and the Argo CD field or policy line that uses it. Use it to confirm your directory's actual attribute names and group layout before you write the connector configuration. Items marked as confirm in your directory are not assumed to match any default.
| Directory item | Dex connector setting | Argo CD use and what to confirm |
|---|---|---|
| User ID (stable identifier) | userIDAttr in the Dex LDAP connector | Dex maps this to the user ID. Confirm which attribute is immutable and unique in your directory, since RBAC in Argo CD 3.0 and later keys on the federated_claims.user_id claim. |
| Username (login name) | usernameAttr in the Dex LDAP connector | Shown as the user name in Argo CD. Confirm whether your users sign in with sAMAccountName, userPrincipalName or another attribute, and whether that value can change. |
| Email address | emailAttr in the Dex LDAP connector | Used for identity and notifications where configured. Confirm that every account that needs access has a populated mail value. |
| Display name | Attribute mapped in the connector, if your Dex version exposes it | Informational only in most setups. Confirm the attribute name in your schema before relying on it in any audit report. |
| Group membership | groupSearch settings (base DN, filter, user and group attributes) in the Dex LDAP connector | Group names or IDs returned here feed the scopes setting and the g lines in policy.csv. Confirm whether your groups are returned as distinguished names or short names, because the policy must match the exact value. |
| Nested group membership | Group search filter and recursion behavior in your Dex version | Confirm whether a user in a child group inherits the parent group's Argo CD role. Test with a nested account before rollout, because the docs do not establish this for every directory. |
| Group count per user | Size of the token returned to Argo CD | Confirm how many groups each user belongs to. Large group sets can grow tokens and affect sessions, so test with your most-grouped accounts. |
| Account state (disabled or locked) | Filter applied in the user search | Confirm that disabled accounts are excluded by the user search filter, since a disabled directory account should not keep Argo CD access. |
Hardening the directory bind and TLS path
An LDAP or Active Directory connector gives Dex a standing credential into your directory and gives Argo CD a sign-in path that bypasses your normal identity controls. The cards below cover the bind account, the TLS trust chain, where the bind password lives, and how to remove the local admin and API surfaces once SSO works.
Scope the bind account to read
Dex uses a bind account to search the directory for the user and, when group RBAC is configured, for the groups the user belongs to. Create a dedicated service account with read access only to the user and group containers it needs, and no write rights or membership in privileged groups. Ask your directory team to confirm the account cannot modify users, groups or password attributes, and that its password expiry and lockout policy match how Dex will reconnect.
Verify the directory certificate chain
Configure Dex to connect to the directory over TLS and validate the server certificate against your internal certificate authority. Disabling verification or trusting any certificate exposes the bind password and user credentials on the network path. Check that the certificate name matches the host name in the connector configuration, and that the CA bundle is mounted into Dex so the chain validates after pod restarts.
Keep the bind password in a Secret
The bind password belongs in a Kubernetes Secret referenced by Dex, not in the argocd-cm ConfigMap or in Git. Restrict read access to that Secret with RBAC on the Argo CD namespace, and confirm that your GitOps repository holds only a reference to it. Plan a rotation procedure that updates the Secret and restarts Dex, because a rotated password that is not propagated will stop all directory sign-ins at once.
Control who can change RBAC
Argo CD roles live in policy configuration, and anyone who can edit that configuration or the repository it is synced from can grant themselves admin rights. Limit write access to the Argo CD configuration repository and its protected branches, and require review for changes to group mappings. The repo-server runs Helm and Kustomize on repository content, so treat any repository that can alter RBAC or the Argo CD project definitions as a privileged path.
Disable the built-in admin user
The built-in admin account is intended for initial setup. After directory sign-in and at least one tested administrator group work, set admin.enabled to false so the local password cannot be used. Keep a documented break-glass procedure that another administrator can run, and confirm it before disabling the account, since recovering access later is harder than planning it now.
Treat JWT as the only API method
Argo CD authenticates API requests only with JSON Web Tokens, so directory sign-in is the entry point for people and automation tokens are issued from the same configuration. Review which accounts can generate tokens and how long they live, and revoke tokens tied to departed staff. Confirm that the directory account used for sign-in is disabled when a person leaves, because existing sessions and tokens are the remaining access path.
Why LDAP logins and group roles fail
This table maps the failures teams most often hit when Argo CD signs users in through the Dex LDAP connector, with the likely cause, the check to run and the fix direction for each. Work down the rows in order, because a bind or TLS problem hides every symptom that comes after it.
| Failure | Likely cause | Check to run | Fix direction |
|---|---|---|---|
| Bind failure at login | Bind DN, bind password or the service account lacks read access to the user subtree | Confirm the bind DN and password in the Dex connector config, then bind with a standard LDAP client from the Dex pod network | Correct the bind account or its permissions, and store the bind password in a Kubernetes Secret rather than plain config |
| Certificate or TLS error | Directory certificate is not signed by a CA Dex trusts, or the hostname does not match the certificate | Test the TLS handshake from the Dex pod and compare the certificate subject and chain with the configured host | Add the issuing CA to Dex's trust store, and use the directory hostname that appears on its certificate |
| User not found | User search base is too narrow, the user filter does not match the account type, or the login attribute is wrong | Run the same search filter and base with an LDAP client as the bind account and compare the result | Widen the base to the subtree that holds users, adjust the filter and align the username attribute with what users type |
| Groups missing from the token | Group search is not configured, the group filter or user attribute does not match how membership is stored, or nested groups are not expanded | Inspect the group membership on the test user and check whether membership is stored on the user or the group object | Set the group search base, filter and user matching attribute to match the directory schema, then sign out and sign in again |
| Roles not applied after a policy change | Old session still carries the previous claims, or policy.csv uses a group name that does not match the value Dex sends | Compare the group value in the token with the g line in policy.csv and check the role's permissions | Correct the group string, apply the policy and have the user sign in again so new claims are issued |
| Admin access lost after SSO setup | The built-in admin account was disabled before an SSO role was verified, or no group maps to an administrator role | Confirm which accounts can still sign in and which group holds the admin role in policy.csv | Re-enable admin temporarily through the supported recovery path, fix the mapping, then disable admin again |
| Login works but users see no applications | Project roles or policy lines grant nothing for the mapped group, or the default policy is too restrictive | Test the role with a user in that group and review the project's role bindings | Add explicit project-scoped permissions for the group and confirm the change in a test project first |
When to front Active Directory with an IdP instead
If your on-premises Active Directory already syncs to Microsoft Entra ID through Microsoft Entra Connect, you have an identity provider in place. Microsoft describes Entra Connect as the sync path for existing Active Directory organizations, so the users and groups Argo CD needs may already be available to an OIDC login. Connecting Argo CD to Entra ID keeps the cluster off the LDAP bind path and moves sign-in controls to the place where your users already authenticate. The trade-off is that group information arrives as a token claim, so group volume and claim shape need checking before you write any RBAC.
- Sign-in policy in one place: Password, device and location rules are enforced where users already sign in.
- No directory bind from the cluster: Argo CD does not need a service account bound to Active Directory.
- Group claim design: Confirm how many groups a user receives and whether role mappings will use group IDs or names.
- Sync scope: Entra Connect only carries what it syncs, so confirm that the Argo CD users and groups are in scope.
- Ownership: Confirm who operates the sync service and who approves changes to group membership.
Check the sync scope and group claim design before choosing this path, then read the sibling Argo CD SSO with Microsoft Entra ID page as the next step.
When the directory is OpenLDAP or FreeIPA and no Windows domain is involved, direct LDAP through Dex is often the simpler path, but the directory then becomes a dependency of Argo CD sign-in. OpenLDAP 2.7 includes slapd, a stand-alone LDAP directory server, and slapd supports replication for environments where a single point of failure is not acceptable. FreeIPA is a Linux identity platform that uses Kerberos, and its Active Directory trust guide covers Active Directory users reaching Linux resources, which is a separate need from signing in to Argo CD.
- Directory availability: If the directory is unavailable, Argo CD sign-in fails, so plan replicas and test failover.
- TLS trust: Dex must trust the directory certificate chain, so confirm the CA and certificate lifecycle before go-live.
- Group model: Confirm how groups are modeled in the directory and how the group search will read them.
- Operational ownership: Confirm who patches and upgrades the directory, since OpenLDAP 2.7 retired some backends and deprecated the GnuTLS integration.
- Cross-forest trust: Set up a trust only when Active Directory users also need Linux resources.
Confirm which directory is the source of truth and who operates it before you write bind settings or search filters.
A direct LDAP connector checks a username and password against the directory. Multi-factor authentication and conditional access policies are usually enforced by an identity provider in front of the application, so a direct LDAP path may not give you those controls. Do not assume the Dex LDAP connector supports second factors. Confirm how the connector and your directory stack handle them, and confirm the same for any device or location checks your security policy requires. The Argo CD user management documentation lists OIDC providers as a direct option, which is where these controls are normally configured.
- Second factor scope: Ask whether your directory stack provides MFA for LDAP binds at all.
- Conditional access: Device compliance, location and risk checks typically live in an identity provider, not in a directory bind.
- Session lifetime: Token expiry depends on Argo CD and provider settings, so test how long a session lasts after sign-out or a policy change.
- Break-glass access: The user management documentation recommends disabling the built-in admin user once SSO works, so plan the recovery path first.
- Audit evidence: Ask which system records each sign-in and MFA event for your auditors.
Write down which controls must apply to Argo CD sign-in and test each one on the chosen path before cutover.
If you already run an OIDC provider such as Keycloak, the usual answer is to connect Argo CD to that provider directly and keep the directory behind it. The Argo CD user management documentation lists Keycloak among the OIDC providers Argo CD can use directly, and Dex is needed mainly when no OIDC provider exists. Federating the directory into the provider keeps one set of decisions for groups, multi-factor and account lifecycle, and your Argo CD configuration stays focused on claim mapping. Federation adds a hop, so group changes and disabled accounts take effect only after each link in the chain has synced.
- Single policy point: Groups, MFA and lifecycle decisions sit in the provider.
- Fewer moving parts: No LDAP bind account, search base or Dex connector to maintain on the Argo CD side.
- Token claims: Confirm the provider emits a groups claim and the exact name of that claim.
- Federation chain: Test a group change and an account disablement end to end, because delays come from each hop.
- Fallback path: Keep the direct LDAP option documented in case the provider is unavailable during an incident.
Confirm that the provider can send the group claim you need, then read the sibling pages on mapping identity provider groups to Argo CD RBAC roles.
What Active Directory and Entra ID mean for Argo CD sign-in
Before you configure the Dex LDAP connector, confirm what kind of directory you actually have. Active Directory Domain Services is a Windows Server role that stores users, computers and other objects, and it replicates that data to every domain controller in a domain. Microsoft's comparison says most on-premises applications authenticate against Active Directory using LDAP, Windows-integrated authentication (NTLM and Kerberos) or header-based authentication. Argo CD's Dex connector uses the LDAP path, so the directory must answer LDAP queries from the Dex pod's network segment. Ask your directory team which domain controllers or load-balanced LDAP endpoints Dex should use, and whether they accept LDAPS connections with certificates your cluster can trust.
Many Active Directory organizations also sync identities to Microsoft Entra ID with Microsoft Entra Connect, and Microsoft describes Entra ID as the cloud evolution of Active Directory. Microsoft notes that Active Directory needs a federation system such as AD FS to supply SaaS applications, so a directory that only speaks LDAP does not give Argo CD a modern sign-in path on its own. If your organization already runs Entra ID for SaaS sign-in, a direct OIDC connection from Argo CD to Entra ID is often easier to operate than maintaining LDAP bind accounts and TLS trust in the cluster. Check whether Entra ID is the authoritative source for the groups you plan to map to Argo CD roles, because the group source determines which connector you configure. Confirm the current Entra ID group claim behavior with Microsoft before you commit to a design.
Questions buyers ask about LDAP and Active Directory with Argo CD
What drives the cost of connecting Argo CD to LDAP or Active Directory?
The main cost drivers are the shape of the directory and the number of groups Argo CD must map to roles. A single forest with clean group membership and one bind account is a small job. Multiple domains, nested groups, several directories, or groups that feed many Argo CD projects add design, testing and documentation work. Any quote should break out the directory review, the Dex configuration, the RBAC mapping, TLS setup for the directory, and testing with real test accounts. Ask whether the price covers one environment or each of your staging and production clusters, and whether follow-up changes to group mappings are included.
How long does an LDAP or Active Directory integration with Argo CD take?
Duration depends on how quickly your directory team can provide a bind account, a reachable LDAP endpoint, a CA certificate for TLS, and a clear list of the groups that should map to Argo CD roles. Those inputs often take longer than the Argo CD configuration itself. Ask the partner to state the timeline in the written scope, along with the dependencies it assumes from your side and which milestones depend on directory team responses.
What does the directory team need to provide for this work?
The directory team usually provides a read-only bind account with a defined password policy, the LDAP or LDAPS host names and ports, the base distinguished names for users and groups, and the attribute names used for login and group membership. They also need to confirm which certificate authority signs the directory certificate so Dex can verify the connection. If Active Directory is in use, confirm whether the group search should use the member or memberOf attribute, and whether nested group expansion is needed. Confirm each item with your directory administrators before work starts.
Can our own team set up Argo CD with LDAP or Active Directory in-house?
Yes, a team that already runs Argo CD and understands its RBAC model can usually complete the work without outside help, provided it has directory administrators who can supply accurate settings. The harder parts are testing group search against real accounts, keeping the bind credentials out of Git, and verifying that a user in a nested group gets the intended role. Teams without Argo CD operations experience, or without a test directory, often find the verification steps take the most time. A partner engagement can be scoped to design and review only, or to full implementation.
Does the quote include Active Directory or Windows Server licensing?
Licensing is normally a separate cost and is outside an Argo CD integration unless the written scope says otherwise. Microsoft's Windows Server 2025 pricing page states that Standard and Datacenter editions are licensed per core, with a minimum of 16 cores per server and 8 per processor, and that Client Access Licenses are needed for each user or device that accesses the server. The same page says prices vary by region. Existing Active Directory domain controllers are already in your estate, so the question is whether any new directory servers are planned. Ask the partner to state explicitly whether licensing is excluded, and confirm your current licensing position with Microsoft or your reseller.
Should we connect Argo CD to our directory directly or front it with an identity provider?
Direct LDAP through Dex works when no OIDC provider exists and the directory is the only source of identity. If you already run an identity provider, or plan to, connecting Argo CD to that provider over OIDC usually simplifies group handling and keeps Argo CD from holding directory bind credentials. Microsoft's comparison notes that on-premises Active Directory is commonly used with LDAP, Windows-integrated authentication or header-based authentication, and that SaaS applications typically need a federation system such as AD FS. Discuss this choice with your security team before the design is fixed, because it affects who owns the bind account and how offboarding is enforced.
How do Dex and Argo CD upgrades affect an LDAP connection?
Dex ships inside Argo CD, so each Argo CD upgrade can change how the connector and RBAC behave. The Argo CD 2.14 to 3.0 upgrade notes state that Dex-based RBAC now uses the federated_claims.user_id claim, so group mappings written for earlier releases need review before the upgrade. Plan a test run against a non-production cluster, keep the connector configuration in version control, and record which Argo CD minor version the mapping was tested against. Ask the partner how upgrade testing is scoped and whether it is part of the fixed price or a separate retainer.
How DeployOpen scopes and delivers Argo CD directory sign-in
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For Argo CD with LDAP or Active Directory through Dex, we start from your directory layout, group model and TLS requirements, then deliver a configured, tested and documented sign-in path that your team can operate after handover.
How we scope
- Written scope lists the directory type, bind account, search bases and the group attributes Argo CD roles will use.
- We confirm whether Dex LDAP is the right path or whether an existing identity provider should front the directory first.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before any work starts.
How we build
- We configure the Dex LDAP connector, bind settings and TLS to the directory in your own cluster.
- We map directory groups to Argo CD roles and test each mapping with real accounts before rollout.
- We verify failure cases such as expired bind credentials, unreachable domain controllers and disabled accounts.
How we hand over
- You receive the configuration, group-to-role mapping, test results and a runbook for the sign-in path.
- We document how to disable the built-in admin user once directory sign-in is confirmed working.
- Your team walks through troubleshooting steps for login failures, group sync issues and certificate renewal.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Upgrade planning covers Argo CD minor releases and any changes to Dex connector settings.
- Ask for a quote built from the written scope, covering one-time build work and any recurring support.
