keycloak-api-manager 3.2.1 → 4.0.1

package/test/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "keycloak-api-manager-tests",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "test": "NODE_ENV=test NODE_PATH=./node_modules mocha --exit"
+  },
+  "dependencies": {
+    "@keycloak/keycloak-admin-client": "^26.5.3",
+    "chai": "^4.3.10",
+    "express": "^5.1.0",
+    "keycloak-api-manager": "file:..",
+    "keycloak-connect": "^26.1.1",
+    "mocha": "^10.2.0",
+    "propertiesmanager": "^4.1.0",
+    "request": "^2.88.2"
+  }
+}

package/test/setup.js

@@ -0,0 +1,194 @@
+/**
+ * Global Test Setup - Mocha Hooks
+ * 
+ * This file is loaded by Mocha before any tests run (configured in .mocharc.json).
+ * 
+ * Purpose:
+ * - Creates shared test realm infrastructure once before all tests
+ * - Avoids repeated realm creation/deletion, improving test performance by ~5x
+ * - Ensures consistent test environment across all test suites
+ * - Automatically creates SSH tunnel if direct connection fails
+ * 
+ * What gets created:
+ * - Test realm (keycloak-api-manager-test-realm)
+ * - Test client with proper configuration
+ * - Test user with credentials
+ * - Test roles (test-role-1, test-role-2, test-admin-role)
+ * - Test group
+ * - Test client scope
+ * 
+ * SSH Tunnel Retry Logic:
+ * - First attempts direct connection to 127.0.0.1:9998
+ * - If connection refused, automatically creates SSH tunnel to smart-dell-sml.crs4.it
+ * - If SSH tunnel also fails, provides troubleshooting steps
+ * 
+ * Note: Individual tests should create unique resources (e.g., user-${timestamp})
+ * to avoid conflicts when multiple tests run in parallel or sequence.
+ */
+
+const enableServerFeatures = require('./enableServerFeatures');
+const { exec } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const keycloakManager = require('../index');
+
+let sshTunnelProcess = null;
+
+/**
+ * Create SSH tunnel for Keycloak access
+ */
+function createSSHTunnelSimple() {
+  return new Promise((resolve, reject) => {
+    const sshUser = 'smart';
+    const sshHost = 'smart-dell-sml.crs4.it';
+    const localPort = 9998;
+    const remotePort = 8080;
+    const homeDir = os.homedir();
+    const keyPath = `${homeDir}/.ssh/id_ed25519`;
+    
+    // Create tunnel in background
+    const cmd = `ssh -fN -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -L 127.0.0.1:${localPort}:127.0.0.1:${remotePort} -i ${keyPath} ${sshUser}@${sshHost}`;
+    
+    exec(cmd, (err, stdout, stderr) => {
+      if (err) {
+        reject(new Error(`SSH tunnel failed: ${err.message}`));
+      } else {
+        // Give tunnel time to establish
+        setTimeout(() => resolve(`127.0.0.1:${localPort}`), 500);
+      }
+    });
+  });
+}
+
+// Global before hook - runs once before all test suites
+before(async function() {
+    // Increase timeout - realm creation may take 10-20 seconds
+    this.timeout(120000);
+    
+    console.log('\n=== Running global test setup ===\n');
+    
+    try {
+        await enableServerFeatures();
+    } catch (err) {
+        // Extract the root cause message (might be nested in error chain)
+        let rootMessage = err.message || '';
+        let currentErr = err;
+        while (currentErr?.cause) {
+            currentErr = currentErr.cause;
+            rootMessage = currentErr.message || rootMessage;
+        }
+        
+        // Check if connection was refused on 127.0.0.1:9998
+        if (rootMessage.includes('ECONNREFUSED') && rootMessage.includes('127.0.0.1:9998')) {
+            console.log('\n⚠ Direct connection failed (ECONNREFUSED on 127.0.0.1:9998)');
+            console.log('  Attempting to create SSH tunnel to smart-dell-sml.crs4.it...\n');
+            
+            try {
+                // Create SSH tunnel
+                const sshTunnelUrl = await createSSHTunnelSimple();
+                
+                if (sshTunnelUrl) {
+                    console.log(`✓ SSH tunnel created: http://${sshTunnelUrl}\n`);
+                    
+                    // Update config to use tunnel
+                    const configPath = path.join(__dirname, 'config/local.json');
+                    let config = {};
+                    
+                    if (fs.existsSync(configPath)) {
+                        config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+                    }
+                    
+                    if (!config.test) config.test = {};
+                    if (!config.test.keycloak) config.test.keycloak = {};
+                    config.test.keycloak.baseUrl = `http://${sshTunnelUrl}`;
+                    
+                    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+                    console.log(`✓ Updated test/config/local.json to use SSH tunnel\n`);
+                    
+                    // Clear propertiesmanager cache and retry
+                    delete require.cache[require.resolve('propertiesmanager')];
+                    
+                    // Retry setup
+                    await enableServerFeatures();
+                    sshTunnelProcess = sshTunnelUrl; // Mark that we created a tunnel
+                } else {
+                    throw new Error('SSH tunnel creation returned null');
+                }
+            } catch (tunnelErr) {
+                console.error('\n✗ SSH tunnel connection failed:');
+                console.error(`  Error: ${tunnelErr.message}`);
+                console.error('\nTroubleshooting steps:');
+                console.error('  1. Verify SSH key exists: ls -la ~/.ssh/id_ed25519');
+                console.error('  2. Verify SSH access: ssh -i ~/.ssh/id_ed25519 smart@smart-dell-sml.crs4.it echo OK');
+                console.error('  3. Verify remote Keycloak is running on the server');
+                console.error('  4. Try manual tunnel: ssh -L 127.0.0.1:9998:127.0.0.1:8080 smart@smart-dell-sml.crs4.it');
+                console.error('\nTest execution cancelled.\n');
+                throw new Error(`Failed to connect to Keycloak. Direct connection (127.0.0.1:9998) failed and SSH tunnel creation also failed: ${tunnelErr.message}`);
+            }
+        } else {
+            // Not a connection refused error - propagate as-is
+            throw err;
+        }
+    }
+    
+    console.log('\n=== Global setup complete ===\n');
+});
+
+// Global after hook - cleanup test realm and SSH tunnel
+after(async function() {
+    this.timeout(60000);
+    
+    console.log('\n=== Running global test teardown ===\n');
+    
+    try {
+        // Load test config to get realm name
+        const { TEST_REALM } = require('./testConfig');
+        
+        // Delete test realm to restore server to initial state
+        try {
+            console.log(`Deleting test realm: ${TEST_REALM}`);
+            await keycloakManager.realms.del({ realm: TEST_REALM });
+            console.log(`✓ Test realm deleted: ${TEST_REALM}`);
+        } catch (err) {
+            if (err.message && err.message.includes('404')) {
+                console.log(`⚠ Test realm already deleted or not found: ${TEST_REALM}`);
+            } else {
+                console.error(`⚠ Error deleting test realm: ${err.message}`);
+            }
+        }
+        
+        // Stop Keycloak admin client to close connections
+        try {
+            keycloakManager.stop();
+            console.log('✓ Closed Keycloak admin client connection');
+        } catch (err) {
+            // Connection already closed or other state
+            console.log('✓ Keycloak admin client stopped');
+        }
+        
+        // Clean up SSH tunnel config file if it was created
+        try {
+            const configPath = path.join(__dirname, 'config/local.json');
+            if (fs.existsSync(configPath)) {
+                const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+                // Only delete local.json if it contains SSH tunnel config
+                if (config.test?.keycloak?.baseUrl?.includes('127.0.0.1:9998')) {
+                    fs.unlinkSync(configPath);
+                    console.log('✓ Cleaned up SSH tunnel config (test/config/local.json)');
+                }
+            }
+        } catch (err) {
+            console.log('⚠ Could not cleanup config file:', err.message);
+        }
+        
+    } catch (err) {
+        console.error('⚠ Error during test teardown:', err.message);
+    }
+    
+    if (sshTunnelProcess) {
+        console.log('✓ SSH tunnel will close automatically');
+    }
+    
+    console.log('\n=== Global test teardown complete ===\n');
+});

