How Argo CD SSO with Google Workspace works and which method to choose
Platform teams that want Google accounts to sign in to Argo CD should follow the Argo CD Google guide, which routes sign-in through the bundled Dex. The choice is between plain OIDC without groups, which lets people sign in but gives you no group-based access, and the Dex google connector with a service account, which reads Google Groups so that Argo CD roles can follow group membership. Pick the first only if a single shared role or manual per-user assignment is acceptable. Pick the second when access must follow the groups your organization already manages in Google. SAML through Dex is not recommended. The Argo CD Google guide notes that Dex plans to deprecate its SAML module, so a SAML setup built now would need reworking later. Choosing between OIDC and the google connector also affects what you have to provision. The connector path requires a Google service account with domain-wide delegation, the admin.directory.group.readonly scope, the Admin SDK enabled, and an admin email address for Dex to impersonate. Confirm with your Google Workspace administrators who will own that delegation and how it is audited, because it grants read access to directory group data.
Group-based RBAC also depends on the claim Dex passes to Argo CD. Argo CD 3.0 uses the federated_claims.user_id claim for Dex-based RBAC, so check the claim values in a test login before writing policy rules. Google's workload identity option is supported from Dex v2.34.0, which may be preferable to a downloaded key. Confirm the Dex version bundled with your Argo CD release before you rely on it. DeployOpen configures this integration in your own environment, covering the Google OAuth client, the Dex connector, the delegated service account, the Argo CD policy and a sign-in test. DeployOpen does not issue certifications, attestations or audit reports. Evidence that the setup meets your control requirements is produced by your independent auditors, and DeployOpen only prepares the configuration and records.
Plain OIDC or the google connector: which path fits your access model
Plain OIDC through Dex is the path the Argo CD Google guide recommends when every signed-in user should get the same default access. Dex authenticates the user against Google and passes identity claims back to Argo CD, but no group membership is requested, so there is nothing to map to RBAC roles beyond a single default. This keeps the identity setup small: you create an OAuth client in Google Cloud, register the redirect URL, and restrict who can sign in by domain.
- What it needs: an OAuth client for Argo CD in your Google Cloud project, the correct redirect URL, and an allowed domain setting.
- What it can map: a signed-in user identity and a default policy that applies to every authenticated user.
- What it cannot map: per-team or per-group permissions, since no group data reaches Argo CD.
- Setup effort: the smallest of the two paths, with no service account, no delegated admin scope and no Admin SDK dependency.
- Recurring work: reviewing the default policy when teams or application ownership change.
Before you choose this path, confirm that a single default role is acceptable for every person in your domain, including people who should never change production applications.
The Dex google connector adds Google Groups lookup, so Argo CD can map group membership to RBAC roles. This is the path for teams that need different permissions for platform engineers, application owners and read-only auditors. Dex must query the Admin SDK on behalf of an administrator, which requires a Google service account with domain-wide delegation, the admin.directory.group.readonly scope and an admin email for Dex to impersonate.
- What it needs: a service account with domain-wide delegation, the admin.directory.group.readonly scope, the Admin SDK enabled, and an admin email for impersonation.
- What it can map: Google group membership to
glines in the Argo CD RBAC policy, which then grant project and application permissions. - Identity option: the guide says workload identity is supported from Dex v2.34.0, which avoids storing a service account key if your Dex version meets that requirement.
- Setup effort: higher than plain OIDC because of the delegation, scope and Admin SDK steps, and it needs an administrator who can grant domain-wide delegation.
- Recurring work: keeping group names and policy lines in step as Google groups are renamed or restructured.
Confirm your Dex version, whether your organization permits domain-wide delegation, and which Google administrator will own the impersonation account before you commit to this path.
The two paths differ mainly in what Argo CD can see about a user. Plain OIDC gives Argo CD an identity and nothing else, so access decisions cannot depend on team membership. The google connector adds group claims, which makes access follow your directory, but it also makes Google groups a dependency for every sign-in and every permission decision. A group that is deleted, renamed or left empty changes access without any change in Argo CD.
- Granularity: plain OIDC supports one default policy; the google connector supports role differences per group.
- Dependency: group-based access depends on the Admin SDK and the service account remaining available.
- Auditability: group-based RBAC lets you show which Google group grants which Argo CD permission, which helps change-control reviews.
- Blast radius of mistakes: a broad Google group mapped to an admin role grants wide access, so review group membership as carefully as the policy file.
- Testing: verify each mapping with a test account in each group before rollout.
Ask your identity team whether Google groups already reflect the roles you need, or whether they would need to be created first.
The Argo CD Google guide lists SAML through Dex as an option but does not recommend it, because Dex plans to deprecate its SAML module. Choosing SAML for a new Google integration would mean building on a component the upstream project expects to remove, and migrating later. OIDC is the protocol the guide recommends for Google sign-in, with the google connector providing groups where they are needed.
- Deprecation risk: Dex plans to deprecate its SAML module, so a SAML setup would need replacing on a future Dex release.
- Protocol fit: OIDC is the path the guide documents for Google, with and without groups.
- Migration cost: moving from SAML to OIDC later means changing the identity configuration, user mappings and any role bindings that depend on claims.
- Version check: confirm the Dex version bundled with your Argo CD release and its SAML status in the upstream notes.
- Exception handling: if a policy requires SAML, document the reason and the migration plan before deployment.
If your security team has a SAML requirement, raise it early so the design can account for the deprecation and the replacement path.
What you need before configuring Google sign-in for Argo CD
Google sign-in for Argo CD depends on decisions made in three places: the Google Workspace tenant, a Google Cloud project that holds the delegated service account, and the Argo CD installation that Dex runs inside. Settle these before editing any configuration, because group lookup fails in ways that are hard to spot from the Argo CD login screen.
Workspace edition and user count
Business Starter and Business Standard support up to 300 users, while Enterprise editions have no minimum or maximum user limit, according to Google's pricing page. Confirm the number of people who will sign in to Argo CD, including contractors and automation accounts that use Google identities, and confirm the edition your tenant actually holds before you rely on it. The edition also determines whether you can use features such as data regions and client-side encryption, which may matter to your compliance team.
Google Cloud project with Admin SDK
Group lookup runs through the Admin SDK, so the Google Cloud project that holds the service account must have the Admin SDK API enabled. Decide which project owns this identity, who administers it, and how its IAM access is reviewed. Keep it separate from application projects so that changes to the service account do not affect unrelated workloads.
Service account with domain-wide delegation
Dex needs a Google service account with domain-wide delegation and the admin.directory.group.readonly scope. Grant only that read-only scope, and record who approved the delegation in the Workspace Admin console, since it lets the account act across the domain. Plan the key handling, or use workload identity if your Dex version supports it, so that no long-lived key file ends up in Git.
Admin email for impersonation
The delegated service account impersonates a Workspace administrator to read group membership, so you need a dedicated admin user with the privileges required to list groups. Use a named account that is protected with strong authentication and is not used for daily work. Document who can sign in as that account, because compromise of it exposes group data across the domain.
Dex version for workload identity
Workload identity is supported from Dex v2.34.0 onward, so confirm the Dex version bundled with your Argo CD release before choosing it. If your Argo CD release bundles an older Dex, plan for a service account key or an upgrade. Test the chosen Dex version in a non-production instance first, since Dex changes can affect every SSO login.
Supported Argo CD version and HTTPS URL
Argo CD patch releases are published only for the three most recent minor versions, so start from a minor release still inside that window and confirm its patch level with the release notes. Publish the Argo CD URL over HTTPS with a DNS name that matches the redirect URL registered with Google. A mismatch in scheme, host or path is the most common cause of failed sign-in at the start of setup.
Configuring Google OIDC, the service account and Google Groups lookup in order
This sequence takes you from an OAuth client in Google Cloud to a working Argo CD sign-in in which Google Groups drive RBAC, with a check at each step so you know the previous step is sound before you build on it.
Create the OAuth client and redirect URI
In the Google Cloud project that your organization uses for identity, create an OAuth client for Argo CD and register the redirect URI that Dex serves for your Argo CD hostname, using the callback path given in the Argo CD Google user management guide. Your Google Workspace administrator or a cloud identity owner usually performs this step, and the platform team supplies the exact hostname. Record the client ID and client secret in your secrets store, not in Git. The step is complete when the client exists with the correct redirect URI and the secret is stored where your Argo CD secrets process can read it.
Configure Dex with the Google connector and domain
Add a Google connector to the Dex configuration in the Argo CD settings, pointing it at the OAuth client and restricting sign-in to your Workspace domain through the hostedDomains setting. The platform engineer makes this change, and the client secret is referenced from a Kubernetes Secret rather than typed into the ConfigMap. Confirm the Dex pod restarts cleanly and the Argo CD login page shows a Google option. The check is that a user on your domain reaches the Google sign-in screen and a personal account from outside the domain is refused.
Create the service account with domain-wide delegation
In Google Cloud, create a service account for Dex to use for group lookups, then enable domain-wide delegation on it and authorize the client ID for the admin.directory.group.readonly scope in the Google Workspace Admin console. The Admin SDK must be enabled for the project. Workload identity is supported from Dex v2.34.0 if you prefer not to download a key file, so confirm your Dex version before choosing the credential method. The check is that the service account shows delegation enabled and the scope is listed against its client ID in the admin console.
Set the admin email for impersonation
Choose a Workspace super administrator account that Dex will impersonate when it reads group membership, and set it in the Dex Google connector configuration together with the service account credentials. Because the impersonated account carries broad rights, limit who can sign in to that account, protect it with strong authentication, and record its name in your access register. The check is that Dex logs show a successful group lookup on the next login, with no delegation or permission error.
Bind Google group names to RBAC in policy configuration
In the argocd-rbac-cm ConfigMap, map the Google group email addresses to Argo CD roles using policy lines under policy.csv, and set scopes to the claim that carries group membership. Start with one read-only group so the first mapping has a small blast radius. Note that group identifiers must match exactly what Dex returns, so copy the group addresses from the Google admin console rather than retyping them. The check is that a test user in the mapped group appears with the expected role after login, and the role list shows the group name Dex returned.
Disable the built-in admin user
Once SSO and at least one mapped administrator group work, set admin.enabled to false in the argocd-cm ConfigMap, as the user management documentation recommends for the built-in admin after initial setup. Keep the break-glass procedure documented and tested in a way that does not depend on SSO, so a Dex or Google outage does not lock everyone out. The check is that the admin login is refused, a mapped administrator still signs in through Google, and the break-glass path has been exercised once in a non-production environment.
Test login with mapped and unmapped users
Run a structured test with at least one user in a mapped group, one user in a group with a narrower role, and one user with no Argo CD group. Confirm the first user can perform the actions their role allows, the narrower user is denied an action outside their role, and the user with no group sees no applications they should not. Record each result and the group list Dex returned for each test user. This is the check that proves the mapping works, so do not move to production users until every test result matches the policy you wrote.
How Google identities and groups map to Argo CD users and roles
This table traces one Google sign-in from the account email and subject through the Dex claims and group values to the policy.csv bindings that grant Argo CD permissions. Read it as a checklist: each row is a value you must confirm in your own environment before you write a role mapping, because a mismatch in any one of them leaves the user with no access or the wrong access.
| Element | What it carries | Where it is set or checked | What to confirm |
|---|---|---|---|
| Google account email | The human-readable address of the signed-in Workspace user, used for display and often for local admin mapping | Returned by Google through Dex as the email claim | Confirm the address format for your domain and whether any alias or secondary address will appear |
| Google subject identifier | The stable unique ID Google assigns to the account, which does not change when the email is renamed | Returned as the sub claim in the OIDC token | Confirm you key any long-lived role grants on a value that will survive an email change |
| federated_claims.user_id | The user identifier Dex passes to Argo CD for RBAC matching since Argo CD 3.0 | Dex-based RBAC matches on this claim, per the 3.0 upgrade notes | Confirm the value your version emits and use it, not an older claim name, in policy.csv subjects |
| Google Group membership | Group memberships Dex retrieves through the google connector using the Admin SDK directory lookup | Requires the domain-wide delegated service account, the admin.directory.group.readonly scope and an impersonated admin | Confirm the lookup succeeds for a test user who belongs to a group and that nested membership behaves as you expect |
| Group value format returned by Dex | The identifier Dex places in the groups claim, which may be a group email address rather than a display name | Compared with the group string in the policy.csv g line | Confirm the exact string and case from a test login, then copy it verbatim into the binding |
| Role binding in policy.csv | A g line maps a group to a role, and a p line grants that role actions on applications, projects or clusters | Set in the argocd-rbac-cm ConfigMap with scopes set to the claim that carries groups | Confirm the scopes setting matches the claim name and that each g line uses the exact group value |
| Test login and effective role | The permissions a signed-in user receives after mapping, visible in the UI and CLI | Checked by signing in with a test account per group before rollout | Confirm denied actions fail as expected, including for users in no group, and record the result as evidence |
Security settings for Google sign-in and the delegated service account
The Google design gives Dex a credential that can read group membership across your domain, so its scope, its key handling and the admin account it impersonates decide how much damage a leak could do. The cards below cover the Argo CD settings and the Google settings that connect, and the reasons SAML stays out of this design.
Disable the built-in admin user
Use the built-in admin account only for initial setup, then set admin.enabled to false in the argocd-cm ConfigMap once Google sign-in works and at least one SSO administrator has been tested. Keep a break-glass procedure documented outside the cluster before you disable it, because a broken Dex configuration with no local login can lock everyone out. Confirm the change by signing in with a Google account that holds the admin role.
Scope the service account to read-only groups
Grant the service account the admin.directory.group.readonly scope only, and nothing broader, in the domain-wide delegation settings of your Google Workspace admin console. Dex needs to read group membership for RBAC, not to change users or groups. Review the authorized scope list whenever the design changes, since a scope added for a different tool is a common way the delegation grows over time.
Protect the key or use workload identity
A downloaded service account key is a long-lived secret that must be stored, rotated and revoked like any other credential. Where your Dex version supports it, workload identity avoids the key entirely. Workload identity is supported from Dex v2.34.0, so confirm the Dex version bundled with your Argo CD release before choosing it. Record who can read the Kubernetes Secret holding the key, because that person can impersonate the admin account.
Limit the impersonated admin account
Dex impersonates a Google admin account to call the Directory API, so that account's rights matter as much as the service account's. Use a dedicated admin identity with the narrowest role that can read groups, protected by strong MFA and excluded from day-to-day use. Ask your Workspace administrator to confirm the account can be disabled or rotated without breaking sign-in, and monitor its sign-in activity in the admin audit logs.
Serve Argo CD and Dex over TLS
Terminate TLS for the Argo CD server and the Dex endpoint with certificates your organization trusts, and make the OIDC redirect URL in the Google OAuth client match the external HTTPS address exactly. Argo CD encrypts traffic between its own components, but the browser-facing and callback paths are where you must confirm the certificate chain and hostnames. Test sign-in from a clean browser session after every certificate renewal.
Remember API access is JWT-only
Argo CD authenticates API requests only with JSON Web Tokens, so a Google login is not what automation uses. Treat tokens issued after SSO as session credentials with a bounded lifetime, and set up separate, scoped accounts for CI systems rather than sharing a person's session. Review which Argo CD roles are bound to Google groups, because anyone who can reach the API with a valid token carries those permissions.
Why SAML is left out
The Argo CD Google guide does not recommend SAML through Dex because Dex plans to deprecate its SAML module. Building on a connector the upstream project is moving away from adds an upgrade task later. OIDC through Dex, with the google connector for groups, keeps the design on supported paths. Confirm the current Dex deprecation status with the Argo CD release you deploy before you finalize the design.
Questions buyers ask before configuring Google SSO for Argo CD
How much does Google SSO for Argo CD cost to set up?
Argo CD itself is licensed under Apache-2.0 with no paid edition from the project, so the cost is the Google Workspace edition you already pay for, plus the effort to configure Dex, the service account and your group model. The Google Workspace pricing page lists Business Starter and Business Standard as supporting up to 300 users, while Enterprise editions have no minimum or maximum user limit, so edition choice depends on headcount and the controls you need. Recurring costs are the Workspace licenses and the Argo CD operating time. Ask any partner for a fixed-scope quote that separates one-time configuration, testing and handover from any retainer for later changes.
Does the number of Google groups change the effort?
Yes. Group-based RBAC means every group Argo CD must recognize needs a mapping to a role or project, and each mapping needs a test. A small set of groups for admins and read-only users is a short exercise, while dozens of team groups with project-scoped permissions add design time, naming decisions and more test cases. Ask for the group inventory in the scope document, including which groups grant write access to production clusters.
Who in our Google Workspace admin team has to act?
Plan for a Workspace super administrator to create or approve the Google Cloud project and service account, enable the Admin SDK, grant domain-wide delegation with the admin.directory.group.readonly scope, and designate an admin email for Dex to impersonate. The Argo CD team needs the Kubernetes secret handling and RBAC changes. Confirm these roles before kickoff, because delegation approval is often the step that waits longest on the calendar.
Can our own platform team configure this without a partner?
Yes, if your team already runs Argo CD on Kubernetes, can read Dex configuration and has a Workspace administrator willing to create the service account. The Argo CD Google guide documents the steps, and plain OIDC without groups is the simpler first stage. The harder parts are the domain-wide delegation grant, testing group membership for real users and keeping the mapping consistent across upgrades. A partner is useful when those tasks compete with other platform work or when you need the setup documented for audit evidence.
What service account governance do we need?
The service account has read access to group membership across your domain, so treat it as a high-privilege identity. Record who owns it, restrict who can download or rotate its key, and review the delegation scope when administrators change. Workload identity is supported from Dex v2.34.0, which avoids storing a long-lived key where your platform supports it. Confirm the chosen approach with your security team before implementation.
How do Google group changes reach Argo CD, and what should we test after each change?
Argo CD reads group membership through Dex when a user signs in, so a change in Google Groups generally appears the next time a user logs in rather than instantly for an active session. Confirm the exact refresh behavior in your Dex version before promising a timeline. After each group change, test a sign-in from an account in the group and one outside it, check the resulting role in the UI and CLI, and confirm that a removed user loses access to the projects and clusters they should no longer reach.
Is SAML a reasonable option for Google SSO in Argo CD?
Not for a new deployment. The Argo CD Google guide does not recommend SAML through Dex because Dex plans to deprecate its SAML module. Use OIDC through Dex for sign-in, and add the google connector with a service account only when you need group-based RBAC. Plan the configuration so that moving between connectors later does not require rebuilding your role model.
Why Google group lookup or login fails and how to fix it
This table lists the failures teams most often hit when wiring Argo CD to Google through Dex, with the likely cause and the fix for each. Work through it in order when sign-in or group-based roles do not behave as expected, since several symptoms share the same root cause.
| Failure | Likely cause | Fix |
|---|---|---|
| Redirect URI mismatch | The OAuth client in Google Cloud has a callback URL that does not exactly match the Argo CD URL and Dex callback path | Set the authorized redirect URI in the Google OAuth client to match the Argo CD external URL exactly, including scheme and path, then retry sign-in |
| Admin SDK not enabled | Group lookup calls the Admin SDK Directory API, which is off in the project or Workspace domain | Enable the Admin SDK for the project and confirm the Workspace admin console allows the API calls the service account makes |
| Delegation scope not granted or wrong scope string | The domain-wide delegation entry is missing, or it lists a scope other than admin.directory.group.readonly | Add the client ID of the service account under API controls with exactly the admin.directory.group.readonly scope, then wait for the change to propagate and test a group lookup |
| Wrong admin email for impersonation | The configured admin email is not a Workspace super admin or user the service account can impersonate | Set the admin email in the Dex configuration to a real Workspace administrator in the same domain and confirm that account can read group membership |
| Dex older than the workload identity requirement | Workload identity is only supported from Dex v2.34.0, so older Dex images cannot use that setup | Check the Dex version bundled with your Argo CD release and upgrade Dex before switching to workload identity, or use a key-based service account if you cannot upgrade |
| Users with no matching group get no role | Argo CD denies access by default, and the user's Google groups do not match any group line in the RBAC policy | Confirm the group address in the policy matches the Google group email, add a mapping for that group, and test the user's effective role before rollout |
| Admin user still enabled | The built-in admin account remains active after SSO was configured, so password sign-in bypasses the Google login path | Once SSO works and at least one administrator can sign in through it, set admin.enabled to false, and confirm the change in a test session |
Why SAML through Dex is not the path to take for Google
The Argo CD Google guide does not recommend SAML through Dex for Google sign-in, and the reason is maintenance risk: Dex plans to deprecate its SAML connector module. A SAML setup built today would sit on a component its own maintainers intend to remove, so it would need replacing later, under time pressure, and possibly after a release that changes how Dex handles connectors. Do not choose SAML because Google offers it as an identity option. The choice that matters is which of the two supported paths fits your needs.
That leaves two paths. Plain OIDC through Dex is the recommended option when you only need people to sign in and you do not need Argo CD roles driven by Google Groups. The Dex google connector is the option when group membership must drive RBAC, because it is the only path in the guide that reads group data, and it needs a Google service account with domain-wide delegation and an admin email for impersonation. Both paths depend on Dex, so the choice between them is really about whether group-based access is a requirement from day one. Settle that question before you build, since moving from plain OIDC to the connector later changes the identity configuration and the RBAC mapping.
Before you commit, re-check the current Dex and Argo CD documentation, including the Google user management guide and the Dex connector release notes. The deprecation status of the SAML module and the supported connector behavior can change between releases, and your decision should rest on the version you will actually deploy. Ask your DeployOpen contact to confirm the Argo CD and Dex versions in scope, then record the decision and the version it was based on in your design notes.
How DeployOpen scopes and delivers Google SSO for Argo CD
DeployOpen plans and delivers Argo CD sign-in through Google Workspace in infrastructure you control, starting with a written scope that decides whether Dex carries group-based RBAC or plain OIDC is enough. The work covers the Dex configuration, the Google service account setup, the role mapping and the handover documents your administrators need.
How we scope
- We confirm which Google Workspace edition and admin accounts your organization uses before choosing plain OIDC or the Dex google connector.
- The written scope names the Argo CD version, cluster layout, and the Google groups that must map to Argo CD roles.
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we build
- We configure Dex and the Argo CD OIDC settings in your clusters, with admin.enabled set to false once SSO sign-in is tested.
- We set up the domain-wide delegated service account and the admin.directory.group.readonly scope with your Google admins.
- We test sign-in and group-to-role mappings for each team in a non-production instance before any production change.
How we hand over
- You receive the Dex and policy configuration, the service account setup record, and the group-to-role mapping table.
- Runbooks cover how to add a Google group, rotate delegated credentials, and recover admin access if SSO fails.
- Your administrators are walked through the test cases so they can repeat sign-in and group checks after handover.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, including Argo CD patch and minor version updates.
- Retainer work can cover re-testing SSO after Argo CD or Dex upgrades, since those changes can affect the connector.
- Your team confirms the current Google Workspace edition and Dex version with your vendors before each scoped change.
