Skip to content

Keycloak auth client management for kdb Insights Enterprise.

Use ClientManager to register, update, and list Keycloak auth clients (service accounts) on a kdb Insights Enterprise instance.

Example 
from kxi.authorization.client import ClientManager

mgr = ClientManager(host="https://<host>", username="admin", password="<pass>")

# Register a new client with all realm roles
client = mgr.register_client("my-service", client_secret="<secret>")
print(client.id, client.secret)

# List all registered clients
for c in mgr.list_clients():
    print(c.id, c.uuid)

# Delete a client by UUID
mgr.delete_client_by_uuid(client.uuid)

Classes:

  • AuthClient – Keycloak client credentials returned after registration.
  • ClientManager – REST client for Keycloak auth client management.

AuthClient

Bases: BaseModel

Keycloak client credentials returned after registration.

Attributes:

  • host (str) – Base URL of the kdb Insights Enterprise instance.
  • id (str) – Keycloak client ID (human-readable name).
  • secret (str) – Client secret for authentication.
  • uuid (str) – Keycloak internal UUID for this client.

ClientManager

ClientManager(host=None, username=None, password=None, *, realm='insights', timeout=15, session=None)

Bases: KeycloakPath, ApiClient

REST client for Keycloak auth client management.

Authenticates as a Keycloak admin user and provides operations for registering, updating, and listing Keycloak clients (service accounts) on the kdb Insights Enterprise realm.

Example 
from kxi.authorization.client import ClientManager

mgr = ClientManager(
    host="https://<host>",
    username="admin",
    password="<pass>",
)

client = mgr.register_client("analytics-svc", roles="all")
print(client.id, client.secret)

See Connection Parameters for shared constructor arguments.

Functions:

Attributes:

Initialise ClientManager with Keycloak admin credentials.

Parameters:

  • host (str | None) – Base URL of the kdb Insights Enterprise instance.
  • username (str | None) – Keycloak admin username.
  • password (str | None) – Keycloak admin password.
  • realm (str) – Keycloak realm name. Default: "insights".
  • timeout (int) – HTTP request timeout in seconds. Default: 15.
  • session (Client | AsyncClient | None) – Optional pre-built httpx session (overrides credential auth).

all_roles

all_roles: list

Get all roles available in the realm.

assign_roles

assign_roles(client, roles)

Assign realm roles to a client's service account.

Parameters:

  • client (AuthClient) – AuthClient to assign roles to.
  • roles (list[str] | Literal['all']) – List of role names to assign, or "all" to assign every available realm role.

Returns:

  • – API response for the role assignment.

Raises:

  • Exception – Raised when role assignment fails.

delete_client_by_uuid

delete_client_by_uuid(client_uuid)

Delete a Keycloak client by its internal UUID.

Parameters:

  • client_uuid (UUID) – Keycloak internal UUID of the client to delete.

Returns:

  • – API response for the deletion.

get_client

get_client(client_id, *, with_secret=True)

Get a client by name/id.

Parameters:

  • client_id (str) – Client name/id.
  • with_secret (bool) – If True, fetch the client secret.

Returns:

list_clients

list_clients(client_id=None, *, with_secret=True)

Get a list of registered clients.

Parameters:

  • client_id (str | None) – Client id to filter by. If None, all clients are returned.
  • with_secret (bool) – If True, fetch the client secret.

Returns:

register_client

register_client(client_id, client_secret=None, config=None, *, token_lifespan=None, roles='all')

Register a Keycloak client, creating or updating it as needed.

If the client does not exist it is created. If it already exists, its secret and configuration are updated. After registration, the specified roles are assigned to the client's service account.

Parameters:

  • client_id (str) – Keycloak client ID (human-readable name).
  • client_secret (str | None) – Client secret. Auto-generated if None.
  • config (dict[str, Any] | None) – Additional Keycloak client configuration fields.
  • token_lifespan (int | None) – Access token lifespan in seconds for this client.
  • roles (list[str] | Literal['all'] | None) – Role names to assign to the client service account, or "all" to assign every available realm role. Pass None to skip role assignment. Default: "all".

Returns:

Raises:

register_new_client

register_new_client(client_id, client_secret=None, config=None, *, token_lifespan=None)

Register a new Keycloak client.

Creates the client via the Keycloak admin API. Use register_client for an idempotent upsert that also assigns roles.

Parameters:

  • client_id (str) – Keycloak client ID (human-readable name).
  • client_secret (str | None) – Client secret. Auto-generated if None.
  • config (dict | None) – Additional Keycloak client configuration fields.
  • token_lifespan (int | None) – Access token lifespan in seconds for this client.

Returns:

Raises:

update_client

update_client(client, *, secret=None, token_lifespan=None, **config)

Update an existing Keycloak client's configuration.

Parameters:

  • client (AuthClient) – AuthClient to update.
  • secret (str | None) – New client secret. If None, the existing secret is kept.
  • token_lifespan (int | None) – Access token lifespan in seconds for this client.
  • *config* – Additional Keycloak client configuration fields.

Returns:

Back to top