keycloak-api-manager 3.1.0 → 3.2.1

package/.mocharc.json

@@ -0,0 +1,7 @@
+{
+  "require": ["test/mocha.env.js"],
+  "timeout": 15000,
+  "spec": "test/**/*.test.js",
+  "reporter": "spec",
+  "parallel": false
+}

package/Handlers/authenticationManagementHandler.js

@@ -218,7 +218,7 @@ exports.updateRequiredAction=function(filter,actionRepresentation){
  * @parameters:
  * - filter: parameter provided as a JSON object that accepts the following filter:
  *     - alias: [required] The alias (providerId) of the required action to update.
- * - actionRepresentation: The configuration object to update.
+ * - actionConfigRepresentation: The configuration object to update.
  */
 exports.updateRequiredActionConfig=function(filter, actionConfigRepresentation){
  return (kcAdminClientHandler.authenticationManagement.updateRequiredActionConfig(filter,actionConfigRepresentation));

package/Handlers/clientScopesHandler.js

@@ -20,8 +20,8 @@ exports.setKcAdminClient=function(kcAdminClient){
  * A client scope defines a set of protocol mappers and roles that can be applied to clients,
  * such as during login or token generation.
  */
-exports.create=function(scopeRappresentation){
- return (kcAdminClientHandler.clientScopes.create(scopeRappresentation ));
+exports.create=function(scopeRepresentation){
+ return (kcAdminClientHandler.clientScopes.create(scopeRepresentation ));
 }
 
 
@@ -35,13 +35,13 @@ exports.create=function(scopeRappresentation){
  * - filter: parameter provided as a JSON object that accepts the following filter:
  *     - id: [required] The unique ID of the client scope to update.
  *     - realm: [optional] The realm where the client scope exists.
- * - scopeRappresentation: The updated client scope object.
+ * - scopeRepresentation: The updated client scope object.
  *     - name: [optional] The name of the scope
  *     - description: [optional] The scope description
  *     - {other scope fields}
  */
-exports.update=function(filter,scopeRappresentation){
- return (kcAdminClientHandler.clientScopes.update(filter,scopeRappresentation ));
+exports.update=function(filter,scopeRepresentation){
+ return (kcAdminClientHandler.clientScopes.update(filter,scopeRepresentation ));
 }
 
 

package/Handlers/clientsHandler.js

@@ -195,7 +195,7 @@ exports.getClientSecret=function(filter){
  *      - id: [required] The internal ID of the client (not clientId)
  */
 exports.generateNewClientSecret=function(filter){
- return (kcAdminClientHandler.clients.creatgenerateNewClientSecrete(filter));
+ return (kcAdminClientHandler.clients.generateNewClientSecret(filter));
 }
 
 

package/Handlers/componentsHandler.js

@@ -60,8 +60,8 @@ exports.create=function(componentRepresentation){
  *          - bindCredential: ["secret"],
  *          - usersDn: ["ou=users,dc=example,dc=com"]
  */
-exports.update=function(filters, componentRepresentation){
- return (kcAdminClientHandler.components.update(filters, componentRepresentation));
+exports.update=function(filter, componentRepresentation){
+ return (kcAdminClientHandler.components.update(filter, componentRepresentation));
 }
 
 

package/Handlers/groupsHandler.js

@@ -25,8 +25,8 @@ exports.setKcAdminClient=function(kcAdminClient){
  *     - description: [optional] the new group Description
  *     - {other [optional] group description fields}
  */
-exports.create=function(groupRappresentation){
- return (kcAdminClientHandler.groups.create(groupRappresentation));
+exports.create=function(groupRepresentation){
+ return (kcAdminClientHandler.groups.create(groupRepresentation));
 }
 
 

package/Handlers/identityProvidersHandler.js

@@ -18,7 +18,7 @@ exports.setKcAdminClient=function(kcAdminClient){
  * or another SAML/OIDC provider.
  * This method requires specifying an alias, the provider type, and configuration settings such as client ID, client secret, and any other provider-specific options.
  * @parameters:
- * - identityProvidersRappresentation: parameter provided as a JSON object containing the configuration of the Identity Provider
+ * - identityProvidersRepresentation: parameter provided as a JSON object containing the configuration of the Identity Provider
  *      - alias: [required] Unique name for the IdP within the realm.
  *      - providerId: [required] Type of provider (google, facebook, oidc, saml, etc.).
  *      - enabled: [optional] Whether the IdP is enabled. Default is true.
@@ -29,8 +29,8 @@ exports.setKcAdminClient=function(kcAdminClient){
  *      - firstBrokerLoginFlowAlias: [optional] Flow to use on first login.
  *      - config : [optional] Provider-specific configuration, e.g., client ID, client secret, endpoints, etc.
  */
-exports.create=function(identityProvidersRappresentation){
- return (kcAdminClientHandler.identityProviders.create(identityProvidersRappresentation));
+exports.create=function(identityProvidersRepresentation){
+ return (kcAdminClientHandler.identityProviders.create(identityProvidersRepresentation));
 }
 
 /**

package/README.md

@@ -95,7 +95,7 @@ const express = require('express');
 // Initialize the manager with Keycloak credentials
 await KeycloakManager.configure({
     baseUrl: 'http://localhost:8080',   // Keycloak base URL
-    realm: 'master',                    // Realm where the admin user belongs
+    realmName: 'master',                // Realm where the admin user belongs (alias: realm)
     clientId: 'admin-cli',              // Keycloak admin client
     username: 'admin',                  // Admin username
     password: 'admin',                  // Admin password
@@ -165,7 +165,7 @@ const KeycloakManager = require('keycloak-api-manager');
 // Initialize the manager with Keycloak credentials
 await KeycloakManager.configure({
     baseUrl: 'http://localhost:8080',   // Keycloak base URL
-    realm: 'master',                    // Realm where the admin user belongs
+    realmName: 'master',                // Realm where the admin user belongs (alias: realm)
     clientId: 'admin-cli',              // Keycloak admin client
     username: 'admin',                  // Admin username
     password: 'admin',                  // Admin password
@@ -186,7 +186,8 @@ Parameters:
   exposed by this adapter, so any attempt to call KeycloakManager.{function} will result in a runtime error due to access on an undefined object
   Main supported options:
   - baseUrl: [required] Keycloak base Url
-  - realmName: [required] A String that specifies the realm to authenticate against, if different from the "keyCloakConfig.realm" parameter.  If you intend to use Keycloak administrator credentials, this should be set to 'master'.
+    - realmName: [required] A String that specifies the realm to authenticate against, if different from the "keyCloakConfig.realm" parameter.  If you intend to use Keycloak administrator credentials, this should be set to 'master'.
+    - realm: [optional] Alias of realmName for backward compatibility.
   - grantType: [required] The OAuth2 grant type used for authentication. example "password". Possible values: 'password', 'client_credentials', 'refresh_token', etc.
   - clientId: [required] string containing the client ID configured in Keycloak. Required for all grant types.
   - tokenLifeSpan: [required] Numeric Lifetime of an access token expressed in seconds. It indicates how often the access token should be renewed. If set incorrectly and the Keycloak token expires before the renewal interval defined by this parameter, errors and exceptions may occur
@@ -200,6 +201,101 @@ Parameters:
   - refreshToken: [Optional] string containing a valid refresh token to request a new access token when using the refresh_token grant type.
 ---
 
+## 🧰 Available Helper Functions
+
+### `function setConfig(config)`
+This function updates the runtime configuration of the Keycloak-api-manager Admin Client instance.
+It allows switching the target realm, base URL, or HTTP request options without reinitializing the client or re-authenticating.
+It’s useful when you need to interact with multiple realms or environments dynamically using the same admin client instance.
+
+**` -- @parameters -- `**
+- config: is a JSON object that accepts the following parameters:
+  - realmName: [optional] The name of the target realm for subsequent API requests. 
+  - baseUrl: [optional] The base URL of the Keycloak server (e.g., https://auth.example.com). 
+  - requestOptions: [optional] Custom HTTP options (headers, timeout, etc.) applied to API calls. 
+  - realmPath: [optional] A custom realm path if your Keycloak instance uses a non-standard realm route.
+  - other fields
+
+**` -- @notes -- `**
+Calling setConfig does not perform authentication 
+- it only changes configuration values in memory.
+- The authentication token already stored in the admin client remains active until it expires.
+- Only the properties explicitly passed in the config object are updated; all others remain unchanged.
+
+If the authenticated user does not have permissions in the new realmName, subsequent calls may fail with a 403 or 404.
+
+Typically used in multi-realm or multi-environment management scripts.
+
+```js
+const KcAdminClient = require('keycloak-api-manager');
+
+
+// Switch context to another realm dynamically
+kcAdminClient.setConfig({
+  realmName: 'customer-realm',
+});
+
+// All subsequent API calls will target "customer-realm"
+const users = await kcAdminClient.users.find();
+console.log(users);
+```
+
+### `function getToken()`
+This function retrieves the current authentication tokens used by the Keycloak-api-manager Admin Client to communicate with the Keycloak REST API.
+It returns both the access token (used for API authorization) and the refresh token (used to renew the session when the access token expires).
+
+**` -- @returns -- `**
+A JSON object containing:
+- accessToken: The active access token string currently held by the Keycloak Admin Client. 
+- refreshToken: The corresponding refresh token string, if available, used to request a new access token without re-authentication.
+
+**` -- @notes -- `**
+The tokens are managed internally by the Keycloak Admin Client after successful authentication via kcAdminClient.auth().
+The accessToken typically expires after a short period (e.g., 60 seconds by default).
+You can use these tokens to call Keycloak REST endpoints manually or to debug authorization issues.
+If the client is not authenticated or the session has expired, both values may be undefined.
+
+```js
+const KcAdminClient = require('keycloak-api-manager');
+
+// Example: retrieve and print current tokens
+try {
+  const tokens = KcAdminClient.getToken();
+  console.log('Access Token:', tokens.accessToken);
+  console.log('Refresh Token:', tokens.refreshToken);
+} catch (error) {
+  console.error('Failed to retrieve tokens:', error);
+}
+
+```
+### `function auth(credentials)`
+This function allows a user or client to authenticate against a Keycloak realm and obtain an access token (and optionally a refresh token).
+It sends a direct HTTP POST request to the Keycloak OpenID Connect token endpoint using the provided credentials.
+
+**` -- @parameters -- `**
+credentials: a JSON object containing authentication details. Supported fields include:
+- username: [optional] Username of the user (required for password grant). 
+- password: [optional] Password of the user (required for password grant). 
+- grant_type: [required] The OAuth2 grant type (e.g. "password", "client_credentials", "refresh_token"). 
+
+
+```js
+const KeycloakManager = require('keycloak-api-manager');
+
+// Example: authenticate a user via password grant
+try {
+  const tokenResponse = await KeycloakManager.auth({
+    username: "demo",
+    password: "demo123",
+    grant_type: "password",
+  });
+
+  console.log("Access Token:", tokenResponse.access_token);
+} catch (error) {
+  console.error("Authentication failed:", error);
+}
+
+```
 
 ## 🔧 Available Admin Functions
 All administrative functions that rely on Keycloak's Admin API must be invoked using the
@@ -317,7 +413,7 @@ It’s useful for incremental updates or merging configuration pieces.
 **` -- @parameters -- `**
 - configuration: is a JSON object that accepts filter parameters
   - realm:[required] The name of the realm where the data should be imported.
-  - representation:[required] A JSON object representing part of the realm configuration to be imported(can include users, roles, groups, clients, etc.).
+  - rep:[required] A JSON object representing part of the realm configuration to be imported(can include users, roles, groups, clients, etc.).
     - ifResourceExists:[required] Defines the behavior when an imported resource already exists in the target realm.
         Options are:
       - 'FAIL' – the operation fails if a resource already exists.
@@ -1855,7 +1951,10 @@ Creates a new client with the provided configuration
 ```js
 const KeycloakManager = require('keycloak-api-manager');
  // create a client called my-client
- const client= await KeycloakManager.clients.create({name: "my-client", id:"client-id"});
+ const client= await KeycloakManager.clients.create({
+    name: "my-client",
+    clientId:"client-id"
+ });
 console.log("New Client Created:", client);
  ```
 
@@ -2238,7 +2337,7 @@ Default client scopes are automatically assigned to a client during token reques
 
 **` -- @parameters -- `**
 - filter: JSON structure that defines the filter parameters:
-    - id: [required] The client ID of the client whose default client scopes you want to list.
+    - id: [required] The internal ID of the client whose default client scopes you want to list.
 
 ```js
 const KeycloakManager = require('keycloak-api-manager');
@@ -2258,7 +2357,7 @@ Optional scopes are those that a client can request explicitly but are not autom
 
 **` -- @parameters -- `**
 - filter: JSON structure that defines the filter parameters:
-    - id: [required] The client ID of the client whose optional client scopes you want to list.
+    - id: [required] The internal ID of the client whose optional client scopes you want to list.
 
 ```js
 const KeycloakManager = require('keycloak-api-manager');
@@ -3943,7 +4042,7 @@ Client scopes are reusable sets of protocol mappers and role scope mappings whic
 can be assigned to clients to define what information about the user is included in tokens and what roles are available.
 
 #### `entity clientScopes functions`
-##### `function create(scopeRappresentation)`
+##### `function create(scopeRepresentation)`
 method is used to create a new client scope in a Keycloak realm.
 A client scope defines a set of protocol mappers and roles that can be applied to clients,
 such as during login or token generation.
@@ -3958,7 +4057,7 @@ const KeycloakManager = require('keycloak-api-manager');
  ```
 
 
-##### `function update(filter,scopeRappresentation)`
+##### `function update(filter,scopeRepresentation)`
 The method updates the configuration of an existing client scope in a realm.
 You can modify properties such as the scope’s name, description, attributes, or protocol mappers.
 
@@ -3966,7 +4065,7 @@ You can modify properties such as the scope’s name, description, attributes, o
 - filter: parameter provided as a JSON object that accepts the following filter:
     - id: [required] The unique ID of the client scope to update.
     - realm: [optional] The realm where the client scope exists. 
-- scopeRappresentation: The updated client scope object. for example:
+- scopeRepresentation: The updated client scope object. for example:
   - name: [optional] The name of the scope
   - description: [optional] The scope description
   - other scope fields....
@@ -4795,14 +4894,14 @@ These are providers like Google, Facebook, GitHub, SAML, OIDC, etc.
 
 #### `entity identityProviders functions`
 
-##### `function identityProviders.create(identityProvidersRappresentation)`
+##### `function identityProviders.create(identityProvidersRepresentation)`
 The method is used to create a new Identity Provider (IdP) in a Keycloak realm. 
 An IdP allows users to authenticate via external providers such as Google, Facebook, GitHub, 
 or another SAML/OIDC provider. 
 This method requires specifying an alias, the provider type, and configuration settings such as client ID, client secret, and any other provider-specific options.
 
 **` -- @parameters -- `**
-- identityProvidersRappresentation: parameter provided as a JSON object containing the configuration of the Identity Provider
+- identityProvidersRepresentation: parameter provided as a JSON object containing the configuration of the Identity Provider
     - alias: [required] Unique name for the IdP within the realm. 
     - providerId: [required] Type of provider (google, facebook, oidc, saml, etc.). 
     - enabled: [optional] Whether the IdP is enabled. Default is true. 
@@ -5185,7 +5284,7 @@ Groups are collections of users and can have roles and attributes assigned to th
 Groups help organize users and assign permissions in a scalable way
 
 #### `entity groups functions`
-##### `function create(groupRappresentation)`
+##### `function create(groupRepresentation)`
 Create a new group in the current realme
 
 **` -- @parameters -- `**
@@ -5637,7 +5736,7 @@ Get a role by its Id
 
 **` -- @parameters -- `**
 - filters: parameter provided as a JSON object that accepts the following parameters:
-    - Id (string, required) — The Id of the role to retrieve.
+    - id (string, required) — The id of the role to retrieve.
     - realm (string, optional if set globally) — The realm where the role is defined.
 ```js
 const KeycloakManager = require('keycloak-api-manager');
@@ -5664,7 +5763,7 @@ Update a role by its Id
 
 **` -- @parameters -- `**
 - filters: parameter provided as a JSON object that accepts the following parameters:
-    - name (string, required) — The exact name of the role to retrieve.
+    - id (string, required) — The id of the role to retrieve.
     - realm (string, optional if set globally) — The realm where the role is defined.
 - role_dictionary: A JSON object representing a role dictionary as defined in Keycloak
 ```js
@@ -6194,7 +6293,7 @@ This allows you to modify settings such as OTP policies, password requirements,
 **` -- @parameters -- `**
 - filter: parameter provided as a JSON object that accepts the following filter:
     - alias: [required] The alias (providerId) of the required action to update.
-- actionRepresentation: The configuration object to update. 
+- actionConfigRepresentation: The configuration object to update. 
   
   
 ```js

package/docker-compose.yml

@@ -0,0 +1,27 @@
+version: '3.8'
+
+services:
+  keycloak:
+    image: keycloak/keycloak:latest
+    container_name: keycloak-test
+    ports:
+      - "8080:8080"
+    environment:
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: admin
+      KC_DB: dev-mem
+      KC_METRICS_ENABLED: 'false'
+      KC_HEALTH_ENABLED: 'true'
+    command:
+      - start-dev
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health/ready"]
+      interval: 5s
+      timeout: 5s
+      retries: 12
+    networks:
+      - keycloak-network
+
+networks:
+  keycloak-network:
+    driver: bridge

package/index.js

@@ -96,7 +96,7 @@ exports.setConfig=function(configToOverride){
 }
 //TODO: Remove da documentare
 // restituisce il token utilizzato dalla libreria per comunicare con la keycloak API
-exports.getToken=function(configToOverride){
+exports.getToken=function(){
         return({
                 accessToken:kcAdminClient.accessToken,
                 refreshToken:kcAdminClient.refreshToken,

package/index.mjs

@@ -0,0 +1,21 @@
+/**
+ * ESM wrapper for keycloak-api-manager
+ * This file provides ES Module support while the core is still CommonJS
+ */
+
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import path from 'path';
+
+const require = createRequire(import.meta.url);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const keycloakApiManager = require('./index.js');
+
+export const configure = keycloakApiManager.configure;
+export const setConfig = keycloakApiManager.setConfig;
+export const getToken = keycloakApiManager.getToken;
+export const auth = keycloakApiManager.auth;
+
+export default keycloakApiManager;

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "keycloak-api-manager",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "description": "Keycloak-api-manager is a lightweight Node.js wrapper for the Keycloak Admin REST API. It provides an easy-to-use functional methods and functions to manage realms, users, roles, clients, groups, and permissions directly from your application code — just like you would from the Keycloak admin console.",
   "main": "index.js",
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "require": "./index.js"
+    }
+  },
   "scripts": {
-    "test": "mocha"
+    "test": "mocha",
+    "test:watch": "mocha --watch --watch-extensions js"
   },
   "dependencies": {
     "@keycloak/keycloak-admin-client": "^26.3.2",
@@ -23,6 +30,11 @@
     "serve-favicon": "^2.5.0",
     "underscore": "^1.13.7"
   },
+  "devDependencies": {
+    "chai": "^4.3.10",
+    "mocha": "^10.2.0",
+    "dockerode": "^4.0.2"
+  },
   "keywords": [
     "keycloak",
     "user",