How Argo CD mapping identity provider groups to RBAC roles works
Group mapping turns a signed-in identity into Argo CD permissions. When single sign-on works but users see nothing, or see far too much, the fault almost always sits in this chain: the identity provider issues claims, Argo CD reads the claims named in the scopes setting, and the RBAC policy decides what each claim can do. By default scopes reads the groups claim, and it can be set to a list such as [groups, email] if you need more than one claim checked. A group's policies apply only after it is bound to a role with a g line in policy.csv, so a group that exists in your identity provider but has no g line grants nothing. Each p line then defines what that role can do on which resources and in which projects, and a user holding several roles gets the union of their permissions.
Plan the chain in that order when you design the mapping: confirm the claim arrives in the token, confirm the value Argo CD receives, then write the g and p lines against that exact value. Group identifiers are a frequent source of mismatch, since some providers emit display names and others emit opaque IDs, and a policy written against one form will not match the other. Confirm with your identity provider's administrator which form the token carries for your tenant, and keep the group naming consistent across the identity provider and the policy. Teams usually need this mapping instead of local accounts once more than a handful of people sign in, once access must follow joiner and leaver events in the directory, or once audit reviewers ask who held which permission and why. Local accounts remain useful for break-glass access, and the Argo CD RBAC guide is the reference for the exact syntax and the argocd admin settings rbac commands you will use to test it.
Which scopes, mapping and group identifier settings fit your identity provider
This table compares the scopes setting, the form of group values, and direct OIDC against Dex connectors when mapping identity provider groups to Argo CD roles. Read each row for the condition that makes an option fit and the failure that follows a wrong choice. The main takeaway is that the value your provider sends in the claim must match the g line in policy.csv exactly, so confirm the claim before writing policy.
| Setting or option | When it fits | What breaks if it is wrong |
|---|---|---|
| Default scopes (groups only) | Fits when your provider sends a groups claim under that exact name and policies need only group membership. | Group policies never match if the claim has another name, and users receive only what their other roles grant. |
| Scopes as a list, such as groups and email | Fits when a second claim helps identify users or when policies depend on more than group membership. | Each listed claim must exist in the token. A claim the provider does not send cannot match any rule. |
| Group names in the claim | Fits when the provider sends readable group names and renames are rare or coordinated with policy updates. | A renamed group silently changes or removes its grants. The g line must match the string exactly. |
| Group IDs or object identifiers | Fits when names can change and the provider emits stable identifiers in the claim. | Name-based g lines never match identifiers. Confirm with your provider which value its claim carries. |
| Direct OIDC to the provider | Fits when the provider places groups in the ID token or another claim Argo CD reads without a connector. | If the groups claim is absent from the token, RBAC sees no groups. Check the token before writing policy. |
| Dex connector (SAML, LDAP, GitHub) | Fits when the provider is not OIDC or a Dex connector supplies the group data you need. | Group values depend on connector mapping. Dex-based RBAC uses federated_claims.user_id from 3.0 onward, so review policy lines after upgrades. |
| Validate and test before rollout | Fits every mapping: validate the policy file and test sample subjects against the live configuration. | Skipping this leaves claim assumptions untested, so the first failure often locks a user out. |
How g and p lines in policy.csv work together
A g line in policy.csv assigns a subject to a role. For SSO, the subject is the group value that arrives in the OIDC claim named in scopes, which defaults to groups. The line tells Argo CD that anyone whose token carries that group should be treated as holding the named role. The role can be one of the built-in roles or a custom role that you define with its own p lines. Nothing in the g line grants permission by itself; it only links a group to a role.
- Format: a line such as
g, platform-admins, role:adminbinds the groupplatform-adminsto the built-in admin role. - Custom roles: a binding such as
g, payments-deployers, role:payments-deployerpoints the group at a role you wrote. - Claim source: the group string must match the value the identity provider actually emits, so check the claim in a real token before writing the line.
- Scopes: the claim named in
scopesmust be present in the token for the binding to match at all. - Case and format: group values are compared exactly, so confirm capitalization and any prefixes with the identity provider.
Before rollout, decode a test token from each group and confirm the exact string that appears in the claim. Confirm the binding works with the argocd admin settings rbac command against the live configuration.
A p line grants a role permission to perform an action on a resource. The Argo CD RBAC model covers applications, projects, logs and other resource types, and each line names a subject (a role), a resource, an action and an object scope, followed by an allow or deny effect. Because the subject in a p line is a role, the same role can be reused across many groups, and a change to the role applies everywhere it is bound.
- Applications: lines on
applicationscontrol actions such as get, sync and override against a project and application pattern. - Projects: lines on
projectscontrol who can read or change the project itself. - Logs: log access needs an explicit
logs, getpermission, which the 2.14 to 3.0 upgrade notes call out. - Update and delete: since 3.0, update and delete RBAC apply only to the application itself, so check object scope on those lines.
- Deny lines: an explicit deny overrides an allow for the same match, which helps when a broad grant needs one exception.
Define each line with a specific object pattern, such as a project name, rather than a wildcard, and test the result against a sample subject before relying on it.
The following example is illustrative only. It shows two custom roles and their bindings. The first role is read-only, and the second lets a team deploy only within its own project. Group names and project names are placeholders, and you should adapt them to your own identity provider and project layout.
- Read-only role:
p, role:readonly, applications, get, */*, allowandg, all-engineers, role:readonlylet every engineer view applications without changing them. - Project-scoped deployer:
p, role:payments-deployer, applications, get, payments/*, allowandp, role:payments-deployer, applications, sync, payments/*, allowlimit actions to applications in thepaymentsproject. - Project access:
p, role:payments-deployer, projects, get, payments, allowlets the role see the project it works in. - Binding:
g, payments-deployers, role:payments-deployerconnects the group from the identity provider to the role. - Review: keep each role in a short, labeled block so auditors can match lines to the groups they cover.
Run both examples through argocd admin settings rbac validate before deployment, and confirm the object patterns match the names your team uses.
The most common misunderstanding is that a group receives permissions as soon as its policies exist. In practice, a group's policies apply only after a g line assigns that group to a role. A p line that names a role has no effect on any user until some group, user or subject is bound to that role. Many SSO problems that look like permission bugs are missing or misspelled binding lines.
- Two separate steps: define the role with
plines, then bind the group with agline. - Silent failure: a valid role with no binding produces users who can sign in but see nothing extra.
- Group to role: one group can hold several roles, and one role can serve several groups.
- Default role: a default policy applies to authenticated users who have no matching binding, so review it before adding new groups.
- Testing: use argocd admin settings rbac to test a specific subject and action against the live configuration.
Before a release, confirm for each group that a g line exists and that the role it points to contains the p lines you expect.
Setting up a group mapping step by step
This sequence takes a group claim from your identity provider through to a tested Argo CD role mapping, with a check at each stage so that no change reaches all users until it has been proven on a local policy file and against live subjects.
Confirm the groups claim reaches Argo CD
Sign in as a test user through your configured SSO path and inspect the token your identity provider issues. Confirm that the groups claim is present, that it lists the group identifiers you intend to map, and that the claim name matches what Argo CD checks. Your identity provider administrator usually owns this step, and the Argo CD administrator reviews the result. It is done when a test user's token shows the expected group values and the user can log in without errors.
Set the scopes setting
In argocd-rbac-cm, set the scopes key to the claim or claims Argo CD should evaluate. The default is groups. If you also need email matching, set a list such as [groups, email]. Make this change in your Git-managed configuration so it is reviewed like any other change. It is done when the rendered ConfigMap shows the intended scopes value and the Argo CD API server has restarted or reloaded it.
Define project roles and p lines
Decide which permissions each role needs, scoped to specific AppProjects where possible. Write p lines in a local policy.csv file that grant actions such as get, sync or override on the applications and projects a team owns, and keep the wildcard grants to a minimum. Record each role's purpose beside it in your change request. It is done when every p line names a role, a project, an object type and an action you can justify to a reviewer.
Add g lines that bind groups to roles
For each identity provider group, add a g line that assigns it to the role you defined. Use the exact identifier the token carries, whether that is an opaque group ID or a readable name, because a mismatch produces a silent failure in which the group has no permissions. Confirm the identifier against the token captured in the first step. It is done when each group in scope maps to exactly one intended role and no g line refers to a group you did not verify.
Validate the policy file locally
Run argocd admin settings rbac validate against the local policy file to confirm the syntax and structure are accepted. Fix any reported errors before going further. Then run argocd admin settings rbac against the same file with a test subject, such as a group identifier from your token, and an action such as get on an application in the target project. Expect allow for permissions you granted and deny for everything else. It is done when validation passes and the allow and deny results match your written expectations for each group.
Test live subjects against the running configuration
Apply the policy to a non-production Argo CD instance, then run argocd admin settings rbac again, this time against the live configuration rather than a file. Test real subjects drawn from captured tokens of users in each group, including a user who should be denied. Also test a user in no mapped group. Record the outputs. It is done when live results match the local results for every group and the denial cases fail as expected.
Prepare a rollback plan before wide enablement
Before the mapping applies to all users, keep the previous rbac configuration in version control so it can be restored in one change, and confirm who can make that change and how quickly it can be reviewed. Note which local admin access path remains available if SSO mapping locks out administrators. Confirm the admin account policy in the user management documentation before disabling anything. It is done when the rollback change has been rehearsed in a non-production instance and the team agrees on the trigger for using it.
Enable the mapping and verify with real users
Roll the validated configuration to production, starting with the group or team that has the lowest-risk access, then sign in as representative users from each group. Check that each user sees and can act on only the applications their role allows, and watch the Argo CD logs for denied requests that suggest a missing mapping. Expand to other groups once these checks pass. It is done when a representative user from each mapped group has been verified and no unexpected denials remain.
Security risks of broad or untested group mappings
A group mapping decides who can change production deployments, so a single broad group or an unreviewed policy edit can grant far more access than intended. The cards below cover the risks that most often turn a working SSO setup into an exposure, each paired with a control you can apply and verify before rollout.
Over-broad groups granting admin
If a common identity provider group such as all engineers or all staff is mapped to the admin role, every member gains control over every application and cluster Argo CD manages. Map groups to narrow project roles instead, and confirm in your provider which groups are actually emitted in the groups claim. Run argocd admin settings rbac can for a representative user from each group before any mapping goes live. Review group membership as part of your access reviews, since membership changes are the source of most unexpected grants.
Membership changes waiting for re-login
Argo CD reads group claims from the token issued at sign-in, so a user removed from a group can keep the old permissions until their session ends. Removing access in your identity provider is not enough on its own. Set session lifetimes that match your offboarding requirements, and test a removal in a non-production instance by signing in before and after the change. Document how long a revoked user can keep access so that approvers know the exposure window.
Built-in admin left enabled
The built-in admin account exists for initial setup and bypasses your identity provider entirely. Leaving it enabled gives anyone who obtains its password a path around every group mapping you built. After SSO and at least one tested mapping are working, set admin.enabled to false in argocd-cm. Confirm the change by attempting a login as admin and recording the rejection, and keep a break-glass procedure that is documented and reviewed.
Policy changes merged without review
The g and p lines in policy.csv decide which groups can act on which projects, so a one-line edit can widen access silently. Keep the policy in version-controlled configuration, require review from a security owner for any change to role or group assignments, and run argocd admin settings rbac validate against the file in CI. Compare each proposed change with the last approved version so that reviewers can see exactly which permissions a group gains.
Untrusted repositories from mapped users
The repo-server runs Helm and Kustomize on repository content, so a user who can point an application at a repository they control can run build tooling inside Argo CD's environment. Restrict which users can create or update applications, limit each project to an approved set of source repositories and destination clusters, and review who holds update rights on applications. Ask your platform team which repository credentials the repo-server can reach before granting these rights to a broader group.
Questions teams ask before mapping Argo CD roles to identity groups
How much effort does mapping identity groups to Argo CD roles take?
The effort depends mostly on how many groups you map, how many Argo CD projects they touch, and how clean your identity provider's group structure already is. A small mapping with a few groups and one or two projects is a contained change. Effort rises when groups are nested, when several teams share one Argo CD instance, or when the mapping has to be designed from scratch rather than adapted from an existing model. Ask any provider for a written scope listing the groups, projects, roles and test cases included, since that list is what drives the quote.
Can our team set up group-based RBAC on its own?
Yes, if one or two engineers can read the RBAC guide, edit policy.csv safely and run the validation commands against a copy of the configuration. The harder parts are rarely the syntax. They are agreeing which group gets which permission, confirming the claim that carries group membership, and proving that nobody gains access they should not have. Teams without a Kubernetes and identity background usually ask for an outside review of the final policy before it reaches production, even when they build the first draft themselves.
What do identity and platform owners need to provide?
Identity owners need to confirm which claim carries group membership, whether group values arrive as names or as IDs, how many groups a user can receive, and which groups are dedicated to Argo CD. Platform owners need to define the Argo CD projects, the destination clusters and namespaces each team may use, and who approves changes to the policy. Both groups should agree on a change path for group renames and deletions, because a stale group ID in policy.csv silently removes access. Write these answers down before any build work starts.
How long does testing a group mapping take as group count grows?
Testing time grows with the number of groups, roles and projects, because each combination of user, group and action needs a check. Start with a test matrix: for each group, list the actions it should allow and deny, then run argocd admin settings rbac against the candidate policy before any change reaches the live configuration. Plan extra time for users who belong to several groups, for groups that exceed the token size limit, and for sign-in flows that differ between the web UI and the CLI. Ask a provider to show the test matrix as a deliverable.
Should the mapping use group IDs or group names?
Use the identifier your identity provider stays stable with, which is usually the group ID, because names can change when a team is renamed. Group names are easier to read in policy.csv and in reviews, so many teams keep a comment beside each ID that records the human-readable name. Confirm with your identity provider whether the claim carries IDs or names by default, and test with a real user before committing. A mismatch between the value in the token and the value in the policy is the most common reason a group appears to do nothing.
What should we ask an outside partner to include in the scope?
Ask for a written scope that names the identity provider and connection method, the claim used for groups, the list of Argo CD projects and roles to be mapped, the test matrix and the rollout steps. Also ask how the partner will handle the admin account, how changes will be reviewed, and what handover documentation you receive. Fixed-scope engagements are agreed in writing before work starts, so the deliverables and the acceptance criteria should be clear enough that you can check them yourself. Ask for a quote based on that scope rather than a general hourly estimate.
What breaks most often after a group mapping goes live?
The most common failures are a group ID that changed, a group that was never assigned a role with a g line, and a user whose group list was truncated by the identity provider. Each one looks like a permission problem but starts in the mapping. Check the claim for a sample user after every identity change, and keep the test matrix in version control so it can rerun after edits. Ask any partner how they plan to monitor these failures once the mapping is live.
What to confirm in your identity provider and Argo CD version
Most RBAC mapping failures trace back to a version difference or a claim the provider never sends. Confirm the Argo CD release, the claim path and the token behavior before you write a single policy line, because each one changes which lines in policy.csv will match.
Argo CD version and 3.0 RBAC changes
Confirm the exact Argo CD minor version before copying any policy example. The 2.14 to 3.0 notes changed how Dex-based RBAC identifies users, so it now uses the federated_claims.user_id claim. Update and delete permissions also apply only to the application itself, and reading logs needs an explicit logs, get permission. Check the version against the project's supported release list, since only the three most recent minor versions receive patch releases.
Groups claim and its size limit
Confirm that your provider emits the claim named in scopes, usually groups, in the token Argo CD actually receives. Some providers omit group membership by default, require an extra configuration step, or switch to a overflow mechanism when a user belongs to many groups. Ask the provider for the documented limit on group claims and test with a user who has the highest realistic group count, not a sample account.
Group IDs versus display names
Many providers send opaque object IDs in the groups claim instead of readable names. A g line that uses a display name will then match nothing, and the group will silently get no permissions. Decide whether your policy will use IDs or names, record the mapping in version control, and confirm the exact string the token contains by decoding a test token rather than trusting the admin console label.
Token lifetime and re-login behavior
Changing a group membership in the identity provider does not update an existing Argo CD session until the token is reissued. Confirm the access token lifetime, whether refresh tokens are issued, and how long a removed user keeps access after an assignment is revoked. Plan for users to log out and back in after every mapping change, and state that window in your rollout notes so that access reviews reflect the real delay.
Claims in the CLI login token
The argocd login --sso flow uses a separate client, so the groups claim must also appear in the token issued to that client. Check that the CLI client has the groups scope and claim mapper enabled, and that the token it produces contains the same group strings as the web login. A web session that works while CLI access fails usually means the claim is missing from the second client, not that the policy is wrong.
How to test a group mapping before it reaches production users
Test the mapping in stages, and start with the policy file before any live login. Run argocd admin settings rbac validate against the policy.csv file to catch syntax errors and malformed g or p lines, then review each g line and confirm the group string matches exactly what the identity provider sends in the claim named in scopes. Because a group's policies apply only after it is assigned a role, a missing g line will look like a working login that simply cannot do anything. Keep the offline file in version control so the reviewer sees the same content that will be applied.
Next, check the live configuration with argocd admin settings rbac, which tests whether a given subject can perform a given action. Pick one sample subject from each group, using a test account or a real user who has agreed to participate, and run the actions that matter most: syncing an application in a permitted project, attempting a sync in a project the group should not reach, and reading logs. Then move a small pilot group onto SSO while the others stay unchanged. Watch the first sign-ins, because the claim value a user actually receives is the final check on group IDs versus names. Confirm the setup against the Argo CD RBAC configuration guide before widening access.
Keep the admin account enabled until SSO has been proven for every role that matters, and only then set admin.enabled to false. Record evidence for the change review: the validated policy file with its version, the output of each subject test, the pilot sign-in results, the identity provider group identifiers used, and the approver for the final switch. Note any denied actions you expected and any you did not, since reviewers look for both. Repeat the subject tests after every change to policy.csv or to the identity provider's group configuration.
How DeployOpen scopes and delivers Argo CD group mappings
DeployOpen treats group-to-role mapping as a written, testable change to your Argo CD installation rather than a configuration edit made by hand. We scope the identity provider claims, the policy lines and the project roles together, then test each mapping against your own groups before it reaches your production instance.
How we scope
- Confirm which OIDC claims Argo CD checks in scopes, and whether groups alone or groups with email are needed
- Inventory the identity provider groups, recording each group's ID and display name for every mapping
- Agree in writing which Argo CD roles and AppProject roles each group receives, and which groups receive none
- Engagements are fixed-scope, with scope, deliverables and timelines agreed before any work starts
How we build
- Write the g and p lines in policy.csv from the agreed matrix, keeping one reviewable change per group
- Validate the policy file with the Argo CD admin settings rbac validate command before any cluster is touched
- Run the argocd admin settings rbac check against the local file and the live configuration for each subject and action
- Keep the policy and the identity provider configuration under version control so every change has a reviewer
How we hand over
- Deliver a mapping document listing each identity provider group, its Argo CD role, its project bindings and its owner
- Provide a test record showing allowed and denied actions for representative users in each group
- Document the rollback steps, including how to restore the previous policy.csv and confirm admin access
- Walk your platform and security teams through the change process for adding or removing a group later
How we support
- Review group membership changes and policy updates when your identity provider or teams change
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped in writing
- Re-run permission tests after each Argo CD upgrade, since RBAC behavior can change between versions
- Confirm with your identity provider vendor how group claims behave for your tenant before each planned change
