Skip to content
Documentation Background

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.


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:

  1. Read the generated password from the argocd-initial-admin-secret Secret.
  2. Change it.
  3. Delete the Secret.
  4. Disable the account once other administrators exist.
Terminal window
# 1. read the generated password
argocd 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 credential
kubectl -n argocd delete secret argocd-initial-admin-secret

Anyone 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.

Terminal window
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 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: v1
kind: ConfigMap
metadata:
name: argocd-cm
namespace: argocd
labels:
app.kubernetes.io/part-of: argocd
data:
accounts.alice: apiKey, login # a human who also scripts against the API
accounts.automation: apiKey # a CI pipeline account with no UI access
CapabilityAllows
loginSigning in to the web UI and the CLI with a password
apiKeyGenerating 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 CAPABILITIES
admin true login
alice true apiKey, login
automation true apiKey

Set it with the CLI:

Terminal window
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:

Terminal window
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)\"
}}"

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.

Terminal window
# disable
kubectl patch -n argocd cm argocd-cm --type merge \
-p '{"data": {"accounts.alice.enabled": "false"}}'
# delete the account, then its password hash
kubectl 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"}]'

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.

Terminal window
# omit --account to issue a token for the current user
argocd account generate-token --account automation --expires-in 90d --id ci-pipeline

By 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.

Terminal window
export ARGOCD_AUTH_TOKEN='<token>'
argocd account get-user-info

argocd account get --account automation lists the account’s tokens with their IDs, issue times, and expiry:

Name: automation
Enabled: true
Capabilities: apiKey
Tokens:
ID ISSUED AT EXPIRING AT
89ec94b0-aff8-47c6-b59a-229c4b564688 2026-10-20T14:15:16-06:00 2027-01-18T15:15:16-06:00
70cf36ea-b365-4f04-9fc0-56229cd41620 2026-10-20T12:39:16-06:00 never

Token metadata is stored in argocd-secret under accounts.<account>.tokens. Revoke a compromised or unused token by ID:

Terminal window
argocd account delete-token --account automation 70cf36ea-b365-4f04-9fc0-56229cd41620

Projects can also issue tokens for their own roles, which scopes automation to one team. That mechanism is covered with projects.


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.

RoleAccess
role:adminUnrestricted access to every resource and action
role:readonlyget on all resources, nothing that changes state. Writes return PermissionDenied

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 - allow or deny
ResourceValid actionsObject
applicationsget, create, update, delete, sync, action/..., override<project>/<app>
applicationsetsget, create, update, delete<project>/<name>
logsget<project>/<app>
execcreate<project>/<app>
clusters, projects, repositoriesget, create, update, deleteResource name
accountsget, updateAccount name
certificates, gpgkeysget, create, deleteName
extensionsinvokeExtension name

Some actions need more care than the table suggests:

  • update and delete on an Application affect the Application object only. To act on its managed resources, use the form <action>/<group>/<kind>/<namespace>/<name>, for example delete/*/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 in action//Pod/maintenance-off.
  • override lets a user sync arbitrary local manifests instead of the configured source. It is a way to bypass Git, so grant it sparingly. Setting application.sync.requireOverridePrivilegeForRevisionSync: "true" in argocd-cm treats syncing to a different revision as an override too.
  • applicationsets create effectively 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.

A developer role that manages Applications and ApplicationSets and can see the clusters, repositories, and certificates:

p, role:developers, applications, *, */*, allow
p, role:developers, applicationsets, *, */*, allow
p, role:developers, clusters, get, *, allow
p, role:developers, repositories, get, *, allow
p, role:developers, certificates, get, *, allow
g, Developers, role:developers
g, ArgoCDAdmins, role:admin

The 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.

  • 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 deny always wins over any allow, regardless of line order. Access is granted only if at least one allow matched and no deny did.
  • policy.matchMode selects glob (the default) or regex matching. Glob does not treat / as a separator, so action/extensions/* matches the whole remaining path.

All global RBAC configuration sits in argocd-rbac-cm:

apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-rbac-cm
namespace: argocd
labels:
app.kubernetes.io/part-of: argocd
data:
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.

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.

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.

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.


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.

Terminal window
# syntax check
argocd admin settings rbac validate --policy-file policy.developers.csv
# Expected output: Policy is valid
# ask whether a subject may do something
argocd admin settings rbac can role:developers sync applications 'team-a/orders' \
--policy-file policy.developers.csv
# Expected output: Yes

Apply a validated file to the live ConfigMap without replacing other keys:

Terminal window
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/stdin

Changes take effect without restarting argocd-server.


SymptomLikely causeFix
A user signs in but sees no ApplicationsNo role binding and an empty policy.defaultBind the user or group to a role, or set a minimal default policy
permission denied on an action the role seems to allowA deny rule matches, or the resource and object form is wrongTest with argocd admin settings rbac can, and check the <project>/<name> object
Policies for an SSO group have no effectThe group has no g binding to a role, or scopes does not include the claim holding the groupAdd g, <group>, <role> and set scopes to match the provider’s claim
New local user cannot sign inNo password set, or login capability missingSet a password with argocd account update-password and add login
Token generation is refused for an accountThe account lacks the apiKey capabilityAdd apiKey to accounts.<name>
Login rejected for everyone after repeated typosFailed-login throttlingWait out the failure window, or raise the limits on argocd-server
API call with a token fails after the CLI login worksARGOCD_AUTH_TOKEN or --auth-token overrides the sessionUnset the variable, or issue a token with the permissions you need