Keycloak

Connect Keycloak to CloudThinker for identity and access management operations

Connect your Keycloak realm to enable Oliver (Security Professional) to inspect realms, audit clients, review users and roles, and analyze identity and access configuration.

Keycloak authenticates with a confidential service-account client that holds realm-management roles on the target realm.

Supported platforms

Platform	Support
Self-hosted Keycloak	All versions
Phase Two	Managed Keycloak service

Prerequisites

• A Keycloak realm you want CloudThinker to inspect.
• Admin access to create a confidential client and assign service-account roles — kcadm.sh (self-hosted) or the realm console (Phase Two).
• The realm’s base URL and realm name.

The connection scopes to the roles you grant the cloudthinker-svc service account. Assign the least-privileged realm-management roles that cover what CloudThinker needs.

Setup

Both paths create the same artifact: a cloudthinker-svc confidential client with realm-management roles on its service account. Self-hosted uses kcadm.sh; Phase Two uses the realm console.

Self-hosted Keycloak

Provision the client with kcadm.sh, Keycloak’s admin CLI. Run from any shell where it’s available.

1. Authenticate

   kcadm.sh config credentials \
     --server http://localhost:8080 --realm master \
     --user admin --password '<admin-password>'
   
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 \
     -s 'redirectUris=[]'
   
3. Assign realm-management roles

   kcadm.sh add-roles -r <your-realm> \
     --uusername service-account-cloudthinker-svc \
     --cclientid realm-management \
     --rolename realm-admin
   

   Use narrower roles (e.g. view-realm, view-users) if you want least-privilege.

4. Get 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
   
5. Add the connection in CloudThinker

   Navigate to Connections → Keycloak and enter:

   • KEYCLOAK_URL: http://<host-ip>:8080
   • KEYCLOAK_REALM: your realm name
   • KEYCLOAK_CLIENT_ID: cloudthinker-svc
   • KEYCLOAK_CLIENT_SECRET: secret from the previous step

   Click Connect. CloudThinker shows a Connected status once it succeeds.

Phase Two

For managed Keycloak via Phase Two.

1. Open the realm console

   In the Phase Two dashboard, open the console for the realm you want to connect.

2. Create a client

   Go to the Clients tab → Create client and configure:

   • Client ID: cloudthinker-svc
   • Click Next
   • Enable Client authentication and Authorization
   • Click Next, then Save
3. Assign realm-management roles

   Open the new client → Service account roles → Assign roles.

   Search for realm-management and assign the roles you want CloudThinker to use. We recommend assigning all realm-management roles — check both pages to avoid missing any.

4. Get the client secret

   In the same client, open Credentials and copy the value under Client Secret.

5. Get the realm URL

   Back in https://dash.phasetwo.io/realms, open the realm card and click Details. Copy the value under Host (e.g. https://<region>.auth.ac/auth).

6. Add the connection in CloudThinker

   Navigate to Connections → Keycloak and enter:

   • KEYCLOAK_URL: Host URL from the realm details (e.g. https://<region>.auth.ac/auth)
   • KEYCLOAK_REALM: your realm name
   • KEYCLOAK_CLIENT_ID: cloudthinker-svc
   • KEYCLOAK_CLIENT_SECRET: secret from the credentials step

   Click Connect. CloudThinker shows a Connected status once it succeeds.

Connection details

Field	Description	Example
KEYCLOAK_URL	Keycloak base URL	http://<host-ip>:8080
KEYCLOAK_REALM	Target realm name	my-realm
KEYCLOAK_CLIENT_ID	Service-account client ID	cloudthinker-svc
KEYCLOAK_CLIENT_SECRET	Client secret from the credentials step	—

Required permissions

The cloudthinker-svc service account needs realm-management roles on the target realm. Common roles:

Role	Purpose
view-realm	Read realm settings
view-users	List and inspect users
view-clients	List and inspect clients
query-users, query-clients, query-groups	Run lookup queries
manage-users, manage-clients, manage-realm	Make changes (assign only if needed)

For read-only analysis, assign only the view-* and query-* roles. Add manage-* roles only when you need Oliver to make changes.

Agent capabilities

Once connected, Oliver can:

Capability	Description
Realm inspection	Review realm settings and configuration
Client audit	List clients, review flows and authorization settings
User management	View users, sessions, and credentials state
Role and group review	Inspect roles, composites, and group hierarchies
Access analysis	Identify over-privileged service accounts and stale clients

Verify the connection

@oliver #report list all clients in the realm to verify the Keycloak connection

Example prompts

@oliver #report list all clients in the realm and flag any with direct access grants enabled
@oliver #report show service accounts with realm-admin and review whether each is needed
@oliver #recommend audit users without 2FA enabled

Troubleshooting

401 Unauthorized

• Verify the client secret was copied correctly
• Confirm Client authentication is enabled on the client
• Ensure the service account has realm-management roles assigned

403 Forbidden on realm operations

• Service account is missing the required realm-management role for that operation
• Self-hosted: re-run add-roles with the missing role
• Phase Two: re-check both pages of the role assignment list

Cannot reach Keycloak URL

• Self-hosted: confirm the base URL matches your Keycloak hostname
• Phase Two: copy the URL exactly from the realm Details → Host field

Empty client secret

• The client must be confidential — publicClient=false (self-hosted) or Client authentication enabled (Phase Two)
• Public clients have no secret

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.

• Dedicated client — use cloudthinker-svc as a dedicated service-account client, not a shared admin client.
• Secret rotation — rotate the client secret periodically via the Credentials tab.

Related

Oliver Agent

Security and compliance agent

Connections Overview

All available connections