Recovering admin access to Argo CD when the password or SSO fails
If you are locked out of the Argo CD UI because the admin password is lost or a bad OIDC or Dex change has broken sign-in, the fix happens from the cluster, not the login screen. Someone with rights to the Argo CD namespace (commonly argocd) and to the Secrets and Deployments in it must make the change with kubectl. Before touching anything, confirm who holds that access, where the Argo CD configuration lives in Git, and whether a working copy of the current argocd-secret and argocd-cm exists, so you can roll back if the reset makes things worse. The Argo CD FAQ describes the two reset paths. The first writes a new bcrypt hash to admin.password in argocd-secret. The second deletes admin.password and admin.passwordMtime and restarts argocd-server, which lets Argo CD regenerate the initial password. The second path fits when no one knows what the password should be. The first fits when you want a known value set deliberately and recorded in your secrets store.
Changing the admin password revokes every existing admin JWT immediately, according to the Argo CD security documentation. That is useful during an incident, since it also cuts off any token a former operator or a leaked automation credential may still hold. It also means CI jobs or scripts that authenticate as admin will fail until you issue them new credentials, so list those dependencies before you rotate. For SSO failures, the admin user is a fallback, not a daily login. The user management guidance says to use the built-in admin user only for initial setup and to set admin.enabled to false once local users or SSO are configured. If your recovery relies on admin, plan to re-enable it only for the repair, then disable it again and record the change.
Repairing a broken OIDC or Dex configuration is usually the slower part. Fix it from the cluster by restoring the last known-good oidc.config or Dex settings in argocd-cm, and check RBAC against the claim Argo CD actually receives, since Argo CD 3.0 Dex-based RBAC uses federated_claims.user_id. Confirm with your identity provider team which settings changed. DeployOpen plans and carries out these recoveries as fixed-scope work inside your cluster, with the scope, the access needed and the verification steps agreed in writing before work starts.
Which recovery path fits your lockout
This table compares the three ways to regain access to Argo CD: writing a new bcrypt hash, deleting the stored admin password, and repairing OIDC or Dex settings. Read each row against your situation to see what changes in the cluster and who loses access. The main takeaway is that the first two paths only restore the local admin account, while the third fixes single sign-on for everyone.
| Path | What it changes | Blast radius | When to choose it |
|---|---|---|---|
| Write a new bcrypt hash to admin.password | Replaces the stored hash in argocd-secret with a hash you generate, then restarts or waits for argocd-server to read it | Local admin login only; all existing admin JWT tokens are revoked immediately | You know the admin account is still enabled and need a known password for break-glass access |
| Delete admin.password and admin.passwordMtime, then restart argocd-server | Removes the stored password fields so Argo CD regenerates the initial admin password on restart | Local admin login only; existing admin tokens are revoked when the password changes | You cannot generate a bcrypt hash easily and the initial secret was never rotated or is still expected to exist |
| Fix OIDC or Dex settings in argocd-cm and argocd-secret | Corrects issuer, client ID, client secret, redirect URL, Dex connector or group mapping values | Every user who signs in through SSO, plus any RBAC rules that depend on group claims | Single sign-on is broken for all users and the local admin account is disabled or unusable |
| Access requirement | Requires cluster access with rights to read and patch secrets and config maps in the Argo CD namespace | Anyone with those rights can change login behavior, so limit and log this access | Confirm who holds cluster-admin or namespace rights before you start any path |
| Verification after the change | Sign in through the UI or CLI and confirm the expected identity and role | Test with a non-admin account to confirm group mapping still applies | Use this check before closing the incident, not only that the login page loads |
| Hardening afterward | Set admin.enabled to false once local users or SSO work, as the user management guide recommends | Reduces the number of standing local credentials | Plan this once recovery is complete so the break-glass path is documented and tested |
| Restart and availability | Restarting argocd-server briefly interrupts API and UI sessions | Short sign-in interruption; sync operations may be affected if the server is busy | Schedule during a quiet window if other teams depend on the UI or CLI |
How to reset the admin password from the cluster
This sequence restores a working administrator login to Argo CD by writing a new password hash into the cluster, restarting the API server, and confirming access before anyone relies on it. It assumes you control kubectl access to the cluster that runs Argo CD.
Confirm cluster access and the Argo CD namespace
The engineer with cluster-admin rights confirms that the current kubectl context points at the cluster that hosts Argo CD, then lists the namespace where it runs. Most installations use the argocd namespace, but yours may differ, so check it before running any other command. Confirm that the argocd-secret Secret and the argocd-server Deployment exist in that namespace. The step is done when both objects return from the cluster and you have recorded the namespace name for the steps that follow.
Back up the current argocd-secret
Before you change anything, export the existing argocd-secret to a file stored outside the cluster, using a restricted location with the same access controls as other cluster secrets. The file holds signing keys and credentials, so treat it as sensitive. This copy lets you roll back if the edit goes wrong. The step is done when the exported file exists, is readable only by the operator, and you can list its keys.
Generate a bcrypt hash for the new password
Create a bcrypt hash of the new admin password on a workstation you trust, using a tool your team already approves for this purpose, such as the Argo CD CLI or a standard bcrypt utility. Keep the plain-text password out of shell history and out of tickets. The output is a hash string beginning with a bcrypt prefix. The step is done when you have a hash and have confirmed it starts with that prefix, so the value you write into the Secret is in the format Argo CD expects.
Write the hash to admin.password
Patch the admin.password key in argocd-secret with the bcrypt hash, and set admin.passwordMtime to the current time in RFC 3339 format so Argo CD records when the password changed. Alternatively, you can delete admin.password and admin.passwordMtime from the Secret, which makes Argo CD generate a new initial password on restart, as described in the Argo CD FAQ. Patching the hash keeps the password you chose. The step is done when kubectl shows the updated key names in the Secret without printing the values.
Restart argocd-server to load the change
Restart the argocd-server Deployment so it reads the updated Secret. Wait until the rollout reports that all replicas are available. Restarting only the server is sufficient for the admin credential, and the application controller and repo-server keep running. The step is done when the rollout completes without errors and the pods show Ready. Expect existing admin sessions to stop working at this point, because the Argo CD security documentation says that changing the admin password immediately revokes all existing admin JWT tokens.
Log in as admin with the new password
Open the Argo CD web interface or use the CLI to log in as the admin user with the password you set. If you removed the password fields instead, use the initial password generated by Argo CD, then change it immediately. Confirm that the login succeeds and that you can list applications and projects. The step is done when an authenticated session returns the application list. If login fails, check that the hash prefix is intact, that argocd-server restarted, and that you are not connecting to a stale endpoint.
Verify SSO and disable the admin user
Test a login through your configured SSO provider and confirm that an account in the administrator group receives the expected role. Once you have a working local or SSO administrator, the Argo CD user management documentation recommends disabling the built-in admin user by setting admin.enabled to false. Make sure your recovery path, including the saved Secret backup and documented cluster access, is recorded before you disable it. The step is done when the SSO administrator can perform a read and a sync action, and the admin user is disabled in argocd-cm.
Security risks when you reset admin access
Resetting the admin password is a cluster-level operation, so the risk sits in who can reach the cluster and what the reset touches. The cards below cover the controls that determine whether a recovery leaves the system in a safer state than it started.
Cluster access is the real gate
Anyone who can read or write the argocd-secret Secret in the Argo CD namespace can set a new admin hash, so the password reset is only as strong as cluster RBAC. Before a recovery, confirm which engineers and service accounts hold get, patch and update rights on that Secret. Remove standing rights afterward and record who used them.
Password reset revokes admin tokens
When the admin password changes, all existing admin JWT tokens are revoked immediately. This helps after a suspected leak, but it also interrupts any CI job or script that uses an admin token. Check which automation depends on admin tokens and plan replacement tokens from a non-admin account before you rotate.
Disable the admin account after recovery
The user management guidance is to use the built-in admin user only for initial setup. Once local users or SSO work, set admin.enabled to false in argocd-cm so password logins for admin stop being an entry point. Confirm first that at least one named user holds a role that can manage RBAC.
API access uses JWTs only
Argo CD authenticates API requests only with JSON Web Tokens, so a recovered password does not create a separate API key path. Review which tokens exist for accounts and automation after recovery, and expire or delete tokens that no longer have an owner. Treat any token copied into a script as a credential.
Credentials stay out of logs
Argo CD redacts cluster, Git and OAuth2 credentials from API responses and logs, which lowers exposure during troubleshooting. That protection does not cover what you paste yourself. Never place a new password, bcrypt hash or token in a ticket, chat thread or runbook. Share a pointer to the vault entry instead.
Keep an audit trail of the reset
A direct edit to argocd-secret may not appear in Argo CD's own activity views, so confirm what your cluster audit logs record for Secret writes and deployment restarts. Ask your platform team which API server audit policy covers the namespace and where those events are retained. Record the time, operator and reason in your change system.
Fixing a broken OIDC or Dex configuration from the cluster
A broken SSO change locks out every user who signs in through it, and the admin fallback is often the only way back in. A wrong issuer URL, a rotated client secret, a redirect URL that does not match the identity provider, or a malformed Dex connector in the argocd-cm ConfigMap each stop logins at the same point. Before you change any SSO setting, confirm that the built-in admin user is enabled and that you can reach it with a known password. The user management documentation recommends keeping admin.enabled as a setup-only fallback until local users or SSO are working, and disabling it only after that is proven. If you disable admin first and the SSO change is wrong, recovery means editing cluster objects directly, which is the path this section is designed to avoid.
When SSO is broken, work from the cluster rather than through the UI. Start by checking the current oidc.config or dex.config value in argocd-cm and comparing the issuer, client ID and redirect URL with what the identity provider lists for the Argo CD application. The client secret lives in argocd-secret, so a secret rotated on the identity provider side must be written back there as well, and the argocd-server pods restarted so they reload it. If the change came from Git, the faster and safer fix is usually to revert the commit in the source repository and let the sync restore the previous argocd-cm values. Keep in mind that any manual edit you make in the cluster will be overwritten the next time Argo CD syncs that object from Git, so record the change and fix the source of truth afterward. Confirm the exact Dex or OIDC keys for your Argo CD version against the user management documentation before editing.
Recovery is not finished when logins work again. In Argo CD 3.0, Dex-based RBAC matches on the federated_claims.user_id claim instead of the earlier user identifier, and the 3.0 upgrade notes describe the change. If your policy.csv or group mappings were written against an older claim, a user may sign in successfully and still receive no role, or lose access they had before. Sign in as a test user from each group, check the effective permissions for an application in each project, and confirm that update, delete and logs permissions behave as the policy intends. Document which claim each group mapping depends on, and keep the admin fallback enabled until that check passes.
What to confirm before you touch argocd-secret
Editing argocd-secret or argocd-cm on a live installation changes how people sign in and how Argo CD reads its own configuration. Confirm the points below first, because the answers decide whether your change will hold, whether it can be rolled back and which key names you should actually edit.
Installed version and support line
Confirm the exact Argo CD version running in the cluster, not the version in your runbook. The project patches only the three most recent minor versions, so an older line may no longer receive fixes. Check whether your install sits on a supported minor line before you rely on documented behavior for that release. If it does not, plan an upgrade alongside the recovery rather than after it.
Whether GitOps manages the Argo CD install
If Argo CD manages its own manifests from Git, a manual change to argocd-secret or argocd-cm may be reverted on the next sync. Find the Application that owns the Argo CD namespace and check its sync policy. Either pause automated sync for that application for the duration of the fix or make the change in the Git source so it survives. Record which path you chose.
Backups of argocd-secret and argocd-cm
Export argocd-secret and argocd-cm to a secure location before you edit either object. argocd-secret holds the server signing key and the admin password hash, so the backup is sensitive and needs the same access controls as the cluster itself. Without a copy you cannot compare the before and after state or restore the original settings if the change breaks SSO for other users.
Exact key names in your install
Read the live keys with kubectl before writing any value. Confirm that the admin password hash lives under admin.password and that the password change timestamp is stored as admin.passwordMtime. Confirm the admin.enabled setting in argocd-cm and the OIDC or Dex settings you plan to correct. Key names differ between installs that were built from custom manifests, so do not copy names from a sample without checking them against your own object.
Repository definitions stored as Secrets
Since Argo CD 3.0, repositories must be defined as Kubernetes Secrets rather than in argocd-cm. Confirm that your repository credentials are in Secrets before you edit argocd-cm during recovery. If you find repository entries still in the ConfigMap on your version, treat that as a sign that the install was not upgraded cleanly and review it with the upgrade notes before changing anything.
Who can reach the cluster and the admin path
Confirm which people hold cluster-admin or equivalent access and who can reach the Argo CD API or UI through a local route. Recovery usually relies on kubectl access to the cluster, not on the web login, so confirm that at least two people can reach the control plane if one credential fails. Also confirm which team approves the change, because a reset of the admin password immediately revokes existing admin tokens.
Questions teams ask before recovering Argo CD access
Do we need outside help to recover Argo CD admin access?
Not always. If you have a cluster administrator who can read and write the argocd-secret Secret and restart argocd-server, the password reset itself is a short procedure. Outside help is worth considering when the cluster is shared, the change must follow a formal approval path, or nobody on your team has done this before. The effort depends less on the password and more on what else is broken: a misconfigured OIDC block, an RBAC policy that locked out every group, or an unknown state left by a previous attempt. Ask any partner to list which of these checks they will perform and what they will leave for your team to run again later.
How long does recovering Argo CD access usually take?
It depends on two things: how much access you still have and how far the configuration has drifted from what is in Git. If a cluster administrator is available and the fault is a forgotten password, the reset is a matter of minutes once the change is approved. If the SSO settings were edited directly in the cluster and nobody recorded them, the work includes reconstructing the intended state and checking it against the repository. No duration figure is supplied for this work, so ask for a time estimate in writing that names the access you already have and the systems you need to review.
What does recovery need from our team?
Plan for three inputs before anyone touches the cluster:
- Cluster administrator access with permission to read and update the
argocd-secretSecret, theargocd-cmandargocd-rbac-cmConfigMaps, and the Argo CD deployments. - A change window agreed with the teams whose applications sync through this instance, since a restart of
argocd-serverinterrupts logins and may pause automated work. - A recent backup of the Argo CD namespace, including Secrets and ConfigMaps, so the previous state can be restored if the fix goes wrong.
Also confirm who can approve the change and who will check the result from the user interface.
Will a self-managed Argo CD revert our manual edits to the admin settings?
It can, and this is the most common reason recovery does not stick. If Argo CD manages its own configuration from Git, a manual change to argocd-cm or argocd-rbac-cm made in the cluster may be overwritten at the next sync. The same applies to a password change if the Secret is part of a managed manifest. Before editing, check whether the relevant objects are tracked by an application and whether self-management is enabled. Fix the source in Git first, then let the sync apply it, so the recovered state survives the next reconciliation.
What happens to existing sessions when we reset the admin password?
Changing the admin password revokes all existing admin JWT tokens immediately, according to the Argo CD security documentation. Any automation or user session that relies on an admin token will stop working and must be issued a new token after the change. Plan that impact into the change window, and check whether any pipelines authenticate as admin before you rotate the password.
How do we avoid getting locked out of Argo CD next time?
Keep at least one recovery path that does not depend on the SSO provider you are trying to fix. The Argo CD user management documentation recommends using the built-in admin user only for initial setup and disabling it with admin.enabled set to false once local users or SSO are configured, so you must decide whether to keep a break-glass account enabled. Store the procedure, the account owner and the location of the recovery credentials in your runbooks, test the SSO settings in a non-production instance, and keep the configuration in Git so a broken change can be reverted with a commit.
Can DeployOpen take on admin access recovery as a fixed-scope task?
Yes. Most DeployOpen engagements are fixed-scope, with the scope, deliverables and timelines agreed in writing before work starts. A typical written scope for this task would cover reviewing the current argocd-secret, argocd-cm and argocd-rbac-cm state, restoring access through an approved change, reconciling the settings with Git, and documenting the break-glass procedure for your team. DeployOpen does not publish a price list, so a quote follows from that written scope. Ask for the deliverables, the access you must grant, and what remains your responsibility after the work closes.
Preventing the next lockout
The most effective protection against a repeat lockout is a tested way back in that does not depend on SSO working. Argo CD's user management guidance recommends using the built-in admin user only for initial setup and then disabling it by setting admin.enabled to false once local users or SSO are configured. Before you disable it, confirm that at least one named person can log in through your identity provider and that someone with cluster access can run the recovery steps from the previous section without help from the team that configured SSO. Write down who holds that path, where the break-glass kubeconfig lives, and how access is granted and revoked. Treat the admin disable step as a dated change in your runbook, and confirm with your own change process when it should happen relative to the SSO rollout.
Test every SSO change in a non-production Argo CD instance that uses the same identity provider tenant or a realistic copy of its settings, including the group claims and Dex connector or direct OIDC configuration you plan to use in production. Changes to argocd-cm and argocd-rbac-cm are easy to make and hard to validate from the UI once a bad setting has locked out every role. Keep a copy of argocd-secret and argocd-cm in your backup set, stored with the same protection as other cluster secrets, so you can restore known-good configuration quickly. Because argocd-secret holds the admin password hash and signing material, treat those backups as sensitive. Confirm with your platform team how often these objects are captured and whether a restore has ever been rehearsed.
Review who holds cluster-admin rights on the Argo CD namespace and on the clusters Argo CD manages at least once a quarter, because anyone with write access to argocd-secret or the Argo CD namespace can reset the admin password without going through the UI. Check that Argo CD's own RBAC policy grants admin-level roles only to the groups you intend, and that automation accounts are scoped to the projects they need. Record each review with the date, the reviewer and the changes made, since that record is also useful evidence for access reviews. Ask your team to confirm the current admin status, the number of people who can read or write Kubernetes Secrets in that namespace, and whether anyone outside the platform group can exec into the Argo CD pods.
How DeployOpen recovers and hardens Argo CD access
DeployOpen approaches admin access recovery as a planned change to your cluster, not an improvised fix. We scope the recovery path against your SSO setup and cluster access, build and test it in your own infrastructure, and document the steps so your team can repeat them. Engagements are fixed-scope, and ongoing support is available as a retainer.
How we scope
- Written scope lists which Argo CD instances, namespaces and identity settings are covered by the recovery work.
- We confirm who holds cluster-admin access and how break-glass access is granted and logged today.
- Scope records the identity provider, Dex or direct OIDC setup, and any group-to-role mappings in use.
How we build
- We reproduce the lockout in a non-production copy and test the admin password reset path first.
- We verify OIDC issuer, client ID, redirect URL and group claim settings directly from the cluster configuration.
- We set admin.enabled and local user settings to match the access model agreed in the written scope.
How we hand over
- You receive a runbook covering password reset, token revocation and OIDC fixes, written for your own operators.
- Each step lists the Kubernetes objects changed, the expected result and the check that confirms access works.
- We walk your platform team through a recovery drill so the procedure is tested by the people who will run it.
How we support
- Ongoing support and upgrades are available as a retainer after handover, covering Argo CD patch releases.
- We can rerun access checks after identity provider changes, certificate rotations or Argo CD upgrades.
- Continuous security testing of the Argo CD installation can be added to a retainer if your team wants it.
