keycloak-api-manager 4.0.0 → 5.0.0

package/docs/architecture.md

@@ -0,0 +1,47 @@
+# Architecture and Runtime
+
+This package exposes a single runtime (`index.js`) that initializes one Keycloak admin client instance and wires all handler modules.
+
+## Runtime Lifecycle
+
+1. `configure(credentials)`
+   - Validates and normalizes runtime configuration.
+   - Authenticates against Keycloak.
+   - Starts automatic token refresh.
+   - Injects the configured client into all handlers.
+
+2. `setConfig(overrides)`
+   - Updates realm/baseUrl/request options at runtime.
+   - Keeps active session/token management in place.
+
+3. `auth(credentials)`
+   - Direct token endpoint call for explicit auth flows.
+
+4. `stop()`
+   - Stops refresh timer for clean process termination.
+
+## Handler Design
+
+Each file in `Handlers/` receives the configured Keycloak client through `setKcAdminClient`.
+
+Pattern:
+
+- Keep wrapper methods thin and explicit.
+- Use official client methods whenever possible.
+- Use direct REST calls only for endpoints not fully covered by `@keycloak/keycloak-admin-client`.
+
+## Direct API Wrappers
+
+Some handlers (for example Organizations update behavior) use direct `fetch` calls to match real Keycloak endpoint requirements.
+
+Guideline:
+
+- Prefer wrapper parity with official endpoints.
+- Keep payload shaping close to Keycloak server expectations.
+- Avoid test-specific logic in production handlers.
+
+## Error Handling Principles
+
+- Fail fast on missing configuration.
+- Preserve Keycloak error context in thrown messages.
+- Keep behavior deterministic between local/remote Keycloak instances.

package/docs/deployment.md

@@ -0,0 +1,32 @@
+# Deployment Guide (Local and Remote)
+
+This guide covers test/development Keycloak deployment options used by this project.
+
+## Local Deployment
+
+### HTTP (fast dev)
+
+- Start compose from `test/docker-keycloak/`.
+- Use `http://localhost:8080` as base URL.
+
+### HTTPS (production-like)
+
+- Provide certificate and key (`keycloak.crt`, `keycloak.key`).
+- Expose `8443` and set hostname consistently.
+
+## Remote Deployment (SSH)
+
+- Copy compose and optional cert files to remote host.
+- Start container remotely.
+- Verify readiness and endpoint reachability.
+
+## Recommended Verification Checklist
+
+- Container healthy
+- Token endpoint reachable
+- Admin endpoint reachable
+- Feature flags active (`admin-fine-grained-authz:v1,organization,client-policies`)
+
+## Operational Tip
+
+For automated test runs against remote hosts, keep test `baseUrl` aligned with reachable hostname/certificate pair to avoid TLS and normalization errors.

package/docs/keycloak-setup.md

@@ -0,0 +1,47 @@
+# Keycloak Setup and Feature Flags
+
+This guide describes the server-side prerequisites required for full package functionality.
+
+## Minimum Recommended Setup
+
+- Keycloak 25+ (26.x recommended)
+- Admin user in `master` realm (or equivalent privileged client)
+- HTTPS strongly recommended outside local development
+
+## Required Feature Flags
+
+```bash
+--features=admin-fine-grained-authz:v1,organization,client-policies
+```
+
+### Notes
+
+- `admin-fine-grained-authz:v1`: required for management-permissions APIs used by group/user permission flows in this package.
+- `organization`: required for Organizations endpoints.
+- `client-policies`: required for client policy/profile endpoints.
+
+## Docker Example
+
+```bash
+docker run -d --name keycloak \
+  -p 8080:8080 -p 8443:8443 \
+  -e KEYCLOAK_ADMIN=admin \
+  -e KEYCLOAK_ADMIN_PASSWORD=admin \
+  -e KC_FEATURES=admin-fine-grained-authz:v1,organization,client-policies \
+  keycloak/keycloak:latest start-dev
+```
+
+## Compose Example
+
+```yaml
+environment:
+  KEYCLOAK_ADMIN: admin
+  KEYCLOAK_ADMIN_PASSWORD: admin
+  KC_FEATURES: 'admin-fine-grained-authz:v1,organization,client-policies'
+```
+
+## Verify Server Readiness
+
+- Health endpoint should be reachable.
+- Token endpoint should issue admin tokens.
+- Admin endpoints should not return `Feature not enabled` for enabled features.

