Skip to main content
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

PlatformSupport
Self-hosted KeycloakAll versions
Phase TwoManaged 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.
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.

โ€‹
Connection details

FieldDescriptionExample
KEYCLOAK_URLKeycloak base URLhttp://<host-ip>:8080
KEYCLOAK_REALMTarget realm namemy-realm
KEYCLOAK_CLIENT_IDService-account client IDcloudthinker-svc
KEYCLOAK_CLIENT_SECRETClient secret from the credentials stepโ€”

โ€‹
Required permissions

The cloudthinker-svc service account needs realm-management roles on the target realm. Common roles:
RolePurpose
view-realmRead realm settings
view-usersList and inspect users
view-clientsList and inspect clients
query-users, query-clients, query-groupsRun lookup queries
manage-users, manage-clients, manage-realmMake 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:
CapabilityDescription
Realm inspectionReview realm settings and configuration
Client auditList clients, review flows and authorization settings
User managementView users, sessions, and credentials state
Role and group reviewInspect roles, composites, and group hierarchies
Access analysisIdentify 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

  • Verify the client secret was copied correctly
  • Confirm Client authentication is enabled on the client
  • Ensure the service account has realm-management roles assigned
  • 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
  • Self-hosted: confirm the base URL matches your Keycloak hostname
  • Phase Two: copy the URL exactly from the realm Details โ†’ Host field
  • 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.

Oliver Agent

Security and compliance agent

Connections Overview

All available connections