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.
Two ways to connect
Section titled “Two ways to connect”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 Dex | Direct OIDC | |
|---|---|---|
| How it works | The argocd-dex-server Pod acts as an OIDC provider for Argo CD and talks to upstream providers through connectors | argocd-server talks to the OIDC provider itself |
| Configured in | dex.config in argocd-cm | oidc.config in argocd-cm |
| Choose when | The provider does not speak OIDC (SAML, LDAP), or you want Dex features such as mapping GitHub orgs and teams to groups, several providers at once | The provider already exposes OIDC (Keycloak, Okta, Microsoft Entra ID, Google) |
| Extra Pod | Yes, Dex | No |
| 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.
Settings every SSO setup needs
Section titled “Settings every SSO setup needs”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.comClient 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:
| Reference | Resolves to |
|---|---|
$oidc.keycloak.clientSecret | The key oidc.keycloak.clientSecret in the argocd-secret Secret |
$keycloak-secret:clientSecret | The 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.
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=argocdDex connectors
Section titled “Dex connectors”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 orgDo 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 - groupsSet 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.
Direct OIDC
Section titled “Direct OIDC”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 expiresUseful optional keys:
| Key | Purpose |
|---|---|
requestedIDTokenClaims | Ask the provider to include specific claims, such as {"groups": {"essential": true}}, when it has no groups scope |
enableUserInfoGroups, userInfoPath, userInfoCacheExpiration | Read groups from the UserInfo endpoint when they are missing from the ID token |
enablePKCEAuthentication | Use PKCE, required for CLI login without a client secret |
cliClientID | Separate client ID for the CLI when the provider needs one |
logoutURL | Provider logout endpoint, may use {{token}} and {{logoutRedirectURL}} |
rootCA | PEM CA certificate for providers signed by a private CA |
allowedAudiences | Accepted 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.
Walkthrough: Keycloak
Section titled “Walkthrough: Keycloak”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.
Create the client
Section titled “Create the client”In the Keycloak admin console, select the realm and open Clients, then Create client.
- Set Client ID to
argocd. - Leave Client authentication off. With PKCE the client is public and holds no secret.
- Set Root URL and Web origins to
https://argocd.example.com, and Home URL to/applications. - Under Valid redirect URIs add:
https://argocd.example.com/auth/callbackhttps://argocd.example.com/pkce/verifyhttp://localhost:8085/auth/callbackfor the CLI
- Set Valid post logout redirect URIs to
https://argocd.example.com/applications. - 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.
Add a groups claim
Section titled “Add a groups claim”Argo CD reads group membership from a token claim, and Keycloak sends none by default.
- Open Client scopes, create a scope named
groups. - On its Mappers tab choose Configure a new mapper, then Group Membership.
- Set Name and Token Claim Name to
groups, and turn Full group path off, so the claim holdsArgoCDAdminsinstead of/ArgoCDAdmins. - On the
argocdclient open Client scopes, choose Add client scope, pickgroups, and add it as Default. - Create groups such as
ArgoCDAdminsandDevelopers, and add users to them.
Configure Argo CD
Section titled “Configure Argo CD”apiVersion: v1kind: ConfigMapmetadata: name: argocd-cm namespace: argocd labels: app.kubernetes.io/part-of: argocddata: 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:developersThe 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.
Logging in from the CLI
Section titled “Logging in from the CLI”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.
argocd login argocd.example.com --sso --grpc-webargocd account get-user-info
# Expected output:# Logged In: true# Username: [email protected]# Issuer: https://keycloak.example.com/realms/argocd# Groups: ArgoCDAdminsFor 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.
Logout and token lifetime
Section titled “Logout and token lifetime”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.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
Redirect error or invalid redirect_uri at the provider | The callback is not registered, or url is wrong | Register <url>/auth/callback (direct) or <url>/api/dex/callback (Dex), and check url in argocd-cm |
| Login succeeds but the user has no access | The groups claim is absent or has no g binding | Decode 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 path | Turn Full group path off in the mapper |
| Login loops or returns 401 after a config change | argocd-server holds stale settings | Restart argocd-server, and clear browser cookies |
x509: certificate signed by unknown authority in the server log | The provider uses a private CA | Add rootCA to oidc.config |
| CLI login hangs or the callback fails | http://localhost:8085/auth/callback is not allowed, or the client needs a secret | Add the redirect URI and use a public client with PKCE |
| CLI login returns a gateway error | Response headers exceed the proxy buffer | Raise the proxy’s header buffer size, since SSO responses carry large headers |
Missing parameter: code_challenge_method after moving to PKCE | The Keycloak client does not require S256 yet | Set PKCE Method to S256 on the client |
| Sessions end unexpectedly | refreshTokenThreshold is longer than the token lifetime, or Dex is in use | Shorten the threshold. Token refresh does not apply to the Dex web login, so users sign in again when the token expires |