package/docs/test-configuration.md

@@ -0,0 +1,43 @@
+# Test Configuration
+
+Test configuration is managed through `propertiesmanager` with layered files.
+
+## Files and Priority
+
+1. `test/config/default.json` (committed defaults)
+2. `test/config/secrets.json` (gitignored sensitive values)
+3. `test/config/local.json` (gitignored machine-specific overrides)
+
+The active section is selected by `NODE_ENV` (defaults to `test` in suite bootstrap).
+
+## Required Keys
+
+- `test.keycloak.baseUrl`
+- `test.keycloak.realmName`
+- `test.keycloak.clientId`
+- `test.keycloak.username`
+- `test.keycloak.password` (typically in `secrets.json`)
+- `test.keycloak.grantType`
+
+## Example `secrets.json`
+
+```json
+{
+  "test": {
+    "keycloak": {
+      "password": "admin"
+    },
+    "realm": {
+      "user": {
+        "password": "test-password"
+      }
+    }
+  }
+}
+```
+
+## Security Rules
+
+- Never commit `secrets.json`.
+- Never commit production credentials.
+- Keep `default.json` non-sensitive.

package/docs/testing.md

@@ -0,0 +1,60 @@
+# Testing Guide
+
+The test suite validates the package against a real Keycloak server.
+
+## Test Architecture
+
+The suite uses a shared realm strategy:
+
+- One global setup provisions baseline resources.
+- Test files create their own unique entities where needed.
+- Global teardown removes the shared test realm.
+
+This improves speed and keeps the environment deterministic.
+
+## Current Test Layout
+
+```text
+test/
+  specs/
+    *.test.js                 # core suites
+    diagnostics/*.test.js     # diagnostic-style suites
+    matrix/*.test.js          # data-driven matrix suites
+  support/
+    setup.js
+    enableServerFeatures.js
+    testConfig.js
+```
+
+## Commands
+
+```bash
+# full suite
+npm test
+
+# run only test workspace
+npm --prefix test test
+
+# grep a subset
+npm --prefix test test -- --grep "Organizations Handler Tests"
+npm --prefix test test -- --grep "Matrix -"
+```
+
+## Setup Flow
+
+`test/support/setup.js` runs before all suites and executes `test/support/enableServerFeatures.js` to provision:
+
+- realm
+- client
+- user
+- roles
+- group
+- client scope
+- fine-grained permissions (when feature-enabled)
+
+## Writing New Tests
+
+- Import config from `test/testConfig.js`.
+- Use unique names for resources (`generateUniqueName` or timestamp).
+- Clean up created resources in `after` hooks.
+- Avoid destructive realm-wide mutations unless test is explicitly scoped for it.

package/index.js

@@ -1,262 +1,178 @@
-var express = require('express');
-var keycloakAdminClient=require('@keycloak/keycloak-admin-client').default;
-var kcAdminClient=null;
-var realmHandler=require('./Handlers/realmsHandler');
-var usersHandler=require('./Handlers/usersHandler');
-var clientsHandler=require('./Handlers/clientsHandler');
-var clientScopesHandler=require('./Handlers/clientScopesHandler');
-var identityProvidersHandler=require('./Handlers/identityProvidersHandler');
-var groupsHandler=require('./Handlers/groupsHandler');
-var rolesHandler=require('./Handlers/rolesHandler');
-var componentsHandler=require('./Handlers/componentsHandler');
-var authenticationManagementHandler=require('./Handlers/authenticationManagementHandler');
-var request=require('request');
+const KeycloakAdminClient = require('@keycloak/keycloak-admin-client').default;
+
+const handlerRegistry = {
+    realms: require('./Handlers/realmsHandler'),
+    users: require('./Handlers/usersHandler'),
+    clients: require('./Handlers/clientsHandler'),
+    clientScopes: require('./Handlers/clientScopesHandler'),
+    identityProviders: require('./Handlers/identityProvidersHandler'),
+    groups: require('./Handlers/groupsHandler'),
+    roles: require('./Handlers/rolesHandler'),
+    components: require('./Handlers/componentsHandler'),
+    authenticationManagement: require('./Handlers/authenticationManagementHandler'),
+    attackDetection: require('./Handlers/attackDetectionHandler'),
+    organizations: require('./Handlers/organizationsHandler'),
+    userProfile: require('./Handlers/userProfileHandler'),
+    clientPolicies: require('./Handlers/clientPoliciesHandler'),
+    serverInfo: require('./Handlers/serverInfoHandler')
+};
 
-let configAdminclient=null;
-let tokenRefreshInterval=null;
+let kcAdminClient = null;
+let tokenRefreshInterval = null;
+let runtimeConfig = null;
+let authPayload = null;
 
-/**
- * Configure and initialize the Keycloak Admin Client for managing Keycloak resources.
- * 
- * This function MUST be called before using any administrative functions exposed by this library.
- * It sets up the admin client with proper credentials and establishes automatic token refresh.
- * 
- * @param {Object} adminClientCredentials - Configuration object for Keycloak Admin Client
- * @param {string} adminClientCredentials.baseUrl - Keycloak server base URL (e.g., "http://localhost:8080")
- * @param {string} adminClientCredentials.realmName - Realm to authenticate against (use "master" for admin operations)
- * @param {string} adminClientCredentials.clientId - Client ID configured in Keycloak (e.g., "admin-cli")
- * @param {string} adminClientCredentials.grantType - OAuth2 grant type ("password", "client_credentials", etc.)
- * @param {number} adminClientCredentials.tokenLifeSpan - Access token lifetime in seconds (recommended: 60-120)
- * @param {string} [adminClientCredentials.username] - Admin username (required for "password" grant type)
- * @param {string} [adminClientCredentials.password] - Admin password (required for "password" grant type)
- * @param {string} [adminClientCredentials.clientSecret] - Client secret (required for "client_credentials" or confidential clients)
- * @param {string} [adminClientCredentials.scope] - OAuth2 scope (optional, e.g., "openid profile")
- * @param {Object} [adminClientCredentials.requestOptions] - Custom HTTP options (headers, timeout, etc.) compatible with Fetch API
- * @param {string} [adminClientCredentials.totp] - Time-based One-Time Password for MFA (if enabled)
- * @param {boolean} [adminClientCredentials.offlineToken=false] - Request offline token for long-lived refresh tokens
- * @param {string} [adminClientCredentials.refreshToken] - Existing refresh token (for "refresh_token" grant type)
- * 
- * @returns {Promise<void>} Resolves when configuration is complete and authentication successful
- * 
- * @throws {Error} If authentication fails or required parameters are missing
- * 
- * @example
- * // Basic configuration with password grant
- * await KeycloakManager.configure({
- *   baseUrl: 'http://localhost:8080',
- *   realmName: 'master',
- *   clientId: 'admin-cli',
- *   username: 'admin',
- *   password: 'admin',
- *   grantType: 'password',
- *   tokenLifeSpan: 120
- * });
- * 
- * @example
- * // Configuration with client credentials
- * await KeycloakManager.configure({
- *   baseUrl: 'https://auth.example.com',
- *   realmName: 'master',
- *   clientId: 'service-account',
- *   clientSecret: 'secret-key',
- *   grantType: 'client_credentials',
- *   tokenLifeSpan: 60
- * });
- * 
- * @note After successful configuration, all admin handlers are exposed:
- * - KeycloakManager.realms - Realm management
- * - KeycloakManager.users - User management
- * - KeycloakManager.clients - Client management
- * - KeycloakManager.clientScopes - Client scope management
- * - KeycloakManager.identityProviders - Identity provider management
- * - KeycloakManager.groups - Group management
- * - KeycloakManager.roles - Role management
- * - KeycloakManager.components - Component management
- * - KeycloakManager.authenticationManagement - Authentication flow management
- * 
- * @note Token Refresh: The client automatically refreshes the access token at intervals
- * calculated as (tokenLifeSpan * 1000) / 2 milliseconds. Call KeycloakManager.stop()
- * to clear the refresh interval and allow graceful process termination.
- */
-exports.configure=async function(adminClientCredentials){
-        configAdminclient={
-                baseUrl:adminClientCredentials.baseUrl,
-                realmName:adminClientCredentials.realmName
-        }
+function assertConfigured() {
+    if (!kcAdminClient || !runtimeConfig) {
+        throw new Error('Keycloak Admin Client is not configured. Call configure() first.');
+    }
+}
 
-        kcAdminClient=  new keycloakAdminClient(configAdminclient);
-        configAdminclient.clientId=adminClientCredentials.clientId;
-        configAdminclient.clientSecret=adminClientCredentials.clientSecret;
+function toBaseUrl(baseUrl) {
+    if (!baseUrl || typeof baseUrl !== 'string') {
+        throw new Error('Invalid baseUrl. It must be a non-empty string.');
+    }
+    return baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+}
 
+function bindHandlers() {
+    Object.entries(handlerRegistry).forEach(([name, handler]) => {
+        handler.setKcAdminClient(kcAdminClient);
+        exports[name] = handler;
+    });
+}
 
-        let tokenLifeSpan= Number(adminClientCredentials.tokenLifeSpan);
-        tokenLifeSpan = Number.isFinite(tokenLifeSpan) && tokenLifeSpan > 0
-                ? (tokenLifeSpan * 1000) / 2
-                : 30000;
-        delete adminClientCredentials.baseUrl;
-        delete adminClientCredentials.realmName;
-        delete adminClientCredentials.tokenLifeSpan;
-        await kcAdminClient.auth(adminClientCredentials);
+function clearRefreshTimer() {
+    if (tokenRefreshInterval) {
+        clearInterval(tokenRefreshInterval);
+        tokenRefreshInterval = null;
+    }
+}
 
-        if (tokenRefreshInterval) {
-                clearInterval(tokenRefreshInterval);
-        }
+function startRefreshTimer(intervalMs) {
+    clearRefreshTimer();
 
-        tokenRefreshInterval = setInterval(async ()=>{
-                await kcAdminClient.auth(adminClientCredentials);
-        },tokenLifeSpan);
-        if (tokenRefreshInterval.unref) {
-                tokenRefreshInterval.unref();
+    tokenRefreshInterval = setInterval(async () => {
+        try {
+            await kcAdminClient.auth({ ...authPayload });
+        } catch (err) {
+            console.error('Token refresh failed:', err.message);
         }
+    }, intervalMs);
 
-        realmHandler.setKcAdminClient(kcAdminClient);
-        exports.realms=realmHandler;
-
-        usersHandler.setKcAdminClient(kcAdminClient);
-        exports.users=usersHandler;
-
-        clientsHandler.setKcAdminClient(kcAdminClient);
-        exports.clients=clientsHandler;
-
-        clientScopesHandler.setKcAdminClient(kcAdminClient);
-        exports.clientScopes=clientScopesHandler;
-
-        identityProvidersHandler.setKcAdminClient(kcAdminClient);
-        exports.identityProviders=identityProvidersHandler;
-
-        groupsHandler.setKcAdminClient(kcAdminClient);
-        exports.groups=groupsHandler;
-
-        rolesHandler.setKcAdminClient(kcAdminClient);
-        exports.roles=rolesHandler;
+    if (tokenRefreshInterval.unref) {
+        tokenRefreshInterval.unref();
+    }
+}
 
-        componentsHandler.setKcAdminClient(kcAdminClient);
-        exports.components=componentsHandler;
+exports.configure = async function configure(adminClientCredentials = {}) {
+    const {
+        baseUrl,
+        realmName,
+        clientId,
+        clientSecret,
+        tokenLifeSpan,
+        ...credentials
+    } = adminClientCredentials;
+
+    const normalizedBaseUrl = toBaseUrl(baseUrl);
+
+    runtimeConfig = {
+        baseUrl: normalizedBaseUrl,
+        realmName,
+        clientId,
+        clientSecret
+    };
+
+    kcAdminClient = new KeycloakAdminClient({
+        baseUrl: normalizedBaseUrl,
+        realmName
+    });
+
+    const originalSetRefreshToken = kcAdminClient.setRefreshToken?.bind(kcAdminClient);
+    if (originalSetRefreshToken) {
+        kcAdminClient.setRefreshToken = (token) => {
+            if (!token) {
+                kcAdminClient.refreshToken = undefined;
+                return;
+            }
+            return originalSetRefreshToken(token);
+        };
+    }
+
+    authPayload = {
+        clientId,
+        ...(clientSecret ? { clientSecret } : {}),
+        ...credentials
+    };
+    await kcAdminClient.auth(authPayload);
+
+    const intervalMs = Number.isFinite(Number(tokenLifeSpan)) && Number(tokenLifeSpan) > 0
+        ? (Number(tokenLifeSpan) * 1000) / 2
+        : 30000;
+
+    startRefreshTimer(intervalMs);
+    bindHandlers();
+};
 
-        authenticationManagementHandler.setKcAdminClient(kcAdminClient);
-        exports.authenticationManagement=authenticationManagementHandler;
+exports.setConfig = function setConfig(configToOverride = {}) {
+    assertConfigured();
+    kcAdminClient.setConfig(configToOverride);
 
+    runtimeConfig = {
+        ...runtimeConfig,
+        ...(configToOverride.baseUrl ? { baseUrl: toBaseUrl(configToOverride.baseUrl) } : {}),
+        ...(configToOverride.realmName ? { realmName: configToOverride.realmName } : {})
+    };
+};
 
-        //exports = kcAdminClient;
+exports.getToken = function getToken() {
+    assertConfigured();
+    return {
+        accessToken: kcAdminClient.accessToken,
+        refreshToken: kcAdminClient.refreshToken
+    };
 };
 
-/**
- * Updates the runtime configuration of the Keycloak Admin Client instance.
- * Allows switching the target realm, base URL, or HTTP request options without 
- * reinitializing the client or re-authenticating.
- * 
- * @param {Object} configToOverride - Configuration object to update
- * @param {string} [configToOverride.realmName] - The name of the target realm for subsequent API requests
- * @param {string} [configToOverride.baseUrl] - The base URL of the Keycloak server (e.g., https://auth.example.com)
- * @param {Object} [configToOverride.requestOptions] - Custom HTTP options (headers, timeout, etc.) applied to API calls
- * @param {string} [configToOverride.realmPath] - A custom realm path if your Keycloak instance uses a non-standard realm route
- * @returns {void}
- * 
- * @note 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.
- */
-exports.setConfig=function(configToOverride){
-        return(kcAdminClient.setConfig(configToOverride));
-}
+exports.stop = function stop() {
+    clearRefreshTimer();
+};
 
-/**
- * Retrieves the current authentication tokens used by the Keycloak Admin Client.
- * Returns both the access token (used for API authorization) and the refresh token 
- * (used to renew the session when the access token expires).
- * 
- * @returns {Object} Token object containing:
- * @returns {string} accessToken - The active access token string currently held by the Keycloak Admin Client
- * @returns {string} refreshToken - The corresponding refresh token string, if available
- * 
- * @note The tokens are managed internally by the Keycloak Admin Client after successful authentication.
- * The accessToken typically expires after a short period (e.g., 60 seconds by default).
- * If the client is not authenticated or the session has expired, both values may be undefined.
- */
-exports.getToken=function(){
-        return({
-                accessToken:kcAdminClient.accessToken,
-                refreshToken:kcAdminClient.refreshToken,
-        });
-}
+exports.auth = async function auth(credentials = {}) {
+    assertConfigured();
 
-/**
- * Cleanly stops the Keycloak Admin Client by clearing the automatic token refresh interval.
- * When the admin client is configured with tokenLifeSpan, it automatically refreshes 
- * the access token at regular intervals to maintain the session.
- * Calling stop() clears this interval, allowing your Node.js process to exit gracefully.
- * 
- * @returns {void}
- * 
- * @note This method should be called when you're done using the Keycloak Admin Client 
- * and want to terminate your application. It's particularly important in test environments 
- * or CLI scripts where the process needs to exit cleanly. The method is safe to call 
- * multiple times; subsequent calls have no effect.
- * 
- * @example
- * // Configure and use the admin client
- * await KeycloakManager.configure({ ... });
- * const users = await KeycloakManager.users.find();
- * // Clean up and allow process to exit
- * KeycloakManager.stop();
- */
-exports.stop=function(){
-        if (tokenRefreshInterval) {
-                clearInterval(tokenRefreshInterval);
-                tokenRefreshInterval=null;
+    const body = new URLSearchParams();
+    Object.entries(credentials).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+            body.append(key, String(value));
         }
-}
-
-/**
- * Allows a user or client to authenticate against a Keycloak realm and obtain an access token.
- * Sends a direct HTTP POST request to the Keycloak OpenID Connect token endpoint using the provided credentials.
- * 
- * @param {Object} credentials - Authentication details
- * @param {string} [credentials.username] - Username of the user (required for password grant)
- * @param {string} [credentials.password] - Password of the user (required for password grant)
- * @param {string} credentials.grant_type - The OAuth2 grant type (e.g. "password", "client_credentials", "refresh_token")
- * @returns {Promise<Object>} Token response object from Keycloak
- * 
- * @example
- * const tokenResponse = await KeycloakManager.auth({
- *   username: "demo",
- *   password: "demo123",
- *   grant_type: "password",
- * });
- * console.log("Access Token:", tokenResponse.access_token);
- */
-exports.auth=async function(credentials){
-        credentials.client_id=configAdminclient.clientId;
-        credentials.client_secret=configAdminclient.clientSecret;
-        let options={
-                url: `${configAdminclient.baseUrl}realms/${configAdminclient.realmName}/protocol/openid-connect/token` ,
-                headers: {'content-type': 'application/www-form-urlencoded', 'Authorization': "Bearer " + kcAdminClient.accessToken },
-                form: credentials
+    });
+
+    if (runtimeConfig.clientId) {
+        body.append('client_id', runtimeConfig.clientId);
+    }
+    if (runtimeConfig.clientSecret) {
+        body.append('client_secret', runtimeConfig.clientSecret);
+    }
+
+    const response = await fetch(
+        `${runtimeConfig.baseUrl}/realms/${runtimeConfig.realmName}/protocol/openid-connect/token`,
+        {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/x-www-form-urlencoded'
+            },
+            body
         }
-        return new Promise((resolve, reject) => {
-                request.post(options, function (error, response, body) {
-                        if (error) {
-                                console.error("Internal Server Error:", error); // internal error
-                                reject(error);
-                        } else {
-                                resolve(JSON.parse(body)); // ✅ return auth token or error due to invalid credentials
-                        }
-                });
-        });
-};
-
-
-
-
-
-
-/*
- <table><tbody>
- <tr><th align="left">Alessandro Romanino</th><td><a href="https://github.com/aromanino">GitHub/aromanino</a></td><td><a href="mailto:a.romanino@gmail.com">mailto:a.romanino@gmail.com</a></td></tr>
- <tr><th align="left">Guido Porruvecchio</th><td><a href="https://github.com/gporruvecchio">GitHub/porruvecchio</a></td><td><a href="mailto:guido.porruvecchio@gmail.com">mailto:guido.porruvecchio@gmail.com</a></td></tr>
- </tbody></table>
- * */
-
+    );
 
+    const responseText = await response.text();
+    const payload = responseText ? JSON.parse(responseText) : {};
 
+    if (!response.ok) {
+        const errorMessage = payload.error_description || payload.error || 'Authentication failed';
+        throw new Error(errorMessage);
+    }
 
+    return payload;
+};