package/test/specs/authenticationManagement.test.js

@@ -0,0 +1,224 @@
+const path = require('path');
+const { expect } = require('chai');
+
+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');
+
+function shouldSkipFeature(err) {
+  if (!err || !err.message) {
+    return false;
+  }
+  const text = err.message.toLowerCase();
+  return (
+    text.includes('not supported') ||
+    text.includes('unknown_error') ||
+    text.includes('http 404') ||
+    text.includes('http 400')
+  );
+}
+
+async function getFlowByAliasOrId(aliasOrId, candidateId) {
+  try {
+    return await keycloakManager.authenticationManagement.getFlow({ flowId: aliasOrId });
+  } catch (firstErr) {
+    if (candidateId) {
+      return await keycloakManager.authenticationManagement.getFlow({ flowId: candidateId });
+    }
+    throw firstErr;
+  }
+}
+
+async function deleteFlowByAliasOrId(aliasOrId, candidateId) {
+  try {
+    await keycloakManager.authenticationManagement.deleteFlow({ flowId: aliasOrId });
+  } catch (firstErr) {
+    if (candidateId) {
+      await keycloakManager.authenticationManagement.deleteFlow({ flowId: candidateId });
+      return;
+    }
+    throw firstErr;
+  }
+}
+
+describe('AuthenticationManagement Handler', function () {
+  this.timeout(60000);
+
+  const keycloakConfig = (conf && conf.keycloak) || {};
+  const testRealm = `auth-mgmt-realm-${Date.now()}`;
+  const customFlowAlias = `custom-flow-${Date.now()}`;
+  const copiedFlowAlias = `copied-flow-${Date.now()}`;
+
+  before(async function () {
+    await keycloakManager.configure({
+      baseUrl: keycloakConfig.baseUrl,
+      realmName: keycloakConfig.realmName,
+      clientId: keycloakConfig.clientId,
+      clientSecret: keycloakConfig.clientSecret,
+      username: keycloakConfig.username,
+      password: keycloakConfig.password,
+      grantType: keycloakConfig.grantType,
+      tokenLifeSpan: keycloakConfig.tokenLifeSpan,
+      scope: keycloakConfig.scope,
+    });
+
+    await keycloakManager.realms.create({ realm: testRealm, enabled: true });
+    keycloakManager.setConfig({ realmName: testRealm });
+  });
+
+  after(async function () {
+    try {
+      keycloakManager.setConfig({ realmName: testRealm });
+    } catch (err) {
+      // best effort
+    }
+
+    try {
+      await keycloakManager.authenticationManagement.deleteFlow({ flowId: copiedFlowAlias });
+    } catch (err) {
+      // best effort
+    }
+
+    try {
+      await keycloakManager.authenticationManagement.deleteFlow({ flowId: customFlowAlias });
+    } catch (err) {
+      // best effort
+    }
+
+    try {
+      await keycloakManager.realms.del({ realm: testRealm });
+    } catch (err) {
+      // best effort
+    }
+
+    if (typeof keycloakManager.stop === 'function') {
+      keycloakManager.stop();
+    }
+  });
+
+  it('should list required actions and provider metadata', async function () {
+    const requiredActions = await keycloakManager.authenticationManagement.getRequiredActions();
+    expect(requiredActions).to.be.an('array');
+
+    const unregistered = await keycloakManager.authenticationManagement.getUnregisteredRequiredActions();
+    expect(unregistered).to.be.an('array');
+
+    const updatePassword = await keycloakManager.authenticationManagement.getRequiredActionForAlias({
+      alias: 'UPDATE_PASSWORD',
+    });
+    expect(updatePassword).to.be.an('object');
+
+    const actionProviders = await keycloakManager.authenticationManagement.getFormActionProviders();
+    expect(actionProviders).to.be.an('array');
+
+    const authenticatorProviders = await keycloakManager.authenticationManagement.getAuthenticatorProviders();
+    expect(authenticatorProviders).to.be.an('array');
+
+    const clientAuthenticatorProviders = await keycloakManager.authenticationManagement.getClientAuthenticatorProviders();
+    expect(clientAuthenticatorProviders).to.be.an('array');
+
+    const formProviders = await keycloakManager.authenticationManagement.getFormProviders();
+    expect(formProviders).to.be.an('array');
+  });
+
+  it('should read and modify required action settings when available', async function () {
+    try {
+      const before = await keycloakManager.authenticationManagement.getRequiredActionForAlias({
+        alias: 'UPDATE_PASSWORD',
+      });
+
+      const description = await keycloakManager.authenticationManagement.getRequiredActionConfigDescription({
+        alias: 'UPDATE_PASSWORD',
+      });
+      expect(description).to.be.an('object');
+
+      await keycloakManager.authenticationManagement.updateRequiredAction(
+        { alias: 'UPDATE_PASSWORD' },
+        {
+          ...before,
+          enabled: true,
+        }
+      );
+
+      await keycloakManager.authenticationManagement.raiseRequiredActionPriority({
+        alias: 'UPDATE_PASSWORD',
+      });
+      await keycloakManager.authenticationManagement.lowerRequiredActionPriority({
+        alias: 'UPDATE_PASSWORD',
+      });
+    } catch (err) {
+      if (shouldSkipFeature(err)) {
+        this.skip();
+        return;
+      }
+      throw err;
+    }
+  });
+
+  it('should manage authentication flows and executions', async function () {
+    const flows = await keycloakManager.authenticationManagement.getFlows();
+    expect(flows).to.be.an('array');
+    expect(flows.length).to.be.greaterThan(0);
+
+    const browserFlow = flows.find((flow) => flow.alias === 'browser') || flows[0];
+    const flowDetails = await getFlowByAliasOrId(browserFlow.alias, browserFlow.id);
+    expect(flowDetails).to.be.an('object');
+
+    await keycloakManager.authenticationManagement.createFlow({
+      alias: customFlowAlias,
+      providerId: 'basic-flow',
+      topLevel: true,
+      builtIn: false,
+      description: 'Test custom flow',
+    });
+
+    const flowsAfterCreate = await keycloakManager.authenticationManagement.getFlows();
+    const customFlowMeta = flowsAfterCreate.find((flow) => flow.alias === customFlowAlias);
+    const customFlow = await getFlowByAliasOrId(
+      customFlowAlias,
+      customFlowMeta && customFlowMeta.id
+    );
+    expect(customFlow).to.be.an('object');
+    expect(customFlow.alias).to.equal(customFlowAlias);
+
+    await keycloakManager.authenticationManagement.copyFlow({
+      flow: customFlowAlias,
+      newName: copiedFlowAlias,
+    });
+
+    const flowsAfterCopy = await keycloakManager.authenticationManagement.getFlows();
+    const copiedFlowMeta = flowsAfterCopy.find((flow) => flow.alias === copiedFlowAlias);
+    const copiedFlow = await getFlowByAliasOrId(
+      copiedFlowAlias,
+      copiedFlowMeta && copiedFlowMeta.id
+    );
+    expect(copiedFlow).to.be.an('object');
+    expect(copiedFlow.alias).to.equal(copiedFlowAlias);
+
+    const executions = await keycloakManager.authenticationManagement.getExecutions({
+      flow: copiedFlowAlias,
+    });
+    expect(executions).to.be.an('array');
+
+    try {
+      await keycloakManager.authenticationManagement.addExecutionToFlow({
+        flow: copiedFlowAlias,
+        provider: 'auth-cookie',
+      });
+
+      const executionsAfter = await keycloakManager.authenticationManagement.getExecutions({
+        flow: copiedFlowAlias,
+      });
+      expect(executionsAfter).to.be.an('array');
+    } catch (err) {
+      if (!shouldSkipFeature(err)) {
+        throw err;
+      }
+    }
+
+    await deleteFlowByAliasOrId(copiedFlowAlias, copiedFlowMeta && copiedFlowMeta.id);
+    await deleteFlowByAliasOrId(customFlowAlias, customFlowMeta && customFlowMeta.id);
+  });
+});

package/test/specs/clientCredentials.test.js

@@ -0,0 +1,76 @@
+const path = require('path');
+const { expect } = require('chai');
+
+process.env.NODE_ENV = process.env.NODE_ENV || 'test';
+process.env.PROPERTIES_PATH = path.join(__dirname, '..', 'config');
+
+const keycloakManager = require('keycloak-api-manager');
+const { KEYCLOAK_CONFIG, TEST_CLIENT_ID, TEST_REALM } = require('../testConfig');
+
+function buildConfig(overrides = {}) {
+  return {
+    ...KEYCLOAK_CONFIG,
+    ...overrides,
+  };
+}
+
+describe('Authentication - client_credentials grant', function () {
+  this.timeout(20000);
+
+  let testClientId = null;
+  let testClientSecret = null;
+
+  before(async function () {
+    const clients = await keycloakManager.clients.find({ clientId: TEST_CLIENT_ID });
+    const testClient = clients.find((client) => client.clientId === TEST_CLIENT_ID);
+
+    if (!testClient) {
+      this.skip();
+      return;
+    }
+
+    testClientId = testClient.clientId;
+    const secret = await keycloakManager.clients.getClientSecret({ id: testClient.id });
+    testClientSecret = secret?.value;
+
+    if (!testClientSecret) {
+      this.skip();
+    }
+  });
+
+  after(async function () {
+    if (!KEYCLOAK_CONFIG?.username || !KEYCLOAK_CONFIG?.password) {
+      return;
+    }
+
+    await keycloakManager.configure(
+      buildConfig({
+        grantType: KEYCLOAK_CONFIG.grantType || 'password',
+        tokenLifeSpan: KEYCLOAK_CONFIG.tokenLifeSpan || 60,
+      })
+    );
+  });
+
+  it('authenticates without refresh token errors', async function () {
+    if (!testClientId || !testClientSecret) {
+      this.skip();
+      return;
+    }
+
+    await keycloakManager.configure(
+      buildConfig({
+        realmName: TEST_REALM,
+        clientId: testClientId,
+        clientSecret: testClientSecret,
+        grantType: 'client_credentials',
+        tokenLifeSpan: 60,
+        username: undefined,
+        password: undefined,
+      })
+    );
+
+    const token = keycloakManager.getToken();
+    expect(token).to.have.property('accessToken');
+    expect(token.accessToken).to.be.a('string').and.to.have.length.greaterThan(0);
+  });
+});