> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Keycloak

> Connect Keycloak to CloudThinker for identity and access management operations

Connect your Keycloak realm to enable [Oliver](/guide/agents/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**.

<Info>
  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.
</Info>

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

<Tabs>
  <Tab title="Self-hosted Keycloak">
    Provision the client with `kcadm.sh`, Keycloak's admin CLI. Run from any shell where it's available.

    <Steps>
      <Step title="Authenticate">
        ```bash theme={null}
        kcadm.sh config credentials \
          --server http://localhost:8080 --realm master \
          --user admin --password '<admin-password>'
        ```
      </Step>

      <Step title="Create the client">
        ```bash theme={null}
        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=[]'
        ```
      </Step>

      <Step title="Assign realm-management roles">
        ```bash theme={null}
        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.
      </Step>

      <Step title="Get the client secret">
        ```bash theme={null}
        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
        ```
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Phase Two">
    For managed Keycloak via [Phase Two](https://dash.phasetwo.io/realms).

    <Steps>
      <Step title="Open the realm console">
        In the [Phase Two dashboard](https://dash.phasetwo.io/realms), open the console for the realm you want to connect.
      </Step>

      <Step title="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**
      </Step>

      <Step title="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.
      </Step>

      <Step title="Get the client secret">
        In the same client, open **Credentials** and copy the value under **Client Secret**.
      </Step>

      <Step title="Get the realm URL">
        Back in [https://dash.phasetwo.io/realms](https://dash.phasetwo.io/realms), open the realm card and click **Details**. Copy the value under **Host** (e.g. `https://<region>.auth.ac/auth`).
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>
</Tabs>

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

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

## 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

```text theme={null}
@oliver #report list all clients in the realm to verify the Keycloak connection
```

### Example prompts

```text theme={null}
@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

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="Empty client secret">
  * The client must be confidential — `publicClient=false` (self-hosted) or **Client authentication** enabled (Phase Two)
  * Public clients have no secret
</Accordion>

## 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

<CardGroup cols={2}>
  <Card title="Oliver Agent" icon="shield-halved" href="/guide/agents/oliver">
    Security and compliance agent
  </Card>

  <Card title="Connections Overview" icon="plug" href="/guide/connections/overview">
    All available connections
  </Card>
</CardGroup>