Keycloak user management for kdb Insights Enterprise.

Use UserManager to create, delete, and manage users and their role assignments on a kdb Insights Enterprise Keycloak realm.

Example

from kxi.authorization.user import UserManager

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

# Create a user with a temporary password
mgr.create("alice", password="temp-pass", email="alice@example.com")

# Assign kdb Insights roles
mgr.assign_roles("alice", ["insights-user", "insights-query"])

# Add to a Keycloak group by UUID
mgr.add_to_group("alice", "<group-uuid>")

# Delete the user
mgr.delete("alice")

Classes:

• Client – A Keycloak client entry as returned by the admin API.
• Role – A Keycloak realm or client role.
• RoleType – Role query type for user role filtering.
• User – Keycloak user record.
• UserAccess – Keycloak access permissions the API caller has on a user record.
• UserGroup – A Keycloak group that a user belongs to.
• UserManager – REST client for Keycloak user management.

Client

Bases: BaseModel

A Keycloak client entry as returned by the admin API.

Attributes:

• id (str) – Internal Keycloak UUID for this client.
• clientId (str) – Human-readable client ID.
• description (Optional[str]) – Optional client description.

Role

Bases: BaseModel

A Keycloak realm or client role.

Attributes:

• id (str) – Keycloak role UUID.
• name (str) – Role name (e.g. "insights-user").
• composite (bool) – Whether this role is a composite of other roles.
• clientRole (bool) – Whether this is a client-scoped role.
• containerId (str) – UUID of the realm or client that owns this role.
• description (Optional[str]) – Optional human-readable role description.

RoleType

Bases: AutoNameEnum

Role query type for user role filtering.

Used with UserManager.get_roles_for_user.

Attributes:

• available – Roles that can be assigned but are not yet assigned.
• composite – Effective roles including inherited composite roles.
• all – All currently assigned roles.

User

Bases: BaseModel

Keycloak user record.

Attributes:

• id (str) – Keycloak user UUID.
• username (str) – Unique username.
• email (Optional[str]) – Email address.
• enabled (bool) – Whether the account is active.
• totp (bool) – Whether TOTP two-factor authentication is configured.
• emailVerified (bool) – Whether the email address has been verified.
• disableableCredentialTypes (list) – Credential types that can be disabled.
• requiredActions (list) – Pending required actions (e.g. password reset).
• notBefore (datetime) – Tokens issued before this timestamp are invalid.
• access (UserAccess) – Caller's access permissions on this user record.
• firstName (Optional[str]) – User's given name.
• lastName (Optional[str]) – User's family name.
• groups (Optional[List[str]]) – Group paths the user belongs to.

UserAccess

Bases: BaseModel

Keycloak access permissions the API caller has on a user record.

Attributes:

• manageGroupMembership (Optional[bool]) – Whether the caller can manage this user's groups.
• view (Optional[bool]) – Whether the caller can view this user.
• mapRoles (Optional[bool]) – Whether the caller can map roles to this user.
• impersonate (Optional[bool]) – Whether the caller can impersonate this user.
• manage (Optional[bool]) – Whether the caller can fully manage this user.

UserGroup

Bases: BaseModel

A Keycloak group that a user belongs to.

Attributes:

• id (str) – Keycloak group UUID.
• name (str) – Group name.
• path (str) – Full group path, e.g. /analysts/emea.

UserManager

UserManager(host, username=None, password=None, *, realm='insights', timeout=2, session=None, **kwargs)

Bases: KeycloakPath, ApiClient

REST client for Keycloak user management.

Authenticates as a Keycloak admin user and provides CRUD operations for users, role assignments, and group membership on the kdb Insights Enterprise Keycloak realm.

Example

from kxi.authorization.user import UserManager

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

mgr.create("alice", password="temp-pass", email="alice@example.com")
mgr.assign_roles("alice", ["insights-user"])
mgr.delete("alice")

Functions:

• add_to_group – Add a user to a Keycloak group.
• assign_roles – Assign realm and client roles to a user.
• create – Create a new Keycloak user.
• create_client – Create a new client.
• delete – Delete a user by username.
• delete_by_id – Delete a user directly by Keycloak UUID.
• delete_client – Delete a client.
• get – Retrieve a user by username.
• get_assigned_groups – Get all Keycloak groups a user belongs to.
• get_assigned_roles – Get all directly assigned roles for a user.
• get_client_internal_id – Get a clients internal id.
• get_client_secret – Get a clients secret.
• get_effective_roles – Get all effective roles for a user, including inherited composite roles.
• get_role_data – Get role data.
• get_roles_for_user – Get roles for a user filtered by type.
• list – List all users in the realm.
• list_clients – List clients.
• list_realm_management – List realm management roles.
• list_roles – List all available roles in the realm.
• remove_from_group – Remove a user from a Keycloak group.
• remove_roles – Remove realm and client roles from a user.
• reset_password – Reset a user's password.

