Keycloak

Connect a Keycloak realm so agents can audit users, clients, roles, groups, and auth flows, and make identity changes through your Approvals

Connect a Keycloak realm to let CloudThinker agents review users, clients, roles, groups, identity providers, and authentication flows, and make identity changes through your workspace’s Approvals. The connection signs in as a service account: a confidential client in your realm that uses the client credentials grant, with realm-management roles that set what agents can see and change.

Prerequisites

• A Keycloak server CloudThinker can reach over the network. For a server behind a firewall, see Reaching private services. CloudThinker doesn’t block http, but the client secret then travels unencrypted, so use https.
• An administrator who can create a client in the target realm and assign it service account roles.
• The realm name.
• The Admin role in your CloudThinker workspace, which can add and edit connections. See Roles.

A workspace holds one Keycloak connection, and it targets one realm. Agents get a token from <KEYCLOAK_URL>/realms/<KEYCLOAK_REALM>/protocol/openid-connect/token, so the base URL must be the part before /realms.

Setup

Both tabs create the same thing: a confidential client named cloudthinker-svc with service accounts enabled and realm-management roles on its service account.

Admin console

Works for self-hosted Keycloak and managed Keycloak such as Phase Two.

1. Create the client

   In the admin console, switch to your realm, open Clients, and select Create client. Set Client ID to cloudthinker-svc and select Next. Turn on Client authentication, check Service accounts roles, and leave the other flows off. Select Next, then Save.

2. Assign realm-management roles

   Open the client, go to Service accounts roles, and select Assign role. Filter by clients, search for realm-management, and pick the roles. For read-only audits, pick view-realm, view-users, query-users, view-clients, query-clients, and query-groups. To allow changes, see Required permissions. The list can span more than one page.

3. Copy the client secret

   On the same client, open Credentials and copy Client Secret.

kcadm.sh

Use Keycloak’s admin CLI from any machine that can reach your Keycloak server.

1. Sign in

   kcadm.sh config credentials \
     --server https://keycloak.example.com --realm master \
     --user admin
   

   Leave out --password so kcadm.sh prompts for it and the password stays out of your shell history. Add /auth to --server if your server serves under it.

2. Create the client

   kcadm.sh create clients -r <your-realm> \
     -s clientId=cloudthinker-svc \
     -s publicClient=false \
     -s serviceAccountsEnabled=true \
     -s standardFlowEnabled=false \
     -s directAccessGrantsEnabled=false
   
3. Assign read-only realm-management roles

   kcadm.sh add-roles -r <your-realm> \
     --uusername service-account-cloudthinker-svc \
     --cclientid realm-management \
     --rolename view-realm --rolename view-users --rolename query-users \
     --rolename view-clients --rolename query-clients --rolename query-groups
   
4. Copy the client secret

   CID=$(kcadm.sh get clients -r <your-realm> \
     -q clientId=cloudthinker-svc --fields id --format csv --noquotes | tail -n1)
   
   kcadm.sh get clients/$CID/client-secret -r <your-realm> \
     --fields value --format csv --noquotes | tail -n1
   

Then add the connection:

1. Add the connection in CloudThinker

   Open More → Workspace settings → Connections, select Keycloak, and fill in the fields from Connection details. Click Connect.

   Success state: the connection shows Connecting and Verifying, then Connected. CloudThinker signs in as the service account and counts the realm’s users, which proves both the secret and the view-users role.

Connection details

Field	Description	Example
KEYCLOAK_URL	Keycloak base URL, without /realms/.... Include /auth if your server serves under it, as older Keycloak releases and Phase Two do	https://keycloak.example.com
KEYCLOAK_REALM	Realm the client lives in and agents work on	production
KEYCLOAK_CLIENT_ID	Client ID of the service account client	cloudthinker-svc
KEYCLOAK_CLIENT_SECRET	Client secret from the Credentials tab

For Phase Two, copy the base URL from the realm card in the Phase Two dashboard: select Details and copy Host.

Required permissions

Assign realm-management client roles to the service account. Pick the narrowest set that covers your use.

