keycloak-api-manager 3.2.1 → 4.0.1

package/test/config/CONFIGURATION.md

@@ -0,0 +1,170 @@
+# 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/config/default.json

@@ -0,0 +1,36 @@
+{
+  "test": {
+    "keycloak": {
+      "baseUrl": "https://smart-dell-sml.crs4.it:8443",
+      "realmName": "master",
+      "clientId": "admin-cli",
+      "username": "admin",
+      "grantType": "password",
+      "tokenLifeSpan": 60
+    },
+    "realm": {
+      "name": "keycloak-api-manager-test-realm",
+      "client": {
+        "clientId": "test-client",
+        "clientSecret": "test-client-secret"
+      },
+      "user": {
+        "username": "test-user",
+        "email": "test-user@test.local",
+        "firstName": "Test",
+        "lastName": "User"
+      },
+      "roles": [
+        "test-role-1",
+        "test-role-2",
+        "test-admin-role"
+      ],
+      "group": {
+        "name": "test-group"
+      },
+      "clientScope": {
+        "name": "test-scope"
+      }
+    }
+  }
+}

package/test/config/local.json.example

@@ -0,0 +1,7 @@
+{
+  "test": {
+    "keycloak": {
+      "baseUrl": "http://127.0.0.1:9998"
+    }
+  }
+}

package/test/config/secrets.json.example

@@ -0,0 +1,7 @@
+{
+  "test": {
+    "keycloak": {
+      "adminPassword": "your-admin-password-here"
+    }
+  }
+}

package/test/diagnostic-protocol-mappers.js

@@ -0,0 +1,189 @@
+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();

package/test/docker-keycloak/DEPLOYMENT_GUIDE.md