Initialise UserManager with Keycloak admin credentials.

Parameters:

• host (str) – 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: 2.
• session (Client | AsyncClient | None) – Optional pre-built httpx session (overrides credential auth).
• *kwargs* – Additional keyword arguments forwarded to the base client.

add_to_group

add_to_group(user_name, group)

Add a user to a Keycloak group.

Parameters:

• user_name (str) – Username of the user to update.
• group (str) – Keycloak group UUID to add the user to.

assign_roles

assign_roles(user, roles)

Assign realm and client roles to a user.

Parameters:

• user (str | User) – Username string or User object.
• roles (List[str | Role]) – Role name strings or Role objects to assign.

Returns:

• – API response for the role assignment.

Raises:

• NotFoundException – One or more requested roles were not found.

create

create(username, password, email=None, enabled=True, temporary=True, groups=None)

Create a new Keycloak user.

Parameters:

• username (str) – Unique username for the new user.
• password (str) – Initial password for the user.
• email (str | None) – Email address for the user.
• enabled (bool) – Whether the account is active immediately. Default: True.
• temporary (bool) – Whether the user must change the password on first login. Default: True.
• groups (List[str] | None) – Keycloak group paths to add the user to at creation.

Returns:

• – API response for the created user.

Raises:

• ConflictError – A user with the same username already exists.

create_client

create_client(client_id, direct_access_grants_enabled=True, service_accounts_enabled=True)

Create a new client.

delete

delete(user)

Delete a user by username.

Parameters:

• user (str | User) – Username string or User object to delete.

Returns:

• – API response for the deletion.

delete_by_id

delete_by_id(user_id)

Delete a user directly by Keycloak UUID.

Parameters:

• user_id (str) – Keycloak UUID of the user to delete.

Returns:

• – API response for the deletion.

delete_client

delete_client(client_id, direct_access_grants_enabled=True, service_accounts_enabled=True)

Delete a client.

get

get(user)

Retrieve a user by username.

Parameters:

• user (str | User) – Username string or an existing User object (returned as-is).

Returns:

• User – Matching User object.

Raises:

• NotFoundException – No user with the given username exists.
• ConflictException – Multiple users match the username.

get_assigned_groups

get_assigned_groups(user_name)

Get all Keycloak groups a user belongs to.

Parameters:

• user_name (str) – Username to query.

Returns:

• List[UserGroup] – List of UserGroup objects.

get_assigned_roles

get_assigned_roles(user)

Get all directly assigned roles for a user.

Parameters:

• user (str | User) – Username string or User object.

Returns:

• List[Role] – List of Role objects.

get_client_internal_id

get_client_internal_id(client_id)

Get a clients internal id.

get_client_secret

get_client_secret(client_id)

Get a clients secret.

get_effective_roles

get_effective_roles(user)

Get all effective roles for a user, including inherited composite roles.

Parameters:

• user (str | User) – Username string or User object.

Returns:

• List[Role] – List of Role objects.

get_role_data

get_role_data(roles, check_management)

Get role data.

get_roles_for_user

get_roles_for_user(user, role_type)

Get roles for a user filtered by type.

Parameters:

• user (str | User) – Username string or User object.
• role_type (RoleType) – Which roles to return — assigned, composite, or all.

Returns:

• List[Role] – List of Role objects.

list

list(**kwargs)

List all users in the realm.

Returns:

• List[User] – List of User objects.

list_clients

list_clients(**kwargs)

List clients.

list_realm_management

list_realm_management(**kwargs)

List realm management roles.

list_roles

list_roles(check=True)

List all available roles in the realm.

Parameters:

• check (bool) – If True, includes realm-management client roles alongside realm roles. Default: True.

Returns:

• List[Role] – List of Role objects.

remove_from_group

remove_from_group(user_name, group)

Remove a user from a Keycloak group.

Parameters:

• user_name (str) – Username of the user to update.
• group (str) – Keycloak group UUID to remove the user from.

remove_roles

remove_roles(user, roles)

Remove realm and client roles from a user.

Parameters:

• user (str | User) – Username string or User object.
• roles (List[str | Role]) – Role name strings or Role objects to remove.

Returns:

• – API response for the role removal.

reset_password

reset_password(user, password, temporary=True)

Reset a user's password.

Parameters:

• user (str | User) – Username string or User object.
• password (str) – New password value.
• temporary (bool) – Whether the user must change the password on next login. Default: True.

Returns:

• – API response for the password reset.