You want agents to	Roles
Pass the connection test and audit users	view-users, query-users
Review realm settings, identity providers, and auth flows	view-realm
Review clients and client roles	view-clients, query-clients
Review groups and members	query-groups, plus view-users
Create, update, or delete users, groups, or memberships	manage-users
Create or delete clients, client roles, or rotate secrets	manage-clients
Change realm settings or auth flows	manage-realm

realm-admin includes every role above. It’s the quickest choice and the broadest, so use it only if agents should manage the whole realm.

For audits, assign only view-* and query-* roles. A missing role shows up as 403 Forbidden on the matching question, not as a failed connection, unless it’s view-users.

Agent capabilities

Capability	What agents can do	Approval
Users	List and count users, look one up by username, show direct and effective roles and group membership	No
Clients	List clients and their roles, and inspect settings such as which flows are on	No
Roles and groups	List realm roles, groups, and group members	No
Identity providers	List identity providers and their mappers	No
Auth flows	List authentication flows and their executions	No
User changes	Create, update, or delete users, reset passwords, send verification email, change roles and group membership	Through Approvals
Client changes	Create or delete clients and client roles, and rotate client secrets	Through Approvals
Realm, group, and flow changes	Create, rename, or delete groups and subgroups, create or delete flows, change an execution’s requirement. Creating a realm also needs the create-realm role, which exists only in the master realm	Through Approvals

Reads run without asking. Allow writes on the connection’s detail panel is on by default; turn it off to refuse every change. Every change goes through Approvals first.

Every change an agent makes goes through your workspace’s Approvals first. On the default Auto · Rules + AI · Ask me mode, AI judgment can let a safe change run without asking — and an Allow Rule can too, once CloudThinker turns on Rule enforcement for your workspace. Choose Manual to approve every change yourself.

List reads return up to 100 entries by default, so for a large realm, ask about a group, a client, or a username rather than everyone.

CloudThinker passes a new user password to Keycloak on standard input, so it stays out of command logs. It can still appear in the conversation if you type it there, so prefer letting users reset their own password through Keycloak.

Rotating a client secret takes effect the moment it runs, and the old secret stops working. Tell the owner of that client before you ask for it.

Verify the connection

How many users are in my Keycloak realm?

Expect a user count. This needs only view-users. To check client access too, ask which clients have direct access grants enabled, which needs view-clients.

Example prompts

What are the effective realm roles of the user alice?
Which service accounts hold realm-admin, and does each one need it?
Show the steps of the browser authentication flow and which are required

Troubleshooting

Failed to connect to Keycloak

CloudThinker couldn’t get a token or count users. Check in this order:

• KEYCLOAK_URL is reachable from CloudThinker and stops before /realms. Add /auth if your server serves under it.
• KEYCLOAK_REALM is the realm where you created the client. Names are case-sensitive.
• Client authentication and Service accounts roles are on for the client, and the secret was copied in full.
• The service account has view-users.

The client has no secret

The client is public. Turn on Client authentication, or set publicClient=false with kcadm.sh, then copy the secret from Credentials.

403 Forbidden on some questions

The token works, but the service account lacks the role for that endpoint. Read questions need a view-* or query-* role and changes need a manage-* role. Add the role from Required permissions. Roles apply on the next token, so retry the question.

An agent shows only 100 users

List reads stop at 100 by default. Ask for a specific username or group, or ask the agent to page through more results.

Security

• Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
• Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
• Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
• Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.

• Use a dedicated client: keep cloudthinker-svc for CloudThinker only, so you can revoke it without affecting other apps.
• Rotate the secret: the connection breaks the moment you regenerate it, so do both steps together. Keycloak is a single-connection service, so its row has no pencil icon. Regenerate the secret under Credentials in Keycloak, then open More → Workspace settings → Connections and select Keycloak. Once it shows Error, click Replace credentials, click Replace… next to the saved credentials, paste the new KEYCLOAK_CLIENT_SECRET, and click Save and test. See Rotate a credential.
• Avoid realm-admin for audits: read-only roles cover every question in the read rows above.

Related

Approvals

Decide which Keycloak changes run, wait for a person, or are refused.

Connections

See every service you can connect and how connection status works.