Keycloak and Argo CD SSO integration

The first decision in this integration is whether the Keycloak client for Argo CD is confidential, which means it holds a client secret, or public, which means it uses PKCE and has no secret. A confidential client suits the Argo CD web UI, because the Argo CD API server completes the OpenID Connect code exchange on the server side and can keep the secret out of the browser. A public client using PKCE removes the secret from the picture, but the argocd command-line tool must sign in through a browser flow and then hold the resulting tokens on the workstation. Argo CD's user management documentation describes the OIDC integration options, so confirm in the current Argo CD operator manual which client settings the CLI flow requires before you choose.

The trade-off is operational. A client secret has to be created in Keycloak, stored in Kubernetes (Argo CD reads it from its configuration rather than from the Argo CD ConfigMap in plain form), and rotated on a schedule your security team approves. Every rotation touches the Keycloak client, the Kubernetes secret and a restart or reload of the component that reads it, so the runbook should name the owner, the change window and the verification step. Keep the secret out of Git repositories and out of Argo CD Applications that it manages, since a GitOps tool that deploys its own login credentials creates a circular dependency during recovery.

A PKCE client removes the secret to rotate, but it moves the risk into redirect URI and login design. Keycloak only redirects to URIs listed in the client configuration, so each allowed value must be exact: the Argo CD UI callback, and any local callback the CLI uses on a loopback port. Avoid wildcard redirect URIs for an identity provider that controls access to deployment tooling. Decide also how CLI users will obtain access in practice, including whether they sign in from managed laptops only, how tokens expire, and how you will revoke a session when an engineer leaves. Test the CLI login from a workstation that matches your standard image, not only from an administrator's machine.

Before deciding whether one client can serve both the UI and the CLI, check the current Argo CD documentation for the exact client and CLI configuration in the version you run, because the supported pattern can change between releases. If the documentation supports one client for both, you keep a single set of redirect URIs and one lifecycle to manage. If it requires separate clients, you will have two configurations to review, two sets of redirect URIs and possibly two audit trails. Record the decision with the Argo CD version it was tested against, and rerun the sign-in test for the UI and the CLI after every Argo CD upgrade.

Argo CD cannot apply group-based RBAC unless the token it receives carries a groups claim that lists the user's Keycloak groups. A group membership mapper has to be configured on the Keycloak client, because the claim does not appear on its own. The mapper settings determine the claim name, the token where the claim lands (ID token, access token or userinfo) and the form of each group value. Treat these settings as part of the Argo CD RBAC design, since the policy file refers to them directly, and record them in the same change that adds the policy.

Two things must match exactly. The claim name in the Keycloak mapper must equal the claim name Argo CD is configured to read, and each group value in the token must equal the string the RBAC policy references. With the full group path option enabled, nested groups are emitted as paths such as /platform/argocd-admins, so a policy line that uses argocd-admins alone will never match. Choose full path or short name once, document the choice, and verify it with a real user before writing the policy. Confirm in your Argo CD version's documentation whether group matching is case-sensitive.

Argo CD requests scopes at login, and the groups claim only arrives if the requested scopes include the client scope that holds the mapper. Check the scopes and requested claims keys in the Argo CD OIDC configuration and in the user management documentation for your version, then confirm that the Keycloak client scope containing the mapper is assigned to the Argo CD client. A mapper placed on a scope the client never requests produces tokens that look correct in the Keycloak admin console but carry no groups when Argo CD receives them. Decode a test token to confirm what is actually sent.

The main risk is a groups claim that is missing for some users, not for all. Users with no group membership, users whose sessions predate a group change, and local or service accounts may arrive without the claim. Argo CD then evaluates those users against its default policy, which may grant little or no access. Decide in advance what an unassigned user should see, and test at least one user with no groups alongside a user in the intended group. Confirm how the default policy is set in your deployment before you rely on it.

Version also determines which user identity claim the policy uses. The Argo CD 3.0 upgrade notes say Dex-based RBAC now uses the federated_claims.user_id claim. That note applies when sign-in runs through the bundled Dex. If Keycloak is connected directly as an OIDC provider, confirm which claim names apply to your version before writing the policy, and check the groups claim name in a test login instead of assuming the Dex example carries over. Repeat that check after every Argo CD upgrade.

Before you point Argo CD at Keycloak for everyone, run a verification plan that proves each RBAC role behaves the way you designed it. The plan should use separate test users, one per role you mapped from Keycloak groups to Argo CD RBAC, plus a user who belongs to no group at all. Testing with a single administrator account proves little, because that account often bypasses the mappings you are trying to validate. Each test user should be a normal Keycloak user placed in exactly the groups the design assigns, so the groups claim Argo CD receives matches what production will send.

Cover the login paths separately. First, sign in through the web UI and confirm the user lands in the expected view. Second, if you chose a client configuration that supports the argocd CLI, run an argocd login with that user and confirm the CLI session works. The CLI path is where client type decisions show up in practice, so test it as a distinct case rather than assuming the browser result carries over. Third, sign in as the user in no group and confirm access is denied. Fourth, sign in as a user who should see only one project and confirm that project is visible and the others are not. Fifth, confirm the built-in admin account is disabled by attempting to log in with it and checking that the setting you chose, not a leftover password, controls access.

Negative tests matter more than the happy path. Expire a session, or shorten the token lifetime in a test setting, and confirm Argo CD asks the user to sign in again rather than continuing with stale rights. Then remove a test user from its Keycloak group and confirm the change takes effect. Be precise about what you observe: a token already issued may still carry the old groups claim until it expires, so record how long the old access persists and whether your operating model accepts that window. Do not assume the change is instant because the group was removed in Keycloak.

Record the expected result for every case before running it: the user, the login method, the action attempted, the expected outcome and the observed outcome. A written matrix lets an auditor or a second engineer repeat the test and lets you see drift when a later Keycloak or Argo CD upgrade changes behavior. Keep the test accounts and groups in a non-production realm if your environment has one, so test data never mixes with real workforce identities and the test users can be deleted cleanly afterward. If you only have one realm, confirm with your identity team how test accounts will be labeled, restricted and removed before they are created.

Confirm the Argo CD and Keycloak versions you are testing against, and repeat the matrix after any upgrade to either product. Argo CD's user management guidance and its RBAC behavior have changed across releases, so the test results only apply to the versions tested. Ask whoever runs the cutover to sign off on the matrix and to keep it with the change record, because the evidence is what proves the integration was verified before production users depended on it.