Skip to content
Documentation Background

Single sign-on

Local accounts stop scaling once a team grows past a handful of people: each account needs its own password, there are no groups, and offboarding means editing a ConfigMap. SSO moves authentication to the identity provider the organization already runs. Argo CD then needs only to know which groups a user belongs to, and RBAC turns those groups into permissions.


Both options use OpenID Connect (OIDC) between Argo CD and the browser. They differ in what sits between Argo CD and the identity provider.

Bundled DexDirect OIDC
How it worksThe argocd-dex-server Pod acts as an OIDC provider for Argo CD and talks to upstream providers through connectorsargocd-server talks to the OIDC provider itself
Configured index.config in argocd-cmoidc.config in argocd-cm
Choose whenThe provider does not speak OIDC (SAML, LDAP), or you want Dex features such as mapping GitHub orgs and teams to groups, several providers at onceThe provider already exposes OIDC (Keycloak, Okta, Microsoft Entra ID, Google)
Extra PodYes, DexNo
Callback path/api/dex/callback/auth/callback

Configure one of them. When oidc.config is set, Argo CD uses it for login and does not route the web login through Dex. The core install has no API server and no SSO at all, so neither option applies to it.

flowchart LR
    A["Browser"] -->|"1. Log in via SSO"| B["argocd-server"]
    B -->|"2. Redirect to login page"| C["Identity provider"]
    C -->|"3. Redirect back with code"| B
    B -->|"4. Validate ID token, read groups"| D["RBAC policy"]

With Dex, steps 2 and 3 go through Dex, which relays to the real provider and returns a standard token to Argo CD.


Base URL. Set url in argocd-cm to the external address of Argo CD. Argo CD derives the callback URL from it, so a wrong value breaks the redirect. Extra hostnames go in additionalUrls.

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

Client secret. Confidential OIDC clients have a secret. Keep it out of the ConfigMap and reference it. A value starting with $ is resolved in one of two ways:

ReferenceResolves to
$oidc.keycloak.clientSecretThe key oidc.keycloak.clientSecret in the argocd-secret Secret
$keycloak-secret:clientSecretThe key clientSecret in a separate Secret named keycloak-secret

A separate Secret must carry the label app.kubernetes.io/part-of: argocd, or Argo CD does not read it.

Terminal window
kubectl create secret generic -n argocd keycloak-secret \
--from-literal=clientSecret='<client-secret>'
kubectl label secret -n argocd keycloak-secret app.kubernetes.io/part-of=argocd

A Dex connector translates one upstream provider into the standard identity format. List one or more in dex.config:

data:
url: https://argocd.example.com
dex.config: |
connectors:
- type: github
id: github
name: GitHub
config:
clientID: aabbccddeeff00112233
clientSecret: $dex.github.clientSecret # key in argocd-secret
orgs:
- name: your-github-org # restrict login to this org

Do not set redirectURI in a connector. Argo CD fills in the correct callback. Register the provider’s application with https://argocd.example.com/api/dex/callback.

A generic OIDC provider behind Dex needs two extra settings before groups arrive:

- type: oidc
id: keycloak
name: Keycloak via Dex
config:
issuer: https://keycloak.example.com/realms/argocd
clientID: argocd
clientSecret: $keycloak-secret:clientSecret
insecureEnableGroups: true # let Dex pass the groups claim through
scopes:
- profile
- email
- groups

Set getUserInfo: true as well when the provider returns groups only from its UserInfo endpoint. Dex reads groups at login, so a membership change reaches Argo CD only after the user signs in again.


oidc.config is a YAML block inside the ConfigMap:

data:
url: https://argocd.example.com
oidc.config: |
name: Keycloak # label on the login button
issuer: https://keycloak.example.com/realms/argocd
clientID: argocd
clientSecret: $keycloak-secret:clientSecret
requestedScopes: ["openid", "profile", "email", "groups"]
refreshTokenThreshold: 2m # refresh the ID token before it expires

Useful optional keys:

KeyPurpose
requestedIDTokenClaimsAsk the provider to include specific claims, such as {"groups": {"essential": true}}, when it has no groups scope
enableUserInfoGroups, userInfoPath, userInfoCacheExpirationRead groups from the UserInfo endpoint when they are missing from the ID token
enablePKCEAuthenticationUse PKCE, required for CLI login without a client secret
cliClientIDSeparate client ID for the CLI when the provider needs one
logoutURLProvider logout endpoint, may use {{token}} and {{logoutRedirectURL}}
rootCAPEM CA certificate for providers signed by a private CA
allowedAudiencesAccepted aud values. Defaults to the client ID

Set refreshTokenThreshold below the ID token lifetime. If it is longer, Argo CD asks for a new token on every request.

When the provider uses a private CA, supply it with rootCA in oidc.config. Setting oidc.tls.insecure.skip.verify: "true" in argocd-cm turns off certificate checks for all OIDC connections, including to Dex. Use it for throwaway test setups only.


Keycloak exposes OIDC directly, so it works with either method. This walkthrough uses direct OIDC with PKCE, which also enables CLI login. The realm is argocd and the hostnames are keycloak.example.com and argocd.example.com.

In the Keycloak admin console, select the realm and open Clients, then Create client.

  1. Set Client ID to argocd.
  2. Leave Client authentication off. With PKCE the client is public and holds no secret.
  3. Set Root URL and Web origins to https://argocd.example.com, and Home URL to /applications.
  4. Under Valid redirect URIs add:
    • https://argocd.example.com/auth/callback
    • https://argocd.example.com/pkce/verify
    • http://localhost:8085/auth/callback for the CLI
  5. Set Valid post logout redirect URIs to https://argocd.example.com/applications.
  6. In Capability config set PKCE Method to S256.

To use a confidential client instead, switch Client authentication on, copy the secret from the Credentials tab, and reference it as clientSecret in oidc.config. That client works for the browser only. The CLI needs the PKCE variant.

Argo CD reads group membership from a token claim, and Keycloak sends none by default.

  1. Open Client scopes, create a scope named groups.
  2. On its Mappers tab choose Configure a new mapper, then Group Membership.
  3. Set Name and Token Claim Name to groups, and turn Full group path off, so the claim holds ArgoCDAdmins instead of /ArgoCDAdmins.
  4. On the argocd client open Client scopes, choose Add client scope, pick groups, and add it as Default.
  5. Create groups such as ArgoCDAdmins and Developers, and add users to them.
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-cm
namespace: argocd
labels:
app.kubernetes.io/part-of: argocd
data:
url: https://argocd.example.com
oidc.config: |
name: Keycloak
issuer: https://keycloak.example.com/realms/argocd
clientID: argocd
enablePKCEAuthentication: true
refreshTokenThreshold: 2m
requestedScopes: ["openid", "profile", "email", "groups"]
logoutURL: https://keycloak.example.com/realms/argocd/protocol/openid-connect/logout?id_token_hint={{token}}&post_logout_redirect_uri={{logoutRedirectURL}}

The issuer must end with the realm. Keycloak releases before 17 put /auth in front of /realms.

Then map the groups to roles in argocd-rbac-cm:

data:
policy.csv: |
g, ArgoCDAdmins, role:admin
g, Developers, role:developers

The login page now shows a Log in via Keycloak button, and a member of ArgoCDAdmins receives role:admin. Dex-based setups use the same group-to-role mapping.

Make the provider reachable from the cluster

Section titled “Make the provider reachable from the cluster”

argocd-server fetches the provider’s discovery document and signing keys from inside the cluster, so the issuer hostname must resolve there. On a local cluster where the provider is exposed through an ingress with a hostname only your laptop knows, add a CoreDNS rewrite that points the name at the ingress controller Service. On a real cluster use public DNS.


argocd login --sso opens the browser, starts a local web server on port 8085, and receives the login result there. The port is set with --sso-port.

Terminal window
argocd login argocd.example.com --sso --grpc-web
argocd account get-user-info
# Expected output:
# Logged In: true
# Username: [email protected]
# Issuer: https://keycloak.example.com/realms/argocd
# Groups: ArgoCDAdmins

For this to work the provider client must accept the callback http://localhost:8085/auth/callback and must not require a client secret, because a desktop program cannot keep one. PKCE is the safe way to meet both conditions, which is why the Keycloak client above is public with S256. Dex handles this itself: Argo CD registers its CLI and PKCE clients with the bundled Dex, so no extra provider setup is needed beyond the connector.

Add --insecure to the login only when the server uses a self-signed certificate. Behind a gateway that does not pass HTTP/2, --grpc-web is required, as covered in installation and access.


Logging out from the UI or with argocd logout adds the token to a revocation list stored in Redis, so it cannot be reused before it expires. With logoutURL set, the user is also sent to the provider’s logout endpoint to end the SSO session. If the server is unreachable, argocd logout still removes the local token but cannot revoke it on the server.

Group claims are fixed at login. Remove a user from a group and the old group stays in their token until it expires, so keep ID token lifetimes short for sensitive instances.


SymptomLikely causeFix
Redirect error or invalid redirect_uri at the providerThe callback is not registered, or url is wrongRegister <url>/auth/callback (direct) or <url>/api/dex/callback (Dex), and check url in argocd-cm
Login succeeds but the user has no accessThe groups claim is absent or has no g bindingDecode the ID token and check the claim, then add the groups scope and a g rule
Group names have a leading /Keycloak sends the full group pathTurn Full group path off in the mapper
Login loops or returns 401 after a config changeargocd-server holds stale settingsRestart argocd-server, and clear browser cookies
x509: certificate signed by unknown authority in the server logThe provider uses a private CAAdd rootCA to oidc.config
CLI login hangs or the callback failshttp://localhost:8085/auth/callback is not allowed, or the client needs a secretAdd the redirect URI and use a public client with PKCE
CLI login returns a gateway errorResponse headers exceed the proxy bufferRaise the proxy’s header buffer size, since SSO responses carry large headers
Missing parameter: code_challenge_method after moving to PKCEThe Keycloak client does not require S256 yetSet PKCE Method to S256 on the client
Sessions end unexpectedlyrefreshTokenThreshold is longer than the token lifetime, or Dex is in useShorten the threshold. Token refresh does not apply to the Dex web login, so users sign in again when the token expires