Keycloak - CloudThinker

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
Phase Two

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

Authenticate

kcadm.sh config credentials \
  --server http://localhost:8080 --realm master \
  --user admin --password '<admin-password>'

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=[]'

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.

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

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.

For managed Keycloak via Phase Two.

Open the realm console

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

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

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.

Get the client secret

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

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).

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.

Oliver Agent

Security and compliance agent

Connections Overview

All available connections

​Supported platforms

​Prerequisites

​Setup

​Connection details

​Required permissions

​Agent capabilities

​Verify the connection

​Example prompts

​Troubleshooting

​Security

​Related

Oliver Agent

Connections Overview

Supported platforms

Prerequisites

Setup

Connection details

Required permissions

Agent capabilities

Verify the connection

Example prompts

Troubleshooting

Security

Related