Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 37 ยท Security and RBAC

SSO and Authentication: OIDC, Dex and the Admin Account

Set up single sign-on for Argo CD with Dex or native OIDC, map groups to roles, retire the admin account and use API tokens safely for automation.

A fresh Argo CD install has a single local admin user with a generated password. That is fine for the first hour. After that, people should sign in through your identity provider (IdP), so access follows your company's joiners, leavers and group memberships. This lesson covers the options and the secure steps around them.

Authentication versus authorization

  • Authentication answers "who are you?". It comes from local accounts or SSO.
  • Authorization answers "what may you do?". It is done by RBAC policies, usually keyed on the groups in your SSO token.
sequenceDiagram
  participant U as Browser
  participant A as Argo CD server
  participant I as Identity provider
  U->>A: Open /auth/login
  A->>U: Redirect to IdP
  U->>I: Sign in
  I->>U: Redirect with code
  U->>A: /auth/callback?code=...
  A->>I: Exchange code for ID token
  A->>U: Session cookie (claims: email, groups)

The authorization code flow, as Argo CD uses it. Groups arrive in the ID token.

The first-time admin password

On first install the password is in a Secret:

Terminal
argocd admin initial-password -n argocd
argocd login argocd.example.com --username admin
argocd account update-password

After you change it, delete the initial Secret: kubectl delete secret argocd-initial-admin-secret -n argocd. Then plan to disable the account entirely once SSO works.

The external URL

SSO needs to know the public address of the UI, because it builds redirect URLs from it. Set it in argocd-cm:

YAML
data:
  url: https://argocd.example.com

A wrong url is the most common cause of "redirect URI mismatch" errors. The same URL plus /auth/callback must be registered as the redirect URI in your IdP.

Option 1: native OIDC

Use this when your IdP speaks OpenID Connect directly (Okta, Entra ID, Google Workspace, Keycloak, Auth0 and others):

YAML
# argocd-cm
data:
  url: https://argocd.example.com
  oidc.config: |
    name: Company SSO
    issuer: https://idp.example.com/realms/main
    clientID: argocd
    clientSecret: $oidc.company.clientSecret
    requestedScopes: ["openid", "profile", "email", "groups"]

The $oidc.company.clientSecret reference means the value comes from a key in the argocd-secret Secret, so no secret is in the ConfigMap. Many IdPs need a custom "groups" claim configured on their side; if groups are missing in the token, RBAC mappings silently match nothing. Check what the server sees with the argocd account get-user-info command after login.

Option 2: Dex

Argo CD bundles Dex, an identity broker. Dex lets you connect providers that are not OIDC-native (GitHub, GitLab, LDAP, SAML 2.0) and presents them to Argo CD as one OIDC source:

YAML
data:
  url: https://argocd.example.com
  dex.config: |
    connectors:
      - type: github
        id: github
        name: GitHub
        config:
          clientID: $dex.github.clientID
          clientSecret: $dex.github.clientSecret
          orgs:
            - name: my-org

With GitHub, groups are org:team strings, which is why the RBAC examples use my-org:shop-devs. If you use only OIDC and do not need Dex, you can scale the Dex server down to save resources.

Native OIDC Dex
Moving parts Fewer One more component
Providers OIDC compliant GitHub, LDAP, SAML and OIDC
Group claims Whatever the IdP issues Normalized by the connector

Logging in from the CLI

Terminal
argocd login argocd.example.com --sso

This opens a browser for the same flow. In CI do not use a person's session. Use a project role token or a local apiKey account with a narrow policy and an expiry.

Local accounts and tokens

YAML
# argocd-cm
data:
  admin.enabled: "false"
  accounts.ci-deploy: apiKey
Terminal
argocd account generate-token --account ci-deploy --expires-in 24h

Grant the account only what it needs in argocd-rbac-cm, for example p, ci-deploy, applications, sync, shop/*, allow. Tokens can be revoked by deleting them (argocd account delete-token).

Hardening checklist

  • Terminate TLS in front of Argo CD and use https in url.
  • Disable admin after SSO works, keep a documented break-glass procedure.
  • Set policy.default to empty and map groups explicitly.
  • Keep session lifetimes reasonable (users.session.duration in argocd-cm; the default is 24 hours).
  • Use IdP-side MFA and conditional access; Argo CD itself has no password policy for local users.
  • Rate limiting for failed logins exists (login.attempts); keep it enabled.

Stand-in: mapping token claims to roles

The next stand-in takes decoded token claims, the scopes setting and group mappings, and shows why a missing groups claim means no roles.

Python Stand-in: claims to roles

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why must the url field in argocd-cm be correct for SSO?

    A wrong url produces redirect URI mismatch errors at login.
  2. 2. When is Dex the better choice than native OIDC?

    Dex translates non-OIDC providers into OIDC for Argo CD.
  3. 3. Users sign in successfully but have no permissions. A likely cause?

    RBAC maps groups from the token; if they are absent, only policy.default applies.
  4. 4. What should a CI pipeline use to call the Argo CD API?

    Use a project role token or an apiKey account with minimal RBAC rights.

Summary

  • Authentication comes from SSO or local accounts; RBAC then authorizes by group.
  • Set url, then configure native OIDC or Dex; keep secrets in argocd-secret.
  • Disable the admin account after SSO works and delete the initial password Secret.
  • Automation uses expiring, narrowly scoped tokens.

Next: Secrets in GitOps