keycloak-api-manager 3.2.1 → 4.0.0

package/index.js

@@ -13,29 +13,70 @@ var authenticationManagementHandler=require('./Handlers/authenticationManagement
 var request=require('request');
 
 let configAdminclient=null;
+let tokenRefreshInterval=null;
 
 /**
- * ***************************** - ENGLISH - *******************************
- *
- *     Main supported options:
- *     -baseUrl: Keycloak base Url
- *     - realmName: [Optional] 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'.
- *     - scope: [Optional] A string that specifies The OAuth2 scope requested during authentication (optional).
- *              Typically not required for administrative clients. example:openid profile
- *    - requestOptions: [Optional] JSON parameters to configure HTTP requests (such as custom headers, timeouts, etc.).
- *      It is compatible with the Fetch API standard. Fetch request options
- *      https://developer.mozilla.org/en-US/docs/Web/API/fetch#options
- *    - username: [Optional] string username. Required when using the password grant type.
- *    - password: [Optional] string password. Required when using the password grant type.
- *    - grantType: The OAuth2 grant type used for authentication.
- *      Possible values: 'password', 'client_credentials', 'refresh_token', etc.
- *    - tokenLifeSpan: Lifetime of an access token expressed in seconds.
- *    - clientId: string containing the client ID configured in Keycloak. Required for all grant types.
- *    - clientSecret: [Optional] string containing the client secret of the client. Required for client_credentials or confidential clients.
- *    - totp: string for Time-based One-Time Password (TOTP) for multi-factor authentication (MFA), if enabled for the user.
- *    - offlineToken: [Optional] boolean value. If true, requests an offline token (used for long-lived refresh tokens). Default is false.
- *    - refreshToken: [Optional] string containing a valid refresh token to request a new access token when using the refresh_token grant type.
+ * 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={
@@ -48,15 +89,25 @@ exports.configure=async function(adminClientCredentials){
         configAdminclient.clientSecret=adminClientCredentials.clientSecret;
 
 
-        let  tokenLifeSpan= (adminClientCredentials.tokenLifeSpan *1000)/2;
+        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);
 
-        setInterval(async ()=>{
+        if (tokenRefreshInterval) {
+                clearInterval(tokenRefreshInterval);
+        }
+
+        tokenRefreshInterval = setInterval(async ()=>{
                 await kcAdminClient.auth(adminClientCredentials);
         },tokenLifeSpan);
+        if (tokenRefreshInterval.unref) {
+                tokenRefreshInterval.unref();
+        }
 
         realmHandler.setKcAdminClient(kcAdminClient);
         exports.realms=realmHandler;
@@ -89,13 +140,39 @@ exports.configure=async function(adminClientCredentials){
         //exports = kcAdminClient;
 };
 
-
-//TODO: Remove da documentare
+/**
+ * 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));
 }
-//TODO: Remove da documentare
-// restituisce il token utilizzato dalla libreria per comunicare con la keycloak API
+
+/**
+ * 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,
@@ -103,8 +180,51 @@ exports.getToken=function(){
         });
 }
 
-//TODO: Remove da documentare
-//permette ad un utente o un client di autenticarsi su keycloack ed oottenere un token
+/**
+ * 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;
+        }
+}
+
+/**
+ * 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;

package/package.json

@@ -1,17 +1,11 @@
 {
   "name": "keycloak-api-manager",
-  "version": "3.2.1",
+  "version": "4.0.0",
   "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:watch": "mocha --watch --watch-extensions js"
+    "test": "npm --prefix test install && npm --prefix test test",
+    "setup-keycloak": "node test/docker-keycloak/setup-keycloak.js"
   },
   "dependencies": {
     "@keycloak/keycloak-admin-client": "^26.3.2",
@@ -30,11 +24,6 @@
     "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",

package/test/.mocharc.json

@@ -0,0 +1,4 @@
+{
+  "file": ["setup.js"],
+  "spec": ["specs/*.test.js"]
+}

package/test/TESTING.md

@@ -0,0 +1,327 @@
+# Keycloak API Manager - Test Suite
+
+Comprehensive test suite for `keycloak-api-manager` library.
+
+## Overview
+
+This test workspace validates all administrative functions provided by the library against a real Keycloak instance. Tests cover:
+
+- **Authentication Management** - Required actions, authentication flows, executions
+- **Clients** - CRUD operations, roles, secrets, scopes, sessions, authorization services
+- **Client Scopes** - Management, protocol mappers, scope mappings
+- **Components** - Provider listing, CRUD operations, sub-components
+- **Groups** - CRUD, members, role mappings, admin permissions
+- **Identity Providers** - Factory listing, CRUD, mappers
+- **Realms** - Full lifecycle, configuration, events, keys, localization
+- **Roles** - CRUD, composite roles, user assignments
+- **Users** - CRUD, credentials, groups, role mappings, sessions, impersonation
+
+## Architecture
+
+### Shared Test Realm Strategy
+
+Unlike traditional test approaches where each suite creates/destroys its own realm, this implementation uses a **shared test realm** created once before all tests:
+
+**Benefits**:
+- ⚡ **5-10x faster** - Eliminates repeated realm creation overhead (~2-5s per test)
+- 🔄 **Consistent environment** - All tests run against identical infrastructure
+- 🛡️ **Idempotent setup** - Running tests multiple times doesn't recreate existing resources
+- 🎯 **Isolated resources** - Tests create unique resources (e.g., `user-${timestamp}`) to avoid conflicts
+
+**Trade-offs**:
+- Requires cleanup of test-specific resources (most tests handle this)
+- Shared realm means tests can't modify realm-level settings without affecting others
+
+### File Structure
+
+```
+test/
+├── config/                    # Configuration files (propertiesmanager)
+│   ├── default.json          # Base configuration (committed)
+│   ├── secrets.json          # Passwords (gitignored, required)
+│   ├── local.json            # Developer overrides (gitignored, optional)
+│   ├── local.json.example    # Template for local.json
+│   └── CONFIGURATION.md      # Configuration documentation
+├── specs/                     # Test suites
+│   ├── authenticationManagement.test.js
+│   ├── clients.test.js
+│   ├── clientScopes.test.js
+│   ├── components.test.js
+│   ├── groups.test.js
+│   ├── identityProviders.test.js
+│   ├── realms.test.js
+│   ├── roles.test.js
+│   └── users.test.js
+├── .mocharc.json             # Mocha configuration
+├── enableServerFeatures.js   # Creates shared test infrastructure
+├── package.json              # Test dependencies
+├── setup.js                  # Global Mocha hooks
+└── testConfig.js             # Configuration loader and exports
+```
+
+### Key Components
+
+#### `testConfig.js`
+Centralized configuration module that:
+- Sets up propertiesmanager environment
+- Loads and merges config files (default → secrets → local)
+- Exports standardized constants for tests:
+  - `KEYCLOAK_CONFIG` - Admin connection settings
+  - `TEST_REALM` - Shared realm name
+  - `TEST_CLIENT_*` - Client configuration
+  - `TEST_USER_*` - User details and credentials
+  - `TEST_ROLES` - Array of test roles
+  - `TEST_GROUP_NAME` - Test group name
+  - `TEST_CLIENT_SCOPE` - Client scope name
+  - `generateUniqueName()` - Helper for unique resource names
+
+#### `setup.js`
+Global Mocha hooks loaded via `.mocharc.json`:
+- Runs `enableServerFeatures()` once in `before()` hook
+- Sets 30s timeout for realm creation
+- Logs setup progress to console
+
+#### `enableServerFeatures.js`
+Infrastructure setup script that creates (if not exists):
+1. **Test Realm** - Isolated environment for all tests
+2. **Test Client** - Service account client for auth tests
+3. **Test User** - Standard user with credentials
+4. **Test Roles** - Multiple roles for RBAC testing  
+5. **Test Group** - Group for membership tests
+6. **Fine-grained Permissions** - Admin permissions (if server supports)
+7. **Client Scope** - For scope mapping tests
+
+Runs idempotently - safe to execute multiple times.
+
+#### `.mocharc.json`
+Mocha configuration:
+```json
+{
+  "file": ["setup.js"],        // Load global hooks before tests
+  "spec": ["specs/*.test.js"]  // Run all test suites
+}
+```
+
+## Running Tests
+
+### Prerequisites
+
+1. **Keycloak Instance**: Running and accessible
+2. **Configuration**: Create `test/config/secrets.json` with admin password
+3. **SSH Tunnel** (if remote): Ensure tunnel is active before running tests
+
+### Commands
+
+```bash
+# Install dependencies and run all tests
+npm test
+
+# Or step-by-step:
+npm --prefix test install        # Install test dependencies
+npm --prefix test test           # Run all tests
+
+# Run specific test suite
+npm --prefix test test -- --grep "Users Handler"
+
+# Run specific test
+npm --prefix test test -- --grep "should create, find, update, and delete clients"
+```
+
+## Diagnostics
+
+### Protocol Mapper Diagnostic Script
+
+The file [test/diagnostic-protocol-mappers.js](test/diagnostic-protocol-mappers.js) is a manual troubleshooting script.
+It is not part of the automated Mocha test suite. It is used to validate protocol mapper creation via:
+
+- Direct Admin REST API calls
+- The library client (`keycloak-api-manager`)
+
+Run it manually when you need to debug protocol mapper behavior:
+
+```bash
+node test/diagnostic-protocol-mappers.js
+```
+
+It uses the same `test/config` configuration and the shared test realm.
+
+### Expected Output
+
+```
+propertiesmanager Configuration loaded successfully for environment: test
+
+=== Running global test setup ===
+
+Configuring Keycloak Admin Client...
+
+1. Setting up test realm: keycloak-api-manager-test-realm
+   ✓ Test realm already exists: keycloak-api-manager-test-realm
+
+2. Setting up test client...
+   ✓ Test client updated: test-client
+
+[... additional setup output ...]
+
+✓ Keycloak server configuration complete!
+
+=== Global setup complete ===
+
+  Users Handler
+    ✔ should find, findOne, count and update users
+    ✔ should manage password and credentials
+    [... more tests ...]
+
+  59 passing (9s)
+  7 pending
+```
+
+## Configuration
+
+Configuration uses [propertiesmanager](https://www.npmjs.com/package/propertiesmanager) for hierarchical config management.
+
+**Quick Setup**:
+
+1. Copy secrets template:
+   ```bash
+   cp test/config/local.json.example test/config/secrets.json
+   ```
+
+2. Edit `test/config/secrets.json`:
+   ```json
+   {
+     "test": {
+       "keycloak": {
+         "password": "your-admin-password"
+       },
+       "realm": {
+         "user": {
+           "password": "test-user-password"
+         }
+       }
+     }
+   }
+   ```
+
+3. (Optional) Override baseUrl in `test/config/local.json`:
+   ```json
+   {
+     "test": {
+       "keycloak": {
+         "baseUrl": "http://localhost:8080"
+       }
+     }
+   }
+   ```
+
+See [config/CONFIGURATION.md](config/CONFIGURATION.md) for detailed configuration documentation.
+
+## Test Writing Guidelines
+
+### Use Shared Configuration
+
+```javascript
+const {
+    TEST_REALM,
+    TEST_CLIENT_ID,
+    TEST_USER_USERNAME,
+    generateUniqueName
+} = require('../testConfig');
+```
+
+### Create Unique Resources
+
+Avoid conflicts by using timestamps or UUIDs:
+
+```javascript
+const userName = generateUniqueName('test-user');
+const roleName = `role-${Date.now()}`;
+```
+
+### Respect Shared Realm
+
+Don't:
+- Modify realm-level settings (will affect other tests)
+- Delete the shared realm
+- Assume exclusive access to shared resources (client, user, roles)
+
+Do:
+- Create test-specific resources with unique names
+- Clean up resources created during test (in `after()` hooks)
+- Use the shared infrastructure for read operations
+
+### Handle Feature Availability
+
+Some Keycloak features may not be available on all server versions:
+
+```javascript
+try {
+    await keycloakManager.users.listConsents({ realm: TEST_REALM, id: userId });
+} catch (err) {
+    if (err.response?.status === 404) {
+        this.skip(); // Skip test if feature not available
+    }
+    throw err;
+}
+```
+
+## Troubleshooting
+
+### Tests hang indefinitely
+- Check Keycloak instance is running and accessible
+- Verify SSH tunnel is active (if using remote Keycloak)
+- Check `baseUrl` in configuration matches your setup
+
+### "Configuration loading failed"
+- Ensure `test/config/secrets.json` exists
+- Verify JSON syntax (no trailing commas)
+- Check environment wrapper present: `{ "test": { ... } }`
+
+### "Access denied" or 403 errors
+- Verify admin credentials in `secrets.json`
+- Ensure admin user has realm-management permissions
+- Check `realmName` is correct (usually "master" for admin user)
+
+### "Realm not found" errors
+- Check global setup ran successfully (see console output)
+- Verify shared realm created: look for "✓ Test realm created/exists"
+- Ensure realm name matches configuration
+
+### Slow test execution
+- First run is slower (~10-20s) due to realm setup
+- Subsequent runs should be faster (~5-10s)  
+- If still slow, check network latency to Keycloak instance
+- Consider using local Keycloak instance instead of remote tunnel
+
+### Tests fail inconsistently
+- May indicate race conditions or shared resource conflicts
+- Ensure test resources use unique names
+- Check cleanup logic in `after()` hooks
+- Run single test in isolation to verify: `--grep "test name"`
+
+## Performance Metrics
+
+Typical performance on 2020 MacBook Pro with local Keycloak:
+
+- **Global Setup**: ~10-15 seconds (runs once)
+- **Full Suite**: ~9 seconds (59 tests)
+- **Individual Test**: ~50-200ms average
+
+Performance with remote Keycloak over SSH tunnel:
+- **Global Setup**: ~15-25 seconds
+- **Full Suite**: ~15-30 seconds
+
+## Contributing
+
+When adding new tests:
+
+1. Follow existing patterns in `specs/` directory
+2. Import shared config from `testConfig.js`
+3. Use `generateUniqueName()` for test resources
+4. Add cleanup in `after()` hooks
+5. Handle optional features gracefully (use `this.skip()`)
+6. Document any new configuration requirements
+7. Update this README if adding new test categories
+
+## License
+
+Same as parent project.