Rbac Overview

Role-Based Access Control (RBAC) is the core mechanism used to secure your ArgoCD instances, control developer permissions, and prevent unauthorized resource modifications. As multiple teams, CI pipelines, and automated processes interface with the GitOps controller, restricting resource access is critical for cluster security.

In this guide, we will analyze the architecture of ArgoCD access control, policy models, and the structure of RBAC CSV policies.

1. The Architecture of ArgoCD Access Control

ArgoCD implements a centralized access control layer that intercepts all requests coming from the Web UI, the command-line interface (CLI), and direct REST/gRPC API calls. This validation process is managed by the application controller and api-server pods:

               ArgoCD RBAC Authentication Flow
┌────────────────────────────────────────────────────────┐
│  Request Source: Web UI / CLI Client / CI pipeline     │
├────────────────────────────────────────────────────────┤
│  Authentication Layer: OAuth SSO / Local User Token    │
├────────────────────────────────────────────────────────┤
│  RBAC Authorization Engine: Evaluates argocd-rbac-cm   │
│  - Checks policy rules parsed from CSV configurations   │
├────────────────────────────────────────────────────────┤
│  Outcome: Allow/Deny request execution                 │
└────────────────────────────────────────────────────────┘

1. Request Interception: The API server authenticates the incoming request using local tokens or Single Sign-On (SSO) session data.
2. Policy Evaluation: The authorization engine reads rules configured in the argocd-rbac-cm ConfigMap.
3. CSV Parsing: Rules are parsed from CSV (Comma-Separated Values) format, defining policies based on roles, resources, applications, and permissions.
4. Action Execution: The request is approved or rejected based on matching policy definitions.

2. Configuring policies inside argocd-rbac-cm

The primary RBAC configuration is defined inside the argocd-rbac-cm ConfigMap in the argocd deployment namespace.

The ConfigMap Policy Fields:

• policy.default: Defines the default role assigned to authenticated users who do not match any explicit role mapping (e.g., role:readonly to protect resources).
• policy.csv: Contains the list of access rules, defined using a specific CSV permission model.
• scopes: Restricts the OIDC scopes used for group mapping matching.

Here is a complete, production-ready ConfigMap manifest:

# argocd-rbac-cm.yaml
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
  labels:
    app.kubernetes.io/part-of: argocd
data:
  # Set default role to read-only for security
  policy.default: role:readonly
  # Configure explicit group mapping and rules
  policy.csv: |
    # Grant admin access to devops leads
    g, "company:devops-leads", role:admin
    # Define custom developer access rules
    p, role:developer, applications, get, */*, allow
    p, role:developer, applications, sync, */*, allow
    p, role:developer, applications, create, staging-*, allow
    p, role:developer, applications, delete, staging-*, deny

Apply this configuration to your cluster:

kubectl apply -f argocd-rbac-cm.yaml -n argocd

3. The Format of RBAC CSV Policies

ArgoCD uses the Casbin policy engine under the hood. All rules inside the policy.csv block follow specific formats:

Policy Rule Format:

p, <subject>, <resource>, <action>, <object>, <effect>

• p: Indicates this line defines a policy rule.
• <subject>: The target role or user matching this policy (e.g., role:developer).
• <resource>: The target resource category (e.g., applications, projects, repositories, clusters, certificates, gpgkeys).
• <action>: The action permitted (e.g., get, create, update, delete, sync, override).
• <object>: The resource object scope, formatted as <project>/<application-name> (e.g., default/payment-api). Use wildcards * for broad matching.
• <effect>: The policy enforcement outcome (allow or deny).

Group Binding Format:

g, <name/group>, <role>

• g: Indicates this line defines a group mapping relationship.
• <name/group>: The target user account or external SSO group name (e.g., "company:developers").
• <role>: The target role to bind (e.g., role:developer).

4. Policy Matching Rules and Precedence

When evaluating permissions for a user:

1. Deny Rules Overwrite: Any explicit deny rule matches first, immediately rejecting access regardless of other matching allow rules.
2. Wildcard Resolution: The wildcard symbol * matches any project, resource type, or application name.
3. Hierarchy Evaluation: Roles can inherit permissions from other roles by writing mapping definitions (e.g., g, role:admin, role:developer makes the admin role inherit all developer policies).

5. Troubleshooting RBAC Policy Failures

If users report access failures (e.g., PermissionDenied errors in the console):

Step 1: Query Current ConfigMap Settings

Retrieve the active config data to verify syntax:

kubectl get configmap argocd-rbac-cm -n argocd -o yaml

Step 2: Validate Group Identifiers

Ensure that the group identifier strings matched inside your policy.csv block match the group claims returned by your SSO provider exactly. Check the user details endpoint or authentication logs inside the argocd-server pod:

kubectl logs deployment/argocd-server -n argocd --tail=100 | grep -i oauth

Step 3: Run Policy Diagnostics

Test permissions using the CLI. Run the diagnostic checks using user context permissions:

# Check if a user has access to sync an application
argocd account can-i sync applications "default/payment-api" --username developer-username

6. RBAC Policy Reference Summary

In this section, we covered the core architecture of Role-Based Access Control, configured the policy ConfigMap, analyzed policy rules formatting, and reviewed diagnostic CLI actions.

Now we will transition to built-in system roles. In the next guide, we will cover how to manage read-only, administrator, and project roles.