Accounts and RBAC
Argo CD has no user directory of its own beyond a built-in admin superuser and a short list of local accounts. Everything else (people, teams, automation) is either a local account or an identity from single sign-on. Authentication only proves who the caller is. What the caller may do is decided by Argo CD RBAC, a policy layer that is separate from Kubernetes RBAC.
The admin account
Section titled “The admin account”A standard install creates one account, admin, with unrestricted access through the UI, the CLI, and the API. It exists to bootstrap the platform: evaluate Argo CD, run a single-user setup, or configure accounts and SSO. It should not outlive that work.
Hardening the account takes four steps, in order:
- Read the generated password from the
argocd-initial-admin-secretSecret. - Change it.
- Delete the Secret.
- Disable the account once other administrators exist.
# 1. read the generated passwordargocd admin initial-password -n argocd
# 2. change it (the account flag is optional, it defaults to the logged-in user)argocd account update-password \ --account admin \ --current-password '<initial-password>' \ --new-password '<new-password>'
# 3. remove the now-invalid initial credentialkubectl -n argocd delete secret argocd-initial-admin-secretAnyone who can read Secrets in the argocd namespace can decode the initial password, so steps 2 and 3 matter even on a private cluster. See installation and access for how the password is created.
To disable the account, set admin.enabled to "false" in argocd-cm. Do it after a working replacement exists, either an SSO group bound to role:admin or a local account with administrator rights.
kubectl patch -n argocd cm argocd-cm --type merge \ -p '{"data": {"admin.enabled": "false"}}'Argo CD also throttles password guessing. After 5 failed logins within 300 seconds it rejects further attempts. The ARGOCD_SESSION_FAILURE_MAX_FAIL_COUNT and ARGOCD_SESSION_FAILURE_WINDOW_SECONDS environment variables on argocd-server change both limits.
Local accounts
Section titled “Local accounts”Local accounts serve two purposes: tokens for automation, and a handful of users on a small team where SSO would be overkill. They have no groups and no login history, so larger organizations use SSO instead.
Accounts are declared in argocd-cm with the key accounts.<name>. The value lists the capabilities:
apiVersion: v1kind: ConfigMapmetadata: name: argocd-cm namespace: argocd labels: app.kubernetes.io/part-of: argocddata: accounts.alice: apiKey, login # a human who also scripts against the API accounts.automation: apiKey # a CI pipeline account with no UI access| Capability | Allows |
|---|---|
login | Signing in to the web UI and the CLI with a password |
apiKey | Generating API tokens (JWTs) for the CLI and API |
Usernames are limited to 32 characters. A new account has no password, so it cannot sign in until one is set. List accounts and their state with argocd account list:
NAME ENABLED CAPABILITIESadmin true loginalice true apiKey, loginautomation true apiKeySetting a password
Section titled “Setting a password”Set it with the CLI:
argocd account update-password --account alice --new-password '<new-password>'The command asks for the password of the user who is logged in. To manage it declaratively, store a bcrypt hash and a modification time in argocd-secret:
HASH=$(argocd account bcrypt --password '<new-password>')
kubectl -n argocd patch secret argocd-secret -p "{\"stringData\": { \"accounts.alice.password\": \"$HASH\", \"accounts.alice.passwordMtime\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}}"Disabling and removing accounts
Section titled “Disabling and removing accounts”accounts.<name>.enabled: "false" blocks an account in both the UI and CLI and keeps its definition. Removing the key, or setting it to "true", restores access.
# disablekubectl patch -n argocd cm argocd-cm --type merge \ -p '{"data": {"accounts.alice.enabled": "false"}}'
# delete the account, then its password hashkubectl patch -n argocd cm argocd-cm --type json \ -p '[{"op": "remove", "path": "/data/accounts.alice"}]'kubectl patch -n argocd secret argocd-secret --type json \ -p '[{"op": "remove", "path": "/data/accounts.alice.password"}]'API tokens
Section titled “API tokens”An account with the apiKey capability can generate JSON Web Tokens for pipelines, scripts, and monitoring. Tokens work with the CLI and the API, and they carry the account’s RBAC permissions.
# omit --account to issue a token for the current userargocd account generate-token --account automation --expires-in 90d --id ci-pipelineBy default a token never expires, which makes a leaked token a standing credential. Set --expires-in (for example 1h or 90d) and rotate on a schedule. The --id flag gives the token a recognizable name.
Pass the token with --auth-token or the ARGOCD_AUTH_TOKEN environment variable. Either one overrides any session created by argocd login.
export ARGOCD_AUTH_TOKEN='<token>'argocd account get-user-infoargocd account get --account automation lists the account’s tokens with their IDs, issue times, and expiry:
Name: automationEnabled: trueCapabilities: apiKey
Tokens:ID ISSUED AT EXPIRING AT89ec94b0-aff8-47c6-b59a-229c4b564688 2026-10-20T14:15:16-06:00 2027-01-18T15:15:16-06:0070cf36ea-b365-4f04-9fc0-56229cd41620 2026-10-20T12:39:16-06:00 neverToken metadata is stored in argocd-secret under accounts.<account>.tokens. Revoke a compromised or unused token by ID:
argocd account delete-token --account automation 70cf36ea-b365-4f04-9fc0-56229cd41620Projects can also issue tokens for their own roles, which scopes automation to one team. That mechanism is covered with projects.
The RBAC model
Section titled “The RBAC model”Argo CD authorizes every UI, CLI, and API request with the Casbin library. Policies are CSV lines stored in the argocd-rbac-cm ConfigMap. They govern access to Argo CD resources (Applications, clusters, repositories) and have no effect on what Kubernetes allows. Argo CD RBAC controls who may ask Argo CD to do something. The Kubernetes permissions of the control plane, or of an impersonated service account, control what the sync can then do in the cluster.
Authenticating does not grant privileges. A user needs a role binding, or falls back to the default policy.
Built-in roles
Section titled “Built-in roles”| Role | Access |
|---|---|
role:admin | Unrestricted access to every resource and action |
role:readonly | get on all resources, nothing that changes state. Writes return PermissionDenied |
Policy rules
Section titled “Policy rules”Two rule types exist. A p rule grants or denies a permission. A g rule assigns a user or group to a role.
p, <subject>, <resource>, <action>, <object>, <effect>g, <user-or-group>, <role>- Subject - a role, a local user, or an SSO user or group
- Resource - the kind of thing being accessed
- Action - the operation
- Object - the target name,
*for all. For resources that belong to a project the object is<project>/<name>, so*/*means every Application in every project - Effect -
allowordeny
| Resource | Valid actions | Object |
|---|---|---|
applications | get, create, update, delete, sync, action/..., override | <project>/<app> |
applicationsets | get, create, update, delete | <project>/<name> |
logs | get | <project>/<app> |
exec | create | <project>/<app> |
clusters, projects, repositories | get, create, update, delete | Resource name |
accounts | get, update | Account name |
certificates, gpgkeys | get, create, delete | Name |
extensions | invoke | Extension name |
Some actions need more care than the table suggests:
updateanddeleteon an Application affect the Application object only. To act on its managed resources, use the form<action>/<group>/<kind>/<namespace>/<name>, for exampledelete/*/Pod/*/*. Before 3.0, the plain action also covered sub-resources.action/<group>/<kind>/<action-name>runs a resource action such as restarting a Deployment. A resource in the core API group has an empty group, as inaction//Pod/maintenance-off.overridelets a user sync arbitrary local manifests instead of the configured source. It is a way to bypass Git, so grant it sparingly. Settingapplication.sync.requireOverridePrivilegeForRevisionSync: "true"inargocd-cmtreats syncing to a different revision as an override too.applicationsetscreateeffectively grants the right to create Applications, because the ApplicationSet creates them. The project in the policy object limits which projects those Applications can land in.
Binding a custom role
Section titled “Binding a custom role”A developer role that manages Applications and ApplicationSets and can see the clusters, repositories, and certificates:
p, role:developers, applications, *, */*, allowp, role:developers, applicationsets, *, */*, allowp, role:developers, clusters, get, *, allowp, role:developers, repositories, get, *, allowp, role:developers, certificates, get, *, allow
g, Developers, role:developersg, ArgoCDAdmins, role:adminThe last two lines bind the SSO groups Developers and ArgoCDAdmins to a role. A group needs a g binding before any p rule that names the group directly takes effect, so bind groups to roles and attach policies to the roles.
Evaluation order
Section titled “Evaluation order”- Argo CD checks the default policy first. If the default policy allows or denies the action, evaluation stops there.
- Otherwise it evaluates the policies for the user, then for each group the user belongs to.
- A matching
denyalways wins over anyallow, regardless of line order. Access is granted only if at least oneallowmatched and nodenydid. policy.matchModeselectsglob(the default) orregexmatching. Glob does not treat/as a separator, soaction/extensions/*matches the whole remaining path.
Where the policies live
Section titled “Where the policies live”All global RBAC configuration sits in argocd-rbac-cm:
apiVersion: v1kind: ConfigMapmetadata: name: argocd-rbac-cm namespace: argocd labels: app.kubernetes.io/part-of: argocddata: policy.csv: | g, ArgoCDAdmins, role:admin policy.developers.csv: | # extra file, concatenated after policy.csv p, role:developers, applications, *, */*, allow g, Developers, role:developers policy.authenticated.csv: | p, role:authenticated, projects, get, default, allow policy.default: role:authenticated # custom role with minimal rights (policy.authenticated.csv) policy.matchMode: glob scopes: '[groups, email]'Keys of the form policy.<name>.csv are appended to policy.csv in key order. Splitting policies by team lets Kustomize or Helm overlays add a team’s file without editing a shared one.
Projects can define their own roles in AppProject.spec.roles. Those policies are scoped to one project and are covered with multi-tenancy and projects.
Default policy
Section titled “Default policy”policy.default names the role that every authenticated user receives. It is empty on a fresh install, so a user without a binding can sign in but sees no Applications, projects, or clusters, and the API returns empty lists instead of errors.
Anonymous access
Section titled “Anonymous access”Setting users.anonymous.enabled: "true" in argocd-cm lets unauthenticated requests through with the default policy’s permissions. It suits a public status dashboard. Use a dedicated read-only role as the default for such an instance rather than a role that exposes more than the dashboard needs.
SSO users and groups
Section titled “SSO users and groups”For SSO logins, the subject in a g rule is the user’s identifier or one of the values in the claims named by scopes. The default is [groups], and [groups, email] also matches the email claim. Group claims are read at login, so a membership change takes effect after the user signs in again.
Validating and testing policies
Section titled “Validating and testing policies”A missing comma in policy.csv can lock people out, so check files before applying them. The argocd admin settings rbac commands work on local files, a ConfigMap, or the live cluster.
# syntax checkargocd admin settings rbac validate --policy-file policy.developers.csv# Expected output: Policy is valid
# ask whether a subject may do somethingargocd admin settings rbac can role:developers sync applications 'team-a/orders' \ --policy-file policy.developers.csv# Expected output: YesApply a validated file to the live ConfigMap without replacing other keys:
kubectl create configmap -n argocd argocd-rbac-cm \ --from-file=policy.developers.csv=policy.developers.csv \ --dry-run=client -o yaml | \kubectl patch configmap -n argocd argocd-rbac-cm \ --type merge --patch-file /dev/stdinChanges take effect without restarting argocd-server.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
| A user signs in but sees no Applications | No role binding and an empty policy.default | Bind the user or group to a role, or set a minimal default policy |
permission denied on an action the role seems to allow | A deny rule matches, or the resource and object form is wrong | Test with argocd admin settings rbac can, and check the <project>/<name> object |
| Policies for an SSO group have no effect | The group has no g binding to a role, or scopes does not include the claim holding the group | Add g, <group>, <role> and set scopes to match the provider’s claim |
| New local user cannot sign in | No password set, or login capability missing | Set a password with argocd account update-password and add login |
| Token generation is refused for an account | The account lacks the apiKey capability | Add apiKey to accounts.<name> |
| Login rejected for everyone after repeated typos | Failed-login throttling | Wait out the failure window, or raise the limits on argocd-server |
| API call with a token fails after the CLI login works | ARGOCD_AUTH_TOKEN or --auth-token overrides the session | Unset the variable, or issue a token with the permissions you need |