Node.js Keycloak admin client
- TypeScript supported
- Keycloak latest version (v4.1) supported
- Complete resource definitions
- Well-tested for supported APIs
yarn add keycloak-admin
import KcAdminClient from 'keycloak-admin';
// 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',
});
// 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()
});
// 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
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}
)
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
)
- 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}
)
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}
) - 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
)
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
)
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}
) - List members (
GET /{realm}/groups/{id}/members
) - Set or create child (
POST /{realm}/groups/{id}/children
)
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
)
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}
)
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}
)
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
)
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
)
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
)
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}
)
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}
)
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}
)
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
)
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
)
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}
)
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}
)
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}
)
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
)
- Attack Detection
- Authentication Management
- Client Attribute Certificate
- Client Initial Access
- Client Registration Policy
- Key
- User Storage Provider
Checkout MAINTAINERS.md for detailed maintainers list.
This repo is originally developed by Canner and InfuseAI before being transferred under keycloak organization.