Keycloak group management API client.

Use GroupManager to create, list, and delete Keycloak groups on a kdb Insights Enterprise instance.

Example

from kxi.authorization.group import GroupManager

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

# Create a group and list all groups
mgr.create("data-engineers")
groups = mgr.list()

# Assign kdb Insights roles to every member of the group
mgr.assign_roles("data-engineers", ["insights.role.maintainer"])

# Add users to the group
mgr.assign_users("data-engineers", ["alice", "bob"])

# Delete by name or Group object
mgr.delete("data-engineers")

Classes:

• Group – A Keycloak group.
• GroupManager – REST client for Keycloak group management.

Group

Bases: BaseModel

A Keycloak group.

Attributes:

• id (str) – Keycloak group UUID.
• name (str) – Human-readable group name.

GroupManager

GroupManager(host, username, password, *, realm=None, timeout=15, session=None, **kwargs)

Bases: KeycloakPath, ApiClient

REST client for Keycloak group management.

Authenticates as an admin user and provides CRUD operations for Keycloak groups on the kdb Insights Enterprise realm.

Example

from kxi.authorization.group import GroupManager

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

mgr.create("analysts")
group = mgr.get("analysts")
mgr.delete(group)

See Connection Parameters for shared constructor arguments.

Functions:

• assign_roles – Assign realm and client roles to a group.
• assign_users – Add users to a group.
• create – Create a new group.
• delete – Delete a group by name or Group object.
• delete_by_id – Delete a group directly by its Keycloak UUID.
• get – Retrieve a group by name.
• get_assigned_roles – List the realm roles assigned to a group.
• get_members – List the users belonging to a group.
• get_role_data – Resolve role names to Keycloak role payloads.
• list – List all groups in the realm.
• remove_roles – Remove realm and client roles from a group.
• remove_users – Remove users from a group.

Initialise the GroupManager with admin credentials.

Parameters:

• host (str) – Base URL of the kdb Insights Enterprise instance.
• username (str) – Keycloak admin username.
• password (str) – Keycloak admin password.
• realm (str | None) – Keycloak realm name. Defaults to the configured realm.
• timeout (int) – HTTP request timeout in seconds. Default: 15.
• session (Client | AsyncClient | None) – Optional pre-built httpx session (overrides credential auth).
• *kwargs* – Additional keyword arguments forwarded to the base client.

assign_roles

assign_roles(group, roles)

Assign realm and client roles to a group.

Every member of the group inherits the assigned roles.

Parameters:

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

Returns:

• – API response for the role assignment.

Raises:

• NotFoundException – The group, or one or more requested roles, was not found.

assign_users

assign_users(group, users)

Add users to a group.

Each user inherits the roles mapped to the group.

Parameters:

• group (str | Group) – Group name string or Group object.
• users (List[str | User]) – Username strings or User objects to add.

Returns:

• – List of API responses, one per user added.

Raises:

• NotFoundException – The group, or one of the requested users, was not found.

create

create(name)

Create a new group.

Parameters:

• name (str) – Name of the group to create.

Returns:

• – API response for the created group.

delete

delete(group)

Delete a group by name or Group object.

Resolves the group ID via get before deleting.

Parameters:

• group (str | Group) – Group name or Group object to delete.

Returns:

• – API response for the deletion.

delete_by_id

delete_by_id(group_id)

Delete a group directly by its Keycloak UUID.

Parameters:

• group_id (str) – Keycloak UUID of the group to delete.

Returns:

• – API response for the deletion.

get

get(grp)

Retrieve a group by name.

Parameters:

• grp (str | Group) – Group name or an existing Group object (returned as-is).

Returns:

• Group – Matching Group object.

Raises:

• NotFoundException – No group with the given name exists.

get_assigned_roles

get_assigned_roles(group)

List the realm roles assigned to a group.

Parameters:

• group (str | Group) – Group name string or Group object.

Returns:

• List[Role] – List of Role objects assigned to the group.

Raises:

• NotFoundException – No group with the given name exists.

get_members

get_members(group, **kwargs)

List the users belonging to a group.

Parameters:

• group (str | Group) – Group name string or Group object.
• *kwargs* – Additional query parameters forwarded to the request.

Returns:

• List[User] – List of User objects in the group.

Raises:

• NotFoundException – No group with the given name exists.

get_role_data

get_role_data(roles, check_management)

Resolve role names to Keycloak role payloads.

Parameters:

• roles (List[str | Role]) – Role name strings or Role objects.
• check_management (bool) – If True, resolve against the realm-management client roles; otherwise against the realm roles.

Returns:

• List[dict] – List of role payloads suitable for a role-mappings request body.

Raises:

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

list

list(**kwargs)

List all groups in the realm.

Returns:

• – List of Group objects.

remove_roles

remove_roles(group, roles)

Remove realm and client roles from a group.

Parameters:

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

Returns:

• – API response for the role removal.

Raises:

• NotFoundException – The group, or one or more requested roles, was not found.

remove_users

remove_users(group, users)

Remove users from a group.

Parameters:

• group (str | Group) – Group name string or Group object.
• users (List[str | User]) – Username strings or User objects to remove.

Returns:

• – List of API responses, one per user removed.

Raises:

• NotFoundException – The group, or one of the requested users, was not found.