Skip to main content

Client Role API

The ClientRoleHandle class provides a fluent API for managing roles associated with a specific client in Keycloak. It allows you to create, update, delete, and retrieve client roles, as well as list users assigned to those roles.

Class: ClientRoleHandle​

Constructor​

constructor(core: KeycloakAdminClient, clientHandle: ClientHandle, roleName: string)
  • Parameters:
    • core: An instance of KeycloakAdminClient.
    • clientHandle: A handle to the client where the role resides.
    • roleName: The name of the client role to manage.

Static Methods​

getByName(core: KeycloakAdminClient, realm: string, clientId: string, roleName: string, client?: ClientRepresentation | null)​

Fetches a client role by its name.

static async getByName(core: KeycloakAdminClient, realm: string, clientId: string, roleName: string, client?: ClientRepresentation | null)
  • Parameters:
    • core: An instance of KeycloakAdminClient.
    • realm: The name of the realm.
    • clientId: The ID of the client.
    • roleName: The name of the role.
    • client: (Optional) The client representation.
  • Returns: The role representation or null if the role does not exist.

Instance Methods​

get()​

Fetches the client role by its name and updates the instance's role property.

public async get(): Promise<RoleRepresentation | null>
  • Returns: The role representation or null if the role does not exist.

create(data: ClientRoleInputData)​

Creates a new client role.

public async create(data: ClientRoleInputData)
  • Parameters:
    • data: The data for the new client role.
  • Throws: An error if the role already exists.

update(data: ClientRoleInputData)​

Updates the client role's details.

public async update(data: ClientRoleInputData)
  • Parameters:
    • data: The updated data for the client role.
  • Throws: An error if the role does not exist.

delete()​

Deletes the client role.

public async delete()
  • Throws: An error if the role does not exist.

ensure(data: ClientRoleInputData)​

Ensures the client role exists. If it does, updates it; otherwise, creates it.

public async ensure(data: ClientRoleInputData)
  • Parameters:
    • data: The data for the client role.

discard()​

Deletes the client role if it exists.

public async discard()
  • Returns: The name of the deleted client role.

listAssignedUsers()​

Lists all users assigned to the client role.

public async listAssignedUsers()
  • Returns: A list of users assigned to the role.

Types​

ClientRoleInputData​

The input data type for creating or updating a client role.

export type ClientRoleInputData = Omit<RoleRepresentation, 'name | id'>;

This API provides a comprehensive interface for managing client roles in Keycloak, including role creation, updates, deletion, and user assignments.