keycloak-api-manager 4.0.0 → 5.0.0

package/test/TESTING.md

@@ -1,327 +0,0 @@
-# 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.

package/test/config/CONFIGURATION.md

@@ -1,170 +0,0 @@
-# Test Configuration
-
-This directory contains hierarchical configuration files managed by [propertiesmanager](https://www.npmjs.com/package/propertiesmanager).
-
-## Configuration Files
-
-### `default.json` (required, committed to git)
-Base configuration with non-sensitive defaults. Contains the "test" environment section with:
-
-- **keycloak**: Admin connection settings (baseUrl, realmName, clientId, username, grantType)
-- **realm**: Test realm infrastructure specifications (realm name, client, user, roles, groups, scopes)
-
-**When to edit**: Update non-sensitive defaults that all developers should use.
-
-### `secrets.json` (required, gitignored)
-Sensitive credentials overlaid on default.json. Contains passwords and secrets.
-
-**Structure**:
-```json
-{
-  "test": {
-    "keycloak": {
-      "password": "admin"
-    },
-    "realm": {
-      "user": {
-        "password": "test-password"
-      }
-    }
-  }
-}
-```
-
-**When to create**: Before running tests for the first time. Copy structure above and fill in your Keycloak admin password.
-
-### `local.json` (optional, gitignored)
-Developer-specific overrides for local environments. Useful for:
-- Custom baseUrl (localhost instead of tunnel)
-- Different realm names
-- Custom ports
-
-**Example**:
-```json
-{
-  "test": {
-    "keycloak": {
-      "baseUrl": "http://localhost:8080"
-    }
-  }
-}
-```
-
-**When to create**: Only if you need to override defaults for your local environment.
-
-### `local.json.example` (committed to git)
-Template showing example local overrides. Copy to `local.json` and customize.
-
-## Configuration Loading
-
-Files are merged in this order:
-1. **default.json** - Base configuration
-2. **secrets.json** - Overlays sensitive credentials
-3. **local.json** - Overlays developer-specific settings (if exists)
-
-The environment section is determined by `NODE_ENV` (default: "test").
-
-## Important Notes
-
-### Environment Wrapper Required
-All configuration must be wrapped in an environment key:
-
-✅ **Correct**:
-```json
-{
-  "test": {
-    "keycloak": { "baseUrl": "..." }
-  }
-}
-```
-
-❌ **Incorrect**:
-```json
-{
-  "keycloak": { "baseUrl": "..." }
-}
-```
-
-### Git Ignored Files
-These files are excluded from git (see `.gitignore`):
-- `secrets.json` - Contains passwords
-- `local.json` - Developer-specific customizations
-
-### Security
-- Never commit `secrets.json` or `local.json`
-- Keep passwords out of `default.json`
-- Use secure passwords in production-like environments
-
-## Configuration Schema
-
-### keycloak (admin connection)
-```json
-{
-  "baseUrl": "http://127.0.0.1:9998",     // Keycloak server URL
-  "realmName": "master",                   // Admin realm (usually "master")
-  "clientId": "admin-cli",                 // Admin client ID
-  "username": "admin",                     // Admin username
-  "password": "admin",                     // Admin password (in secrets.json)
-  "grantType": "password",                 // OAuth2 grant type
-  "tokenLifeSpan": 60                      // Token refresh interval (seconds)
-}
-```
-
-## Diagnostic Script Configuration
-
-The manual diagnostic script [test/diagnostic-protocol-mappers.js](../diagnostic-protocol-mappers.js)
-uses the same `test` configuration (including `baseUrl`, credentials, and realm settings).
-It is not part of the automated test suite and must be run manually.
-
-Run it with:
-```bash
-node test/diagnostic-protocol-mappers.js
-```
-
-Make sure `baseUrl` points to a reachable Keycloak instance and `secrets.json` contains valid credentials.
-
-### realm (test infrastructure)
-```json
-{
-  "name": "keycloak-api-manager-test-realm",  // Test realm name
-  "client": {
-    "clientId": "test-client",                 // Test client ID
-    "clientSecret": "test-client-secret"       // Test client secret
-  },
-  "user": {
-    "username": "test-user",                   // Test user username
-    "password": "test-password",               // Test user password (in secrets.json)
-    "email": "test-user@test.local",           // Test user email
-    "firstName": "Test",                       // Test user first name
-    "lastName": "User"                         // Test user last name
-  },
-  "roles": ["test-role-1", "test-role-2", "test-admin-role"],  // Roles to create
-  "group": {
-    "name": "test-group"                       // Test group name
-  },
-  "clientScope": {
-    "name": "test-scope"                       // Test client scope name
-  }
-}
-```
-
-## Troubleshooting
-
-### "Configuration loading failed"
-- Ensure `secrets.json` exists with valid JSON
-- Check that environment wrapper "test" is present in all files
-- Verify JSON syntax (no trailing commas, proper quotes)
-
-### "Access denied" errors during tests  
-- Check admin username/password in `secrets.json`
-- Verify `baseUrl` points to accessible Keycloak instance
-- If using SSH tunnel, ensure it's active
-
-### "Realm not found" errors
-- Ensure global setup ran successfully (check console output)
-- Verify realm name matches between config and test expectations
-- Check that Keycloak instance is running and accessible
-
-## More Information
-
-See main project [README.md](../../README.md) for overall test architecture and execution instructions.

package/test/diagnostic-protocol-mappers.js

@@ -1,189 +0,0 @@
-const path = require('path');
-const http = require('http');
-const https = require('https');
-
-process.env.NODE_ENV = process.env.NODE_ENV || 'test';
-process.env.PROPERTIES_PATH = path.join(__dirname, 'config');
-
-const { conf } = require('propertiesmanager');
-const keycloakManager = require('keycloak-api-manager');
-const { TEST_REALM } = require('./testConfig');
-
-function requestAdmin(baseUrl, token, apiPath, method = 'GET', body) {
-  const url = new URL(apiPath, baseUrl);
-  const transport = url.protocol === 'https:' ? https : http;
-  const payload = body ? JSON.stringify(body) : null;
-
-  const options = {
-    method,
-    headers: {
-      Accept: 'application/json',
-      Authorization: `Bearer ${token}`,
-      ...(payload ? { 'Content-Type': 'application/json' } : {}),
-    },
-  };
-
-  return new Promise((resolve, reject) => {
-    const req = transport.request(url, options, (res) => {
-      let data = '';
-      res.on('data', (chunk) => {
-        data += chunk;
-      });
-      res.on('end', () => {
-        if (res.statusCode >= 200 && res.statusCode < 300) {
-          try {
-            const result = {
-              data: data ? JSON.parse(data) : null,
-              statusCode: res.statusCode,
-              headers: res.headers,
-            };
-            resolve(result);
-          } catch {
-            resolve({
-              data: data || null,
-              statusCode: res.statusCode,
-              headers: res.headers,
-            });
-          }
-        } else {
-          const error = new Error(`HTTP ${res.statusCode}: ${data}`);
-          error.statusCode = res.statusCode;
-          error.response = data;
-          reject(error);
-        }
-      });
-    });
-
-    req.on('error', reject);
-    if (payload) {
-      req.write(payload);
-    }
-    req.end();
-  });
-}
-
-async function main() {
-  try {
-    // Configura keycloak manager
-    const keycloakConfig = (conf && conf.keycloak) || {};
-    console.log('keycloakConfig baseUrl:', keycloakConfig.baseUrl);
-    
-    if (!keycloakConfig.baseUrl) {
-      throw new Error('baseUrl not configured in keycloak config');
-    }
-    
-    await keycloakManager.configure(keycloakConfig);
-    
-    keycloakManager.setConfig({ realmName: TEST_REALM });
-    const token = keycloakManager.getToken();
-    const baseUrl = keycloakConfig.baseUrl.endsWith('/') ? keycloakConfig.baseUrl : `${keycloakConfig.baseUrl}/`;
-
-    console.log('\n=== PROTOCOL MAPPER DIRECT API TEST ===');
-    console.log('Base URL:', baseUrl);
-    console.log();
-
-    // 1. Trova il test client
-    const clients = await keycloakManager.clients.find({ clientId: 'test-client' });
-    if (!clients || !clients.length) {
-      console.log('❌ Test client not found');
-      process.exit(1);
-    }
-    const testClient = clients[0];
-    console.log(`✅ Found test client: ${testClient.clientId} (ID: ${testClient.id})\n`);
-
-    // 2. Prova a creare un protocol mapper con API diretta
-    const apiPath = `/admin/realms/${TEST_REALM}/clients/${testClient.id}/protocol-mappers/models`;
-    
-    const protocolMapper = {
-      name: `direct-api-test-${Date.now()}`,
-      protocol: 'openid-connect',
-      protocolMapper: 'oidc-usermodel-attribute-mapper',
-      consentRequired: false,
-      config: {
-        'user.attribute': 'email',
-        'claim.name': 'email_test',
-        'jsonType.label': 'String',
-        'id.token.claim': 'true',
-        'access.token.claim': 'true',
-      },
-    };
-
-    console.log(`📡 Direct API POST: ${apiPath}`);
-    console.log(`Payload: ${JSON.stringify(protocolMapper, null, 2)}\n`);
-
-    const result = await requestAdmin(
-      baseUrl,
-      token.accessToken,
-      apiPath,
-      'POST',
-      protocolMapper
-    );
-
-    console.log(`✅ SUCCESS - Status: ${result.statusCode}`);
-    console.log(`Location: ${result.headers.location || 'N/A'}\n`);
-
-    // 3. Verifica che sia stato creato
-    const listResult = await requestAdmin(
-      baseUrl,
-      token.accessToken,
-      apiPath,
-      'GET'
-    );
-
-    const createdMapper = listResult.data?.find(m => m.name === protocolMapper.name);
-    if (createdMapper) {
-      console.log(`✅ Mapper verified in list:`);
-      console.log(`   ID: ${createdMapper.id}`);
-      console.log(`   Name: ${createdMapper.name}`);
-      console.log(`   Protocol Mapper: ${createdMapper.protocolMapper}\n`);
-
-      // Cleanup
-      await requestAdmin(
-        baseUrl,
-        token.accessToken,
-        `${apiPath}/${createdMapper.id}`,
-        'DELETE'
-      );
-      console.log('🧹 Cleanup: Mapper deleted\n');
-    }
-
-    // 4. Prova con il client manager della libreria
-    console.log('=== TESTING THROUGH KEYCLOAK MANAGER ===\n');
-    
-    try {
-      await keycloakManager.clients.addProtocolMapper(
-        { id: testClient.id },
-        {
-          name: `library-test-${Date.now()}`,
-          protocol: 'openid-connect',
-          protocolMapper: 'oidc-usermodel-attribute-mapper',
-          consentRequired: false,
-          config: {
-            'user.attribute': 'username',
-            'claim.name': 'user_name',
-            'jsonType.label': 'String',
-            'id.token.claim': 'true',
-            'access.token.claim': 'true',
-          },
-        }
-      );
-      console.log('✅ SUCCESS through keycloak-api-manager');
-    } catch (err) {
-      console.log('❌ FAILED through keycloak-api-manager');
-      console.log(`Error: ${err.message}\n`);
-    }
-
-    console.log('\n=== SUMMARY ===');
-    console.log('Direct API: ✅ Works');
-    console.log('Library: Check output above');
-
-  } catch (err) {
-    console.error('❌ ERROR:', err.message);
-    if (err.response) {
-      console.error('Response:', err.response);
-    }
-    process.exit(1);
-  }
-}
-
-main();