@@ -0,0 +1,262 @@
+# Keycloak Deployment Setup Guide
+
+## Quick Start
+
+### Local HTTP (Development)
+```bash
+npm run setup-keycloak
+# Select: 1 (Local)
+# Select: 1 (HTTP)
+# ✓ Keycloak accessible at http://localhost:8080
+```
+
+### Local HTTPS (Production-like)
+```bash
+npm run setup-keycloak
+# Select: 1 (Local)
+# Select: 2 (HTTPS)
+# 
+# If certificates exist in test/docker-keycloak/certs:
+#   ✓ Script automatically uses them
+# 
+# Otherwise, enter certificate path when prompted:
+#   Certificate directory path: /path/to/certs
+#   (or press Enter to use default location)
+# 
+# ✓ Keycloak accessible at https://localhost:8443
+```
+
+### Remote HTTP
+```bash
+npm run setup-keycloak
+# Choose deployment: Remote (auto-selected, no Docker locally)
+# Enable HTTPS: 1 (No - HTTP)
+# Remote host/IP: smart@smart-dell-sml.crs4.it
+# ✓ Keycloak deployed at http://smart-dell-sml.crs4.it:8080
+```
+
+### Remote HTTPS
+```bash
+npm run setup-keycloak
+# Choose deployment: Remote (auto-selected)
+# Enable HTTPS: 2 (Yes - HTTPS)
+# → Certificates automatically loaded from: test/docker-keycloak/certs
+# Remote host/IP: smart@smart-dell-sml.crs4.it
+# ✓ Certificates copied to remote and deployed with HTTPS
+# ✓ Keycloak accessible at https://smart-dell-sml.crs4.it:8443
+```
+
+## Features
+
+### ✅ Local Deployment
+- **HTTP Mode**: Development environment, no certificates needed
+- **HTTPS Mode**: Production-like environment using SSL/TLS certificates
+- **Automatic Health Checks**: Waits for Keycloak to be fully ready
+- **Docker Integration**: Uses docker-compose for easy container management
+
+### ✅ Remote Deployment via SSH
+- **Automatic File Transfer**: Copies docker-compose files via SCP
+- **Certificate Management**: Copies certificates to remote server if HTTPS enabled
+- **SSH Connectivity**: Verifies SSH connection before deployment
+- **Health Checks**: Confirms Keycloak is running on remote server
+
+### ✅ Configuration Management
+- **.env Files**: Auto-generated configuration files
+- **Certificate Mounting**: Automatic mounting of SSL certificates
+- **Hostname Configuration**: Sets proper KEYCLOAK_HOSTNAME for remote servers
+- **Port Configuration**: Supports custom ports for HTTPS
+
+## File Structure
+
+```
+keycloak-api-manager/
+├── docker-compose.yml              # HTTP configuration
+├── docker-compose-https.yml         # HTTPS configuration
+├── .env                             # Generated by setup script (gitignored)
+├── .env.example                     # Reference configuration
+└── test/
+    └── setup-keycloak.js            # Interactive setup script
+```
+
+## Certificate Configuration
+
+### Default Location
+For local HTTPS deployments, the script automatically searches for certificates in:
+```
+test/docker-keycloak/certs/
+├── keycloak.crt  (X.509 certificate)
+└── keycloak.key  (Private key)
+```
+
+**If found**: Script uses them automatically ✅  
+**If not found**: Script prompts you to enter a custom path
+
+The default location allows you to:
+- Generate certificates once and commit them to the repo
+- Run the script without entering certificate path every time
+- Keep certificates organized with the deployment infrastructure
+
+### For Remote Deployments - Automatic Certificate Handling
+
+When deploying to a remote server with HTTPS, the script **automatically**:
+1. Loads certificates from the local `test/docker-keycloak/certs/` directory
+2. Verifies they exist (fails with clear error if missing)
+3. Copies them to the remote server in `deployment_path/certs/`
+4. Uses them for the HTTPS configuration
+
+**No manual prompts** - just ensure you have valid certificates in `test/docker-keycloak/certs/`:
+```bash
+test/docker-keycloak/certs/
+├── keycloak.crt
+└── keycloak.key
+```
+
+### For Local Deployments - Custom Certificate Path
+
+For local HTTPS deployments, certificates are first sought in `test/docker-keycloak/certs/`.  
+If not found there, you will be prompted to enter a custom path:
+```bash
+Certificate directory path (or press Enter for default): /path/to/your/certs
+```
+
+### Certificate Files Required
+For HTTPS deployments, ensure the certificate directory contains:
+- `keycloak.crt` - X.509 certificate file
+- `keycloak.key` - Unencrypted private key file
+
+Example self-signed certificate generation:
+```bash
+# Generate self-signed certificate for testing
+openssl req -x509 -newkey rsa:2048 -keyout keycloak.key \
+  -out keycloak.crt -days 365 -nodes \
+  -subj "/CN=keycloak.test/O=Test/C=US"
+
+# Place in the default location
+mkdir -p test/docker-keycloak/certs
+cp keycloak.crt keycloak.key test/docker-keycloak/certs/
+```
+
+## Configuration Details
+
+### Environment Variables
+
+**HTTP Version**:
+- `KEYCLOAK_HOSTNAME`: Hostname for Keycloak (localhost for local, hostname for remote)
+
+**HTTPS Version**:
+- `KEYCLOAK_CERT_PATH`: Path to certificate directory
+- `KEYCLOAK_HOSTNAME`: Hostname for Keycloak (must match certificate CN for production)
+
+### Docker Compose Files
+
+**docker-compose.yml** (HTTP):
+```yaml
+- Image: keycloak/keycloak:latest
+- Ports: 8080 (HTTP)
+- Database: In-memory (KC_DB: dev-mem)
+- Admin Creds: admin:admin
+```
+
+**docker-compose-https.yml** (HTTPS):
+```yaml
+- Image: keycloak/keycloak:latest
+- Ports: 8080 (HTTP), 8443 (HTTPS)
+- Certificates: Mounted from KEYCLOAK_CERT_PATH
+- Admin Creds: admin:admin
+```
+
+## Troubleshooting
+
+### SSH Connection Failed
+```bash
+# Verify SSH access
+ssh -v smart@smart-dell-sml.crs4.it 'echo OK'
+
+# Check SSH key permissions
+ls -la ~/.ssh/id_ed25519
+chmod 600 ~/.ssh/id_ed25519
+```
+
+### HTTPS Certificate Issues
+```bash
+# Verify certificate files exist
+ls -la /path/to/certs/keycloak.crt
+ls -la /path/to/certs/keycloak.key
+
+# Test certificate validity
+openssl x509 -in keycloak.crt -text -noout
+
+# For browser access with self-signed cert:
+# - Use curl -k (insecure flag)
+# - Add browser exception for the domain
+```
+
+### Keycloak Takes Too Long to Start
+```bash
+# Check container logs
+docker-compose -f docker-compose.yml logs -f
+
+# Or remotely
+ssh smart@smart-dell-sml.crs4.it 'cd /home/smart/keycloak && docker-compose -f docker-compose-https.yml logs -f'
+```
+
+### Port Already in Use
+```bash
+# Check what's using the port
+lsof -i :8080
+lsof -i :8443
+
+# Kill existing container
+docker-compose down
+```
+
+## Running Tests with Different Deployments
+
+After deploying Keycloak with the setup script, run tests:
+
+```bash
+# Tests will automatically detect and connect to Keycloak
+npm test
+
+# The test setup handles:
+# - Local HTTP: Connects to http://localhost:8080
+# - Local HTTPS: Connects to https://localhost:8443
+# - Remote: Can be configured in test/config/default.json
+```
+
+## Advanced Configuration
+
+### Custom Keycloak Version
+Edit `docker-compose.yml` or `docker-compose-https.yml`:
+```yaml
+services:
+  keycloak:
+    image: keycloak/keycloak:25.0  # Change version here
+```
+
+### Custom Database
+Edit docker-compose files, change `KC_DB`:
+```yaml
+environment:
+  KC_DB: postgres  # Instead of dev-mem
+  KC_DB_URL_HOST: postgres-host
+  KC_DB_URL_PORT: 5432
+  KC_DB_USERNAME: keycloak
+  KC_DB_PASSWORD: password
+```
+
+### Additional Environment Variables
+Add to `.env`:
+```bash
+KC_LOG_LEVEL=INFO
+KC_METRICS_ENABLED=true
+KC_CACHE=ispn
+```
+
+## Support
+
+For issues or questions:
+- Check Docker logs: `docker-compose logs -f`
+- Check Keycloak admin console: http://localhost:8080
+- Review certificates: `openssl x509 -in keycloak.crt -text -noout`
+- Test connectivity: `curl -k https://localhost:8443/health/ready`

package/test/docker-keycloak/certs/.gitkeep

@@ -0,0 +1,7 @@
+# This directory is for storing SSL certificates
+# Place your keycloak.crt and keycloak.key files here
+# They will NOT be committed to git (see .gitignore)
+#
+# Example:
+#   cp /path/to/your/keycloak.crt keycloak.crt
+#   cp /path/to/your/keycloak.key keycloak.key