ArgoCD Keycloak Integration

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up an argocd keycloak integration by linking both tools through OpenID Connect. This link lets your team log in to ArgoCD using their central Keycloak accounts. Most platform teams start by creating a client inside Keycloak and sharing its secret. They then map Keycloak user groups to broad admin or read roles in ArgoCD. When those roles are too wide, one bad click can break live apps. How an argocd keycloak integration works The login flow starts when a user opens the ArgoCD web page

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

You set up an argocd keycloak integration by linking both tools through OpenID Connect. This link lets your team log in to ArgoCD using their central Keycloak accounts. Most platform teams start by creating a client inside Keycloak and sharing its secret. They then map Keycloak user groups to broad admin or read roles in ArgoCD. When those roles are too wide, one bad click can break live apps.

How an argocd keycloak integration works

The login flow starts when a user opens the ArgoCD web page or CLI. ArgoCD sends the user straight to the Keycloak login screen to check their identity. The user enters their password and passes any extra checks set up in Keycloak. Once Keycloak confirms who the user is, it builds a signed token for them.

This token holds the user identity, email, and a list of their team groups. Keycloak sends the user back to ArgoCD along with this new signed token. ArgoCD checks the token signature against the public keys from the Keycloak server. This step proves that the token is real and was not changed in transit.

Next, the ArgoCD role engine reads the group names listed inside that user token. Platform admins write policy rules in ArgoCD that match group names to specific permissions. For example, a rule can give the dev group read access to test apps. Another rule can give the ops group full write power over all cluster projects. If a user belongs to several groups, ArgoCD merges all of their allowed actions.

How group mapping works in practice

Keeping group names clean is the most important part of this whole setup process. You first create clear group names in Keycloak that match your real team structure. Then you configure the client mapper in Keycloak to put groups into the token. Without this mapper step, ArgoCD will know who logged in, but not their groups.

When a user leaves the company, you remove their account inside the Keycloak tool. That single action blocks their login to ArgoCD as well as other linked apps. You do not need to hunt down local user accounts across ten different clusters. When a developer moves to a new team, you just update their Keycloak group. The next time they log in, ArgoCD reads the new group and updates access.

Keycloak + ArgoCD Security: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native role mapping solves and what it misses

Central login stops teams from sharing one static admin password across the whole group. It gives you one place to turn off access when someone leaves a team. Role rules in ArgoCD also let you split permissions by project or by app. You can let developers view app status while blocking them from deleting core services.

Yet this native setup only checks who can log in and hold a role. Once a user has a broad write role, they keep that power all day. A developer with sync or delete rights can run risky actions at any time. Native role checks do not pause a bad delete command for a quick review.

Also, teams often need direct command line or database access when an app fails. ArgoCD role rules do not govern what engineers run inside a pod or database. They cannot mask emails, phone numbers, or card numbers in live query results. To control each action in flight, teams must add fine controls at the action level.

Govern kubectl and API calls in flight

Identity providers and Kubernetes RBAC decide who logs into a cluster. They cannot redact keys inside returned JSON objects or hold a risky delete call for review. By design, hoop.dev runs as an open-source proxy, a sidecar for your Kubernetes API, checking requests and responses without replacing RBAC.

First, hoop.dev guardrails refuse banned methods, paths, or headers before they run. Next, hoop.dev data masking rewrites sensitive keys in returned Secret, ConfigMap, and log responses in memory, and writes each decision to the audit trail. Explore the repo on GitHub.

Frequently asked questions

Do I need the built-in Dex server for Keycloak login?

No, you can link ArgoCD straight to Keycloak using standard OpenID Connect settings. You only need the built-in Dex tool if your identity source lacks OIDC support.

Why do my Keycloak groups not show up in ArgoCD?

Keycloak does not put group lists into the identity token until you tell it to. You must add a group membership mapper to the client inside your Keycloak settings.

What happens if the Keycloak server goes down?

Users will not be able to log in through single sign-on during the outage. Admins often keep one local break-glass account in ArgoCD for emergency fixes during downtime.

The query runs. The emails stay hidden.