keycloak-admin

Node.js Keycloak admin client

Features

TypeScript supported
Keycloak version 11 supported
Complete resource definitions
Well-tested for supported APIs

Install

yarn add keycloak-admin

Usage

import KcAdminClient from 'keycloak-admin';
// or
// const KcAdminClient = require('keycloak-admin').default;

// To configure the client, pass an object to override any of these  options:
// {
//   baseUrl: 'http://127.0.0.1:8080/auth',
//   realmName: 'master',
//   requestConfig: {
//     /* Axios request config options https://github.com/axios/axios#request-config */
//   },
// }
const kcAdminClient = new KcAdminClient();

// Authorize with username / password
await kcAdminClient.auth({
  username: 'wwwy3y3',
  password: 'wwwy3y3',
  grantType: 'password',
  clientId: 'admin-cli',
  totp: '123456', // optional Time-based One-time Password if OTP is required in authentication flow
});

// List all users
const users = await kcAdminClient.users.find();

// Override client configuration for all further requests:
kcAdminClient.setConfig({
  realmName: 'another-realm',
});

// This operation will now be performed in 'another-realm' if the user has access.
const groups = await kcAdminClient.groups.find();

// Set a `realm` property to override the realm for only a single operation.
// For example, creating a user in another realm:
await this.kcAdminClient.users.create({
  realm: 'a-third-realm',
  username: 'username',
  email: 'user@example.com',
});

To refresh the access token provided by Keycloak, an OpenID client like panva/node-openid-client can be used like this:

import {Issuer} from 'openid-client';

const keycloakIssuer = await Issuer.discover(
  'http://localhost:8080/auth/realms/master',
);

const client = new keycloakIssuer.Client({
  client_id: 'admin-cli', // Same as `clientId` passed to client.auth()
  token_endpoint_auth_method: 'none', // to send only client_id in the header
});

// Use the grant type 'password'
let tokenSet = await client.grant({
  grant_type: 'password',
  username: 'wwwy3y3',
  password: 'wwwy3y3',
});

// Periodically using refresh_token grant flow to get new access token here
setInterval(async () => {
  const refreshToken = tokenSet.refresh_token;
  tokenSet = await client.refresh(refreshToken);
  kcAdminClient.setAccessToken(tokenSet.access_token);
}, 58 * 1000); // 58 seconds

In cases where you don't have a refresh token, eg. in a client credentials flow, you can simply call kcAdminClient.auth to get a new access token, like this:

const credentials = { grantType: 'client_credentials', clientId: 'clientId', clientSecret: 'some-client-secret-uuid' };
await kcAdminClient.auth(credentials);

setInterval(() => kcAdminClient.auth(credentials), 58 * 1000); // 58 seconds

Supported APIs

Realm admin

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/realms.spec.ts

Import a realm from a full representation of that realm (POST /)
Get the top-level representation of the realm (GET /{realm})
Update the top-level information of the realm (PUT /{realm})
Delete the realm (DELETE /{realm})
Partial export of existing realm into a JSON file (POST /{realm}/partial-export)
Get users management permissions (GET /{realm}/users-management-permissions)
Enable users management permissions (PUT /{realm}/users-management-permissions)
Get events (GET /{realm}/events)
Get admin events (GET /{realm}/admin-events)
Remove all user sessions (POST /{realm}/logout-all)
Remove a specific user session (DELETE /{realm}/sessions/{session})

Role

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/roles.spec.ts

Create a new role for the realm (POST /{realm}/roles)
Get all roles for the realm (GET /{realm}/roles)
Get a role by name (GET /{realm}/roles/{role-name})
Update a role by name (PUT /{realm}/roles/{role-name})
Delete a role by name (DELETE /{realm}/roles/{role-name})
Get all users in a role by name for the realm (GET /{realm}/roles/{role-name}/users)

Roles (by ID)

Get a specific role (GET /{realm}/roles-by-id/{role-id})
Update the role (PUT /{realm}/roles-by-id/{role-id})
Delete the role (DELETE /{realm}/roles-by-id/{role-id})
Make the role a composite role by associating some child roles(POST /{realm}/roles-by-id/{role-id}/composites)
Get role’s children Returns a set of role’s children provided the role is a composite. (GET /{realm}/roles-by-id/{role-id}/composites)
Remove a set of roles from the role’s composite (DELETE /{realm}/roles-by-id/{role-id}/composites)
Get client-level roles for the client that are in the role’s composite (GET /{realm}/roles-by-id/{role-id}/composites/clients/{client})
Get realm-level roles that are in the role’s composite (GET /{realm}/roles-by-id/{role-id}/composites/realm)

User

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/users.spec.ts

Create a new user (POST /{realm}/users)
Get users Returns a list of users, filtered according to query parameters (GET /{realm}/users)
Get representation of the user (GET /{realm}/users/{id})
Update the user (PUT /{realm}/users/{id})
Delete the user (DELETE /{realm}/users/{id})
Count users (GET /{realm}/users/count)
Send a update account email to the user An email contains a link the user can click to perform a set of required actions. (PUT /{realm}/users/{id}/execute-actions-email)
Get user groups (GET /{realm}/users/{id}/groups)
Add user to group (PUT /{realm}/users/{id}/groups/{groupId})
Delete user from group (DELETE /{realm}/users/{id}/groups/{groupId})
Remove TOTP from the user (PUT /{realm}/users/{id}/remove-totp)
Set up a temporary password for the user User will have to reset the temporary password next time they log in. (PUT /{realm}/users/{id}/reset-password)
Send an email-verification email to the user An email contains a link the user can click to verify their email address. (PUT /{realm}/users/{id}/send-verify-email)

User group-mapping

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/users.spec.ts#L178

Add user to group (PUT /{id}/groups/{groupId})
List all user groups (GET /{id}/groups)
Count user groups (GET /{id}/groups/count)
Remove user from group (DELETE /{id}/groups/{groupId})

User role-mapping

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/users.spec.ts#L143

Get user role-mappings (GET /{realm}/users/{id}/role-mappings)
Add realm-level role mappings to the user (POST /{realm}/users/{id}/role-mappings/realm)
Get realm-level role mappings (GET /{realm}/users/{id}/role-mappings/realm)
Delete realm-level role mappings (DELETE /{realm}/users/{id}/role-mappings/realm)
Get realm-level roles that can be mapped (GET /{realm}/users/{id}/role-mappings/realm/available)
Get effective realm-level role mappings This will recurse all composite roles to get the result. (GET /{realm}/users/{id}/role-mappings/realm/composite)

Group

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/groups.spec.ts

Create (POST /{realm}/groups)
List (GET /{realm}/groups)
Get one (GET /{realm}/groups/{id})
Update (PUT /{realm}/groups/{id})
Delete (DELETE /{realm}/groups/{id})
Count (GET /{realm}/groups/count)
List members (GET /{realm}/groups/{id}/members)
Set or create child (POST /{realm}/groups/{id}/children)

Group role-mapping

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/groups.spec.ts#L76

Get group role-mappings (GET /{realm}/groups/{id}/role-mappings)
Add realm-level role mappings to the group (POST /{realm}/groups/{id}/role-mappings/realm)
Get realm-level role mappings (GET /{realm}/groups/{id}/role-mappings/realm)
Delete realm-level role mappings (DELETE /{realm}/groups/{id}/role-mappings/realm)
Get realm-level roles that can be mapped (GET /{realm}/groups/{id}/role-mappings/realm/available)

Client

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/clients.spec.ts

Create a new client (POST /{realm}/clients)
Get clients belonging to the realm (GET /{realm}/clients)
Get representation of the client (GET /{realm}/clients/{id})
Update the client (PUT /{realm}/clients/{id})
Delete the client (DELETE /{realm}/clients/{id})

Client roles

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/clients.spec.ts

Create a new role for the client (POST /{realm}/clients/{id}/roles)
Get all roles for the client (GET /{realm}/clients/{id}/roles)
Get a role by name (GET /{realm}/clients/{id}/roles/{role-name})
Update a role by name (PUT /{realm}/clients/{id}/roles/{role-name})
Delete a role by name (DELETE /{realm}/clients/{id}/roles/{role-name})

Client role-mapping for group

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/groups.spec.ts#L150

Add client-level roles to the group role mapping (POST /{realm}/groups/{id}/role-mappings/clients/{client})
Get client-level role mappings for the group (GET /{realm}/groups/{id}/role-mappings/clients/{client})
Delete client-level roles from group role mapping (DELETE /{realm}/groups/{id}/role-mappings/clients/{client})
Get available client-level roles that can be mapped to the group (GET /{realm}/groups/{id}/role-mappings/clients/{client}/available)

Client role-mapping for user

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/users.spec.ts#L217

Add client-level roles to the user role mapping (POST /{realm}/users/{id}/role-mappings/clients/{client})
Get client-level role mappings for the user (GET /{realm}/users/{id}/role-mappings/clients/{client})
Delete client-level roles from user role mapping (DELETE /{realm}/users/{id}/role-mappings/clients/{client})
Get available client-level roles that can be mapped to the user (GET /{realm}/users/{id}/role-mappings/clients/{client}/available)

Identity Providers

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/idp.spec.ts

Create a new identity provider (POST /{realm}/identity-provider/instances)
Get identity providers (GET /{realm}/identity-provider/instances)
Get the identity provider (GET /{realm}/identity-provider/instances/{alias})
Update the identity provider (PUT /{realm}/identity-provider/instances/{alias})
Delete the identity provider (DELETE /{realm}/identity-provider/instances/{alias})
Find identity provider factory (GET /{realm}/identity-provider/providers/{providerId})
Create a new identity provider mapper (POST /{realm}/identity-provider/instances/{alias}/mappers)
Get identity provider mappers (GET /{realm}/identity-provider/instances/{alias}/mappers)
Get the identity provider mapper (GET /{realm}/identity-provider/instances/{alias}/mappers/{id})
Update the identity provider mapper (PUT /{realm}/identity-provider/instances/{alias}/mappers/{id})
Delete the identity provider mapper (DELETE /{realm}/identity-provider/instances/{alias}/mappers/{id})
Find the identity provider mapper types (GET /{realm}/identity-provider/instances/{alias}/mapper-types)

Client Scopes

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/clientScopes.spec.ts

Create a new client scope (POST /{realm}/client-scopes)
Get client scopes belonging to the realm (GET /{realm}/client-scopes)
Get representation of the client scope (GET /{realm}/client-scopes/{id})
Update the client scope (PUT /{realm}/client-scopes/{id})
Delete the client scope (DELETE /{realm}/client-scopes/{id})

Client Scopes for realm

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/clientScopes.spec.ts

Get realm default client scopes (GET /{realm}/default-default-client-scopes)
Add realm default client scope (PUT /{realm}/default-default-client-scopes/{id})
Delete realm default client scope (DELETE /{realm}/default-default-client-scopes/{id})
Get realm optional client scopes (GET /{realm}/default-optional-client-scopes)
Add realm optional client scope (PUT /{realm}/default-optional-client-scopes/{id})
Delete realm optional client scope (DELETE /{realm}/default-optional-client-scopes/{id})

Client Scopes for client

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/clientScopes.spec.ts

Get default client scopes (GET /{realm}/clients/{id}/default-client-scopes)
Add default client scope (PUT /{realm}/clients/{id}/default-client-scopes/{clientScopeId})
Delete default client scope (DELETE /{realm}/clients/{id}/default-client-scopes/{clientScopeId})
Get optional client scopes (GET /{realm}/clients/{id}/optional-client-scopes)
Add optional client scope (PUT /{realm}/clients/{id}/optional-client-scopes/{clientScopeId})
Delete optional client scope (DELETE /{realm}/clients/{id}/optional-client-scopes/{clientScopeId})

Scope Mappings for client scopes

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/clientScopes.spec.ts

Get all scope mappings for the client (GET /{realm}/client-scopes/{id}/scope-mappings)
Add client-level roles to the client’s scope (POST /{realm}/client-scopes/{id}/scope-mappings/clients/{client})
Get the roles associated with a client’s scope (GET /{realm}/client-scopes/{id}/scope-mappings/clients/{client})
The available client-level roles (GET /{realm}/client-scopes/{id}/scope-mappings/clients/{client}/available)
Get effective client roles (GET /{realm}/client-scopes/{id}/scope-mappings/clients/{client}/composite)
Remove client-level roles from the client’s scope. (DELETE /{realm}/client-scopes/{id}/scope-mappings/clients/{client})
Add a set of realm-level roles to the client’s scope (POST /{realm}/client-scopes/{id}/scope-mappings/realm)
Get realm-level roles associated with the client’s scope (GET /{realm}/client-scopes/{id}/scope-mappings/realm)
Remove a set of realm-level roles from the client’s scope (DELETE /{realm}/client-scopes/{id}/scope-mappings/realm)
Get realm-level roles that are available to attach to this client’s scope (GET /{realm}/client-scopes/{id}/scope-mappings/realm/available)
Get effective realm-level roles associated with the client’s scope (GET /{realm}/client-scopes/{id}/scope-mappings/realm/composite)

Scope Mappings for clients

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/clientScopes.spec.ts

Get all scope mappings for the client (GET /{realm}/clients/{id}/scope-mappings)
Add client-level roles to the client’s scope (POST /{realm}/clients/{id}/scope-mappings/clients/{client})
Get the roles associated with a client’s scope (GET /{realm}/clients/{id}/scope-mappings/clients/{client})
Remove client-level roles from the client’s scope. (DELETE /{realm}/clients/{id}/scope-mappings/clients/{client})
The available client-level roles (GET /{realm}/clients/{id}/scope-mappings/clients/{client}/available)
Get effective client roles (GET /{realm}/clients/{id}/scope-mappings/clients/{client}/composite)
Add a set of realm-level roles to the client’s scope (POST /{realm}/clients/{id}/scope-mappings/realm)
Get realm-level roles associated with the client’s scope (GET /{realm}/clients/{id}/scope-mappings/realm)
Remove a set of realm-level roles from the client’s scope (DELETE /{realm}/clients/{id}/scope-mappings/realm)
Get realm-level roles that are available to attach to this client’s scope (GET /{realm}/clients/{id}/scope-mappings/realm/available)
Get effective realm-level roles associated with the client’s scope (GET /{realm}/clients/{id}/scope-mappings/realm/composite)

Protocol Mappers for client scopes

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/clientScopes.spec.ts

Create multiple mappers (POST /{realm}/client-scopes/{id}/protocol-mappers/add-models)
Create a mapper (POST /{realm}/client-scopes/{id}/protocol-mappers/models)
Get mappers (GET /{realm}/client-scopes/{id}/protocol-mappers/models)
Get mapper by id (GET /{realm}/client-scopes/{id}/protocol-mappers/models/{mapperId})
Update the mapper (PUT /{realm}/client-scopes/{id}/protocol-mappers/models/{mapperId})
Delete the mapper (DELETE /{realm}/client-scopes/{id}/protocol-mappers/models/{mapperId})
Get mappers by name for a specific protocol (GET /{realm}/client-scopes/{id}/protocol-mappers/protocol/{protocol})

Protocol Mappers for clients

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/clients.spec.ts

Create multiple mappers (POST /{realm}/clients/{id}/protocol-mappers/add-models)
Create a mapper (POST /{realm}/clients/{id}/protocol-mappers/models)
Get mappers (GET /{realm}/clients/{id}/protocol-mappers/models)
Get mapper by id (GET /{realm}/clients/{id}/protocol-mappers/models/{mapperId})
Update the mapper (PUT /{realm}/clients/{id}/protocol-mappers/models/{mapperId})
Delete the mapper (DELETE /{realm}/clients/{id}/protocol-mappers/models/{mapperId})
Get mappers by name for a specific protocol (GET /{realm}/clients/{id}/protocol-mappers/protocol/{protocol})

Component

Supported for user federation. Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/components.spec.ts

Create (POST /{realm}/components)
List (GET /{realm}/components)
Get (GET /{realm}/components/{id})
Update (PUT /{realm}/components/{id})
Delete (DELETE /{realm}/components/{id})

Sessions for clients

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/clients.spec.ts

List user sessions for a specific client (GET /{realm}/clients/{id}/user-sessions)
List offline sessions for a specific client (GET /{realm}/clients/{id}/offline-sessions)
Get user session count for a specific client (GET /{realm}/clients/{id}/session-count)
List offline session count for a specific client (GET /{realm}/clients/{id}/offline-session-count)

Authentication Management: Required actions

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/authenticationManagement.spec.ts

Register a new required action (POST /{realm}/authentication/register-required-action)
Get required actions. Returns a list of required actions. (GET /{realm}/authentication/required-actions)
Get required action for alias (GET /{realm}/authentication/required-actions/{alias})
Update required action (PUT /{realm}/authentication/required-actions/{alias})
Delete required action (DELETE /{realm}/authentication/required-actions/{alias})
Lower required action’s priority (POST /{realm}/authentication/required-actions/{alias}/lower-priority)
Raise required action’s priority (POST /{realm}/authentication/required-actions/{alias}/raise-priority)
Get unregistered required actions Returns a list of unregistered required actions. (GET /{realm}/authentication/unregistered-required-actions)

Authorization: Permission

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/clients.spec.ts

Create permission (POST /{realm}/clients/{id}/authz/resource-server/permission/{type})
Get permission (GET /{realm}/clients/{id}/authz/resource-server/permission/{type}/{permissionId})
Update permission (PUT /{realm}/clients/{id}/authz/resource-server/permission/{type}/{permissionId})
Delete permission (DELETE /{realm}/clients/{id}/authz/resource-server/permission/{type}/{permissionId})

Authorization: Policy

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/clients.spec.ts

Create policy (POST /{realm}/clients/{id}/authz/resource-server/policy/{type})
Get policy (GET /{realm}/clients/{id}/authz/resource-server/policy/{type}/{policyId})
Get policy by name (GET /{realm}/clients/{id}/authz/resource-server/policy/search)
Update policy (PUT /{realm}/clients/{id}/authz/resource-server/policy/{type}/{policyId})
Delete policy (DELETE /{realm}/clients/{id}/authz/resource-server/policy/{policyId})

Attack Detection

Demo code: https://github.com/keycloak/keycloak-nodejs-admin-client/blob/master/test/attackDetection.spec.ts

Clear any user login failures for all users This can release temporary disabled users (DELETE /{realm}/attack-detection/brute-force/users)
Get status of a username in brute force detection (GET /{realm}/attack-detection/brute-force/users/{userId})
Clear any user login failures for the user This can release temporary disabled user (DELETE /{realm}/attack-detection/brute-force/users/{userId})

Not yet supported

Authentication Management
Client Attribute Certificate
Client Initial Access
Client Registration Policy
Key
User Storage Provider

Maintainers

Checkout MAINTAINERS.md for detailed maintainers list.

This repo is originally developed by Canner and InfuseAI before being transferred under keycloak organization.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

keycloak-admin

Features

Install

Usage

Supported APIs

Realm admin

Role

Roles (by ID)

User

User group-mapping

User role-mapping

Group

Group role-mapping

Client

Client roles

Client role-mapping for group

Client role-mapping for user

Identity Providers

Client Scopes

Client Scopes for realm

Client Scopes for client

Scope Mappings for client scopes

Scope Mappings for clients

Protocol Mappers for client scopes

Protocol Mappers for clients

Component

Sessions for clients

Authentication Management: Required actions

Authorization: Permission

Authorization: Policy

Attack Detection

Not yet supported

Maintainers

Files

README.md

Latest commit

History

README.md

File metadata and controls

keycloak-admin

Features

Install

Usage

Supported APIs

User group-mapping

User role-mapping

Group role-mapping

Not yet supported

Maintainers