Argo CD SSO with Microsoft Entra ID: Setup Guide

Argo CD SSO with Microsoft Entra ID: what the integration does

Argo CD can sign people in through the Microsoft tenant your company already runs, so access follows the same accounts, multifactor policies and group memberships used elsewhere. The documented options are four: direct OIDC with an app registration that uses a client secret, direct OIDC with workload identity federation, SAML through the bundled Dex, and Dex's microsoft connector. Argo CD's Microsoft guide recommends workload identity federation over client secrets, so a platform team starting from scratch should plan for it first. The client secret path remains documented, but it leaves a long-lived credential to rotate and protect in the cluster.

The trade-off is operational complexity against credential exposure: workload identity federation needs a trust relationship between the Entra app registration and the Kubernetes service account that runs Argo CD, and that setup must be verified before anyone depends on it. Direct OIDC keeps Argo CD talking straight to Entra ID, while the Dex options add a component to run, upgrade and troubleshoot. Confirm with your identity team which of these your tenant policies allow before choosing, since app registration and consent rights vary by organization.

Group claims decide who can do what in Argo CD, so the integration is not complete when sign-in works. Entra ID caps the groups claim at 200 entries, and users above that limit need a different lookup, which the Microsoft guide covers in its own section. Plan the group-to-role mapping alongside the sign-in method, and ask your Entra administrator which groups will be emitted for each user before rollout. Your tenant's data location is fixed at creation, so confirm it matches your residency requirements as part of the same review (Microsoft Entra ID and data residency).

Which Entra ID method fits Argo CD

Argo CD documents four ways to connect Microsoft Entra ID, and they differ in where the trust sits, what secret you manage and how groups reach Argo CD. Use the cards to match the method to your identity team's constraints before you register anything in the tenant.

Direct OIDC with a client secret

Argo CD talks to Entra ID directly as an OIDC client, using an app registration and a client secret stored in the Argo CD configuration. It is the most direct path and the fewest moving parts, which suits a small team that wants Argo CD's own login flow without a bundled Dex. The trade-off is a credential you must rotate and protect. Check who owns the secret, when it expires, and how a rotation is rehearsed before it lapses.

Direct OIDC with workload identity

Argo CD authenticates to Entra ID as the app registration using workload identity federation, so no client secret is stored in the cluster. The Argo CD documentation recommends this over client secrets. It depends on a federated credential configured on the app registration and on the Kubernetes service account trust being set up correctly. Expect more upfront identity work and a platform team that can read federation errors. Confirm the exact setup steps against the current Argo CD Microsoft guide for your version.

SAML through Dex

Argo CD's bundled Dex signs users in to Entra ID over SAML and passes the resulting identity to Argo CD. Choose it when your organization standardizes on SAML for enterprise applications, or when the SAML app already exists. It adds Dex as a component you operate, upgrade and monitor, and group handling depends on the attributes the SAML assertion carries. Verify those attributes in a test sign-in before you write any RBAC rules.

Dex microsoft connector

Dex's microsoft connector uses Entra ID as an upstream identity source, so Argo CD sees the user through Dex rather than a direct OIDC client. It suits teams that already run Dex for other connectors and want one place to map providers. The connector carries the same group limits as any Entra ID token, so the overage behavior still applies to large group memberships. Confirm how the connector handles groups in your Dex version before you plan group-based roles.

How to configure Entra ID sign-in for Argo CD

This sequence takes an Argo CD installation from an unauthenticated admin login to Entra ID sign-in, where group membership in Microsoft Entra ID decides what each person can do in Argo CD. Each step ends with a check you can run before moving on.

Register the application and redirect URI
A directory administrator registers an application in Microsoft Entra ID for Argo CD and adds the Argo CD callback URL as a redirect URI, using the external hostname your users will open in the browser. Record the tenant ID, the application (client) ID, and confirm which sign-in audience the registration uses. The step is done when the registration exists, the redirect URI matches the Argo CD URL exactly, and the people who will sign in belong to that tenant.
Choose client secret or workload identity federation
Decide how Argo CD proves its identity to Entra ID. A client secret is simpler to set up but must be stored, rotated and kept out of Git. Workload identity federation avoids a stored secret and is the method the Argo CD Microsoft guide recommends over client secrets, though it requires a federated credential on the app registration and a cluster setup that your platform team must confirm. The check is a written decision and, if you choose federation, a federated credential that matches the Argo CD service account subject.
Set the OIDC issuer and client settings in Argo CD
Set the url value in the argocd-cm ConfigMap to your Argo CD external URL, and configure the OIDC issuer for your Entra tenant, along with the client ID and, if you use a secret, a reference to the client secret held in a Kubernetes Secret rather than inline text. Apply the change and restart the API server if your version requires it. The check is that the Argo CD login page offers a Microsoft sign-in option and the issuer metadata loads without errors in the Argo CD logs.
Configure the groups claim and token settings
In the app registration, configure the token to include group claims, choosing the group type that matches how your RBAC will refer to groups, such as security group object IDs. Decide whether to use the overage setting for users who belong to more groups than the claim can carry. Enabling overage makes Argo CD call Microsoft Graph, which needs the User.Read delegated permission and a reachable Graph endpoint. The check is a decoded ID token from a test user showing a groups claim with the expected object IDs, or an overage indicator if the user is over the limit.
Bind Entra groups to Argo CD RBAC roles
Map the group object IDs from the token to Argo CD roles by adding entries under policy.csv in the argocd-rbac-cm ConfigMap, and set the scopes value so Argo CD reads the groups claim. Start with a read-only role for a pilot group and a project-scoped role for a delivery team, then add broader roles only after testing. Confirm which claim key your Argo CD version reads for RBAC, since Dex-based configuration uses a different claim name. The check is that a user in the pilot group sees only the applications and projects the mapping allows.
Test sign-in with non-admin accounts
Sign in with at least two test accounts from different Entra groups, one that should have read-only access and one that should have a project role, and compare what each can see and change in the UI and with the CLI using SSO. Also test a user outside every mapped group, who should see nothing beyond default access. The check is that each account behaves as its group mapping predicts and that a sign-in from an account not in any group is denied the actions it should not have.
Disable the admin user once SSO works
After the non-admin tests pass, set admin.enabled to false in argocd-cm so the built-in admin account can no longer sign in. Keep a documented break-glass procedure that your team can use if the identity provider is unavailable, and confirm who holds it. The check is that the admin login is rejected and that a mapped Entra user still has the access the tests showed, from a fresh browser session.

Which Entra ID attributes map to Argo CD roles

This table traces each Entra ID attribute from the sign-in token or directory to the Argo CD identity or RBAC rule it feeds. Read it top to bottom to see where a user's permissions come from, and where to look when a user has the wrong access. Confirm the exact claim names against the Argo CD Microsoft user management guide before you write any policy.

Entra ID attribute	What it carries	Where Argo CD uses it	What to confirm
User identifier (oid or sub)	Stable unique ID for the signed-in user in the tenant	Identifies the user in Argo CD sessions and audit entries, independent of display name	Which claim your configuration uses for the user ID and whether it is stable across renames
Email (preferred_username or email)	Sign-in name or mail address of the user	Display and audit context; some setups use it as the subject in policy.csv	Whether your tenant populates the email claim for guest and synced accounts
Group object IDs in the groups claim	GUIDs of security groups the user belongs to, sent in the token	Matched against g lines in policy.csv to bind groups to Argo CD roles	That the groups claim is emitted with object IDs and the token includes the groups you plan to bind
Group display names	Human-readable group names shown in the Entra admin center	Not used for matching; renaming a group does not break bindings made on object IDs	Use names in comments in policy.csv so reviewers can read the mapping
Overage group list from Microsoft Graph	Full group membership when a user is over the 200-entry groups limit	Fetched through the overage setting so users in more groups can still receive roles	That the User.Read delegated permission is granted and that Graph is reachable from Argo CD
Application roles (app role assignments)	Roles assigned to users or groups on the enterprise application	Only relevant if your design uses roles claims instead of groups	Whether your chosen method emits roles, and how your team will keep one source of truth
policy.csv group bindings	g lines linking a group identifier to an Argo CD role or project role	Final step that turns a token claim into permissions on applications and projects	Each binding against a test user in a non-production instance before rollout

Why the 200-group overage problem locks users out

Microsoft Entra ID limits the groups claim in an ID token to 200 entries. A user who belongs to more groups than that does not receive the list in the token. Instead, the token carries an overage indicator, and Argo CD cannot build that user's RBAC roles from the claim alone. With enableUserGroupOverageClaim set to true, Argo CD calls Microsoft Graph /me/getMemberGroups to fetch up to 2048 security groups for the user. That call needs the User.Read delegated permission on the app registration, so confirm it is granted and consented before you enable the setting. The Argo CD Microsoft user management guide is the reference for the exact flag and permission names.

The lockout risk comes from that second call. If Graph is unreachable from the Argo CD API server or Dex when a user signs in, a user over the 200-group limit cannot complete login, even though their identity is valid and their password and MFA succeed. Users under the limit are unaffected, which makes the failure look intermittent and hard to attribute. Plan for this as an availability dependency: check outbound reachability to Graph from the cluster network, including any proxy or egress policy you apply to the namespace, and add the login path to your monitoring and runbooks.

The most effective control is to reduce how many groups a user carries into the token. Assign only the Entra groups that Argo CD actually maps to roles, and use a dedicated group naming scheme so those groups are easy to filter. Where possible, keep Argo CD access groups separate from broad organizational or licensing groups that accumulate over time. Review membership on a schedule, because group sprawl, not Argo CD itself, usually pushes users over the threshold. Ask your identity team to report how many groups your heaviest users hold before you rely on the overage path in production.

Security settings for Entra ID sign-in to Argo CD

Signing in with Entra ID moves trust to your tenant, so the Argo CD settings around that trust matter as much as the login itself. The cards below cover how the app credential is stored, which local access paths stay open, how the endpoint is encrypted, how roles are granted, and what a compromised tenant can change.

Prefer workload identity over client secrets

Argo CD documents two direct OIDC options for Entra ID: a client secret or workload identity federation. Workload identity federation is the recommended option, because no long-lived secret is stored in the Argo CD configuration to leak or rotate by hand. Before you choose, confirm with your Entra administrator that the federated credential can be created in your tenant and that your Argo CD version supports the configuration you plan to use.

Disable the built-in admin user

The built-in admin account is a local password login that bypasses Entra ID entirely. The user management documentation recommends using it only for initial setup. Once SSO works and at least one administrator can sign in through Entra ID, set admin.enabled to false in argocd-cm. Keep a tested break-glass procedure written down before you do so, because a misconfigured OIDC setting with no admin login leaves you locked out.

Encrypt every Argo CD endpoint

Sign-in redirects, the Argo CD API and the CLI all carry credentials and tokens, so the external endpoint must terminate TLS with a certificate your organization manages. Argo CD also uses TLS between its own components. Confirm the redirect URI registered in Entra ID uses the exact HTTPS address users reach, and that the CLI callback path works behind your ingress and any corporate proxy.

Grant roles through least-privilege policy.csv

Map Entra ID groups to Argo CD roles in argocd-rbac-cm through policy.csv, starting from a default role with no permissions. Give each group access only to the projects and actions it needs, and avoid granting the admin role to broad groups. Since Argo CD 3.0, update and delete permissions apply only to the application itself and logs require an explicit logs, get permission, so review each role after upgrades.

Protect the group source in Entra ID

Argo CD trusts whatever group claims Entra ID issues, so anyone who can change group membership can change Argo CD access. A compromised tenant administrator, or a delegated user with group management rights, can therefore grant production deployment rights without touching Argo CD itself. Restrict who can manage the groups used in policy.csv, require MFA for those administrators, and review audit logs for membership changes on those groups.

Know what tokens and secrets stay hidden

Argo CD authenticates API requests only with JSON Web Tokens, so a stolen session token is the main credential to protect and should expire on a short schedule. Argo CD redacts cluster, Git and OAuth2 credentials from API responses and logs, which limits exposure during troubleshooting. Still review the security documentation for repo-server exposure, since it runs Helm and Kustomize on repository content.

Questions buyers ask about Entra ID sign-in for Argo CD

How much does Entra ID sign-in for Argo CD cost?

The software itself costs nothing, since Argo CD is Apache-2.0 licensed. The cost comes from three places: the Microsoft Entra license tier your users need, internal identity administration time, and platform engineering time to configure the OIDC application, map groups to Argo CD roles and test them. Entra ID Free is included with Microsoft cloud subscriptions such as Azure and Microsoft 365, and Microsoft lists P1 and P2 at separate per-user monthly rates on its pricing page, with P1 included in some Microsoft 365 plans. Check the Microsoft Entra pricing page for current amounts, and confirm which tier covers the people who will sign in. Ask any partner quote to list the engineering effort separately from licenses.

Which Entra ID license do we need for Argo CD sign-in?

Sign-in itself depends on the tenant having an application registration and a sign-in path your users already use, so confirm that first with your Entra administrator. Licensing matters when you rely on features beyond basic sign-in, such as conditional access, group-based assignment or identity protection. Microsoft's pricing page describes which features sit in each tier and which Microsoft 365 plans include P1 or P2. Decide the tier based on your policy needs, not on Argo CD alone, and record the decision with your identity team before the build starts.

How long does Entra ID sign-in for Argo CD take to set up?

Duration depends on how many groups map to Argo CD roles, whether a hybrid directory synchronizes groups into Entra ID, and how many approval cycles your tenant requires for new application registrations. A small, single-tenant setup with one test group and a clear owner is usually the shortest path. Larger role models with several projects, a group overage workaround and a staged rollout take longer. Ask for a written schedule that separates tenant changes, Argo CD configuration, testing and cutover, and name the client approver for each step.

What do we need to provide before a partner starts?

Plan for four inputs. First, tenant administrator access, or a named administrator who can create the application registration and grant the permissions Argo CD needs. Second, a named owner for the groups that will map to Argo CD roles, who can confirm membership and approve changes. Third, a dedicated test group with a few accounts that can sign in and be checked against each role. Fourth, a decision on who may use the local admin account during cutover. Without these, the work stalls at the first permission request, so agree on them in the written scope.

Can our own team set up Entra ID sign-in for Argo CD alone?

Often yes, if your team already runs Argo CD on Kubernetes, has an identity administrator who can change the tenant, and can test RBAC in a non-production cluster first. The skills needed are OIDC configuration, Argo CD RBAC policy and Entra group management. The harder parts are the groups claim limit, which affects users in many groups, and the rollout plan so administrators do not lose access. If one of those areas is new to your team, a fixed-scope engagement can cover the design, build and test while your staff keep ownership of the result.

What goes wrong when users belong to many Entra groups?

Entra ID limits the groups claim to 200 entries. When a user exceeds that, the token carries an overage indicator instead, and Argo CD can call Microsoft Graph to fetch up to 2048 security groups if you enable the overage setting. That call needs the User.Read delegated permission, and users over the limit cannot log in if Graph is unreachable. Confirm whether your users approach the limit, check Graph reachability from the Argo CD API server, and decide whether to filter groups to the ones Argo CD uses. This is a design item to settle before go-live.

Should we use a client secret or workload identity for Argo CD?

Workload identity federation is the option Argo CD's documentation recommends over a client secret, because it removes a long-lived credential that must be stored, rotated and protected. A client secret is simpler to set up but adds a rotation duty and a secret to guard. The choice affects who must be involved, since workload identity needs a federated credential configured in the tenant and a cluster that can present the required token. Confirm your platform supports the chosen method and record the rotation or trust decision as part of the access review.

Does the work also cover ongoing administration after go-live?

Some work recurs after go-live: adding or removing group mappings when teams change, reviewing role assignments, rotating any client secret, and upgrading Argo CD across minor releases, which the project patches for the three most recent minor versions. Identity administration time continues as groups change. Ask whether the quote covers handover, runbooks and a support retainer, and whether the named owners on your side are trained to make routine changes without an engagement.

Common Entra ID sign-in failures in Argo CD and their fixes

This table lists the sign-in failures teams most often hit when wiring Argo CD to Microsoft Entra ID, with the likely cause and fix for each. Read it top to bottom when a login breaks, and start with the first check in each row before changing configuration. The main takeaway is that most failures trace to the redirect URI, the groups claim, or the Graph permission, not to Argo CD itself.

Symptom	Likely cause	Fix and first check
AADSTS50011 redirect URI mismatch after sign-in	The reply URL registered in the Entra app does not exactly match the Argo CD callback URL, including scheme, host and trailing path.	Compare the registered redirect URI character by character with the Argo CD URL. Correct the app registration, then retry the login in a private browser window.
User signs in but has no Argo CD permissions	The groups claim is missing from the token, or the policy.csv mapping uses group names where Entra sends object IDs.	Decode a sample token and confirm the groups claim is present. Map the group object IDs in RBAC, not display names, and confirm the scopes setting includes groups.
Users in many groups get no groups at all	The user belongs to more than 200 groups, so Entra replaces the groups claim with an overage indicator and Argo CD must call Graph.	Set enableUserGroupOverageClaim and confirm the User.Read delegated permission is granted. Check that the user's group count is above 200 before changing anything else.
Overage users fail to log in while others succeed	Argo CD cannot reach Microsoft Graph /me/getMemberGroups from the cluster, often because of egress rules or a proxy.	Test outbound HTTPS to Graph from the argocd-server pod. Open the egress path or configure the proxy, then retry. Users below the limit are unaffected, which points to network access.
Graph call returns a permission or consent error	The User.Read delegated permission was added to the app but admin consent was never granted for the tenant.	Open the app's API permissions in the Entra admin center and confirm consent status. Grant admin consent for the tenant, then have affected users sign in again.
Login works for some users but group roles stop applying after a token change	Argo CD 3.0 Dex-based RBAC uses the federated_claims.user_id claim, so older mappings keyed to other claims no longer match.	Review policy.csv against the 3.0 upgrade notes and confirm the subject identifier in the RBAC lines. Test one account after each change.
No one can sign in after disabling the admin user	admin.enabled was set to false before SSO roles were verified, leaving no working administrator.	Confirm at least one SSO group is mapped to an admin-equivalent role first. Recover through a cluster operator with kubectl access to the argocd-cm ConfigMap, then re-enable admin temporarily if needed.
SSO login fails with a client secret error after rotation	The client secret in the Argo CD configuration expired or was replaced in Entra without updating the Kubernetes secret.	Check the secret expiry date in the Entra app registration. Update the stored secret, or move to workload identity federation, then restart Argo CD components that read it.

When SAML or the Dex microsoft connector makes sense instead

Direct OIDC is the path the workload identity guidance describes, and it should be your default for Argo CD with Microsoft Entra ID. Two alternatives exist: SAML through the bundled Dex, and Dex's microsoft connector. Each one adds components to run. Argo CD itself is then not the only moving part in the sign-in path, because Dex sits between Argo CD and Entra ID, with its own configuration in the argocd-cm ConfigMap, its own logs and its own upgrade cadence tied to Argo CD releases. Choose an alternative only when a specific requirement pushes you there, not because it looks simpler on paper.

The strongest case for these options is an existing Dex deployment. If your Argo CD already uses Dex for another connector, such as GitHub or LDAP, adding a second connector may be less work than running a parallel OIDC configuration with its own client registration and secret handling. The same applies if your Entra ID tenant exposes a SAML application that your security team already governs and monitors. Before committing, confirm in the Argo CD Microsoft user management guide exactly how the connector returns groups, whether it needs the group overage handling described above, and which claim Argo CD uses for RBAC. Group behavior differs between these paths, and a mapping that works with direct OIDC may not carry over unchanged.

Test the chosen path in a non-production instance before you rely on it. Sign in with a user who belongs to more than 200 groups, a user in a single group and a user in no mapped group, and confirm each lands with the expected role. Record which Dex version ships with your Argo CD release, since Dex upgrades are part of your Argo CD upgrade plan. If you pick SAML or the connector and later find the group behavior does not meet your RBAC design, moving to direct OIDC means re-testing sign-in, RBAC and the CLI flow, so decide with that cost in mind.

How DeployOpen scopes and delivers Entra ID sign-in for Argo CD

DeployOpen plans and implements Argo CD sign-in with Microsoft Entra ID inside your own infrastructure, starting from a written scope that names the authentication method, the group mapping and the test cases. The work covers configuration, verification and documentation, and ends with a handover your team can run without us.

How we scope

Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
The scope records which Entra ID method is chosen, whether workload identity or a client secret is used, and why.
The scope lists the groups or app roles that map to Argo CD roles, and how overage over 200 groups will be handled.

How we build

We configure the app registration, redirect URIs, optional claims and Argo CD OIDC settings in your Entra tenant and cluster.
We map group claims to Argo CD RBAC in policy.csv and test each role with accounts that hold different group memberships.
We check the Microsoft Graph permission needed for group overage and confirm behavior when Graph is unreachable.

How we hand over

You receive written configuration, the RBAC mapping, a test matrix with results and a record of each decision made.
We document the admin.enabled change, the local break-glass procedure and the steps to rotate or replace credentials.
We walk your identity and platform staff through the sign-in flow, the group changes they will make and the failure checks.

How we support

Ongoing support, upgrades and continuous testing are available as retainers after the initial handover.
Retainer work can cover re-testing sign-in after Argo CD minor upgrades and changes to Entra ID group structure.
Any change to scope, such as moving from a client secret to workload identity, is agreed in writing before work starts.

Argo CD SSO with Microsoft Entra ID