keycloak-api-manager 6.0.2 → 6.0.4

package/docs/api/roles.md

@@ -2,7 +2,12 @@
 
 Realm and client role management, including composite roles.
 
-**Namespace:** `KeycloakManager.roles`
+Namespace: KeycloakManager.roles
+
+## Overview
+
+This handler manages realm roles and composite relationships.
+It covers CRUD, user-role lookup, and composite role operations for realm and client roles.
 
 ## Role CRUD
 
@@ -16,25 +21,28 @@ Create a realm role.
 ### find(filters)
 List realm roles.
 
-- **Optional**: `first`, `max`, `search`, `briefRepresentation`
+- **Optional**: `first`, `max`, `search`, `briefRepresentation`, `realm`
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ### findOneByName(filters)
 Get role by name.
 
 - **Required**: `filters.name` (string)
+- **Optional**: `filters.realm` (string)
 - **Returns**: Promise<RoleRepresentation>
 
 ### findOneById(filters)
 Get role by id.
 
 - **Required**: `filters.id` (string)
+- **Optional**: `filters.realm` (string)
 - **Returns**: Promise<RoleRepresentation>
 
 ### updateByName(filters, role_dictionary)
 Update role by name.
 
 - **Required**: `filters.name` (string)
+- **Optional**: `filters.realm` (string)
 - **Required**: `role_dictionary` (partial role)
 - **Returns**: Promise<void>
 
@@ -42,6 +50,7 @@ Update role by name.
 Update role by id.
 
 - **Required**: `filters.id` (string)
+- **Optional**: `filters.realm` (string)
 - **Required**: `role_dictionary` (partial role)
 - **Returns**: Promise<void>
 
@@ -49,6 +58,7 @@ Update role by id.
 Delete role by name.
 
 - **Required**: `filters.name` (string)
+- **Optional**: `filters.realm` (string)
 - **Returns**: Promise<void>
 
 ## Composite Roles
@@ -56,27 +66,31 @@ Delete role by name.
 ### createComposite(filters, roles)
 Add composites to a realm role.
 
-- **Required**: `filters.roleName` (string)
+- **Required**: `filters.roleId` (string)
+- **Optional**: `filters.realm` (string)
 - **Required**: `roles` (Array<{id,name}>), realm or client roles
 - **Returns**: Promise<void>
 
 ### getCompositeRoles(filters)
 Get all composites for a role.
 
-- **Required**: `filters.roleName` (string)
+- **Required**: `filters.id` (string)
+- **Optional**: `filters.realm` (string)
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ### getCompositeRolesForRealm(filters)
 Get realm-level composites.
 
-- **Required**: `filters.roleName` (string)
+- **Required**: `filters.id` (string)
+- **Optional**: `filters.realm` (string)
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ### getCompositeRolesForClient(filters)
 Get client-level composites.
 
-- **Required**: `filters.roleName` (string)
-- **Required**: `filters.clientUniqueId` (client UUID)
+- **Required**: `filters.id` (string)
+- **Required**: `filters.clientId` (string, client UUID)
+- **Optional**: `filters.realm` (string)
 - **Returns**: Promise<Array<RoleRepresentation>>
 
 ## Users with Role
@@ -85,6 +99,7 @@ Get client-level composites.
 List users that have a specific realm role.
 
 - **Required**: `filters.name` (role name)
+- **Optional**: `filters.realm` (string)
 - **Optional**: `first`, `max`
 - **Returns**: Promise<Array<UserRepresentation>>
 
@@ -94,6 +109,21 @@ List users that have a specific realm role.
 await KeycloakManager.roles.create({ name: 'realm-admin' });
 const role = await KeycloakManager.roles.findOneByName({ name: 'realm-admin' });
 const users = await KeycloakManager.roles.findUsersWithRole({ name: 'realm-admin' });
+
+// Composite role with one realm role and one client role
+await KeycloakManager.roles.createComposite(
+	{ roleId: compositeRoleId },
+	[
+		{ id: realmRoleId, name: 'test-role-1' },
+		{ id: clientRoleId, name: 'client-role-a', clientRole: true, containerId: clientUuid }
+	]
+);
+
+const realmComposites = await KeycloakManager.roles.getCompositeRolesForRealm({ id: compositeRoleId });
+const clientComposites = await KeycloakManager.roles.getCompositeRolesForClient({
+	id: compositeRoleId,
+	clientId: clientUuid,
+});
 ```
 
 ## See Also

package/docs/api/server-info.md

@@ -2,37 +2,62 @@
 
 Read Keycloak server capabilities and runtime metadata.
 
-**Namespace:** `KeycloakManager.serverInfo`
+Namespace: KeycloakManager.serverInfo
+
+## Overview
+
+Use this handler to inspect server capabilities before enabling advanced features in automation.
+It is useful for diagnostics and compatibility checks in CI pipelines.
 
 ## Methods
 
 ### getInfo()
-Get full server-info payload.
 
-- **Params**: none
-- **Returns**: Promise<object>
+Fetch the full server-info payload from the configured realm context.
+
+Parameters:
+
+- none
+
+Returns:
+
+- Promise<object>: full server info payload.
+
+Common top-level sections returned by Keycloak include:
 
-The payload typically includes:
-- `systemInfo`
-- `memoryInfo`
-- `profileInfo`
-- `themes`
-- `providers`
-- `componentTypes`
-- `passwordPolicies`
-- `protocolMapperTypes`
-- `clientInstallations`
-- `enums`
+- systemInfo
+- memoryInfo
+- profileInfo
+- themes
+- providers
+- componentTypes
+- passwordPolicies
+- protocolMapperTypes
+- clientInstallations
+- enums
 
-## Example
+Example: basic inspection
 
 ```js
 const info = await KeycloakManager.serverInfo.getInfo();
 
 console.log('Keycloak version:', info.systemInfo?.version);
 console.log('Available themes:', Object.keys(info.themes || {}));
-console.log('Available provider categories:', Object.keys(info.providers || {}));
+console.log('Provider categories:', Object.keys(info.providers || {}));
+```
+
+Example: feature guard before workflow
+
+```js
+const info = await KeycloakManager.serverInfo.getInfo();
+const hasOrganizationFeature = Boolean(info.profileInfo?.features?.organization);
+
+if (!hasOrganizationFeature) {
+	throw new Error('Organization feature is not enabled on this Keycloak server.');
+}
 ```
 
 ## See Also
+
 - [API Reference](../api-reference.md)
+- [Keycloak Setup and Feature Flags](../keycloak-setup.md)

package/docs/api/user-profile.md

@@ -2,28 +2,72 @@
 
 Manage realm user-profile configuration and metadata.
 
-**Namespace:** `KeycloakManager.userProfile`
+Namespace: KeycloakManager.userProfile
+
+## Overview
+
+This handler manages declarative user-profile schema in a realm.
+It allows you to inspect current schema, update it, and read resolved metadata (validators, capabilities, attribute model).
+
+Note: endpoints are accessed through direct REST calls in the handler for compatibility across admin-client versions.
 
 ## Methods
 
 ### getConfiguration(filter)
-Get user-profile configuration for realm.
 
-- **Optional**: realm context fields
-- **Returns**: Promise<object>
+Get the current declarative user-profile configuration.
+
+Parameters:
+
+- filter (object, optional):
+- realm (string, optional): override target realm.
+
+Returns:
+
+- Promise<object>: current profile configuration.
 
 ### updateConfiguration(filter, userProfileConfig)
+
 Update user-profile configuration.
 
-- **Optional**: realm context fields
-- **Required**: `userProfileConfig` (full/partial config object)
-- **Returns**: Promise<void|object>
+Parameters:
+
+- filter (object, optional):
+- realm (string, optional): override target realm.
+- userProfileConfig (object, required): full or partial schema payload.
+
+Common top-level fields:
+
+- attributes (array): attribute definitions.
+- groups (array, optional): grouped attributes.
+- unmanagedAttributePolicy (string, optional)
+
+Common attribute fields:
+
+- name (string, required): attribute key.
+- displayName (string, optional)
+- required (object, optional): required rules.
+- permissions (object, optional): view/edit permissions.
+- validations (object, optional): validation rules.
+- annotations (object, optional): UI/metadata annotations.
+- multivalued (boolean, optional): enable list values.
+
+Returns:
+
+- Promise<void|object>: usually no content (204), or response payload if provided by server.
 
 ### getMetadata(filter)
-Get resolved user-profile metadata.
 
-- **Optional**: realm context fields
-- **Returns**: Promise<object>
+Get user-profile metadata resolved by the server.
+
+Parameters:
+
+- filter (object, optional):
+- realm (string, optional): override target realm.
+
+Returns:
+
+- Promise<object>: metadata payload (validators, resolved attributes, capabilities).
 
 ## Common User Profile Structure
 
@@ -56,6 +100,7 @@ await KeycloakManager.userProfile.updateConfiguration({}, {
 });
 
 const metadata = await KeycloakManager.userProfile.getMetadata();
+console.log('Available validators:', Object.keys(metadata.validators || {}));
 ```
 
 ## See Also

package/docs/api-reference.md

@@ -5,7 +5,7 @@ Complete API documentation for keycloak-api-manager.
 ## Table of Contents
 
 ### Guides
-- [OIDC Migration Plan](../OIDC_MIGRATION_PLAN.md) - Deprecation status and migration notes to keycloak-express-middleware
+- [OIDC Migration Plan](../OIDC_MIGRATION_PLAN.md) - Migration notes for legacy OIDC helpers
 
 ### Core API
 - [Configuration & Authentication](api/configuration.md) - Setup, authentication, and lifecycle management
@@ -61,7 +61,8 @@ await KeycloakManager.configure({
   tokenLifeSpan: 60
 });
 
-// Switch to different realm
+// Alternative after configure(): switch runtime context without calling
+// configure() again (no new login/token flow is performed).
 KeycloakManager.setConfig({ realmName: 'my-realm' });
 
 // Use handlers
@@ -79,10 +80,7 @@ KeycloakManager.stop();
 | `configure()` | Authentication and setup | Core |
 | `setConfig()` | Runtime configuration | Core |
 | `getToken()` | Get current access/refresh token pair | Core |
-| `login()` | Deprecated OIDC token endpoint wrapper (moved to keycloak-express-middleware) | Core |
-| `generateAuthorizationUrl()` | Deprecated PKCE helper (moved to keycloak-express-middleware) | Core |
-| `loginPKCE()` | Deprecated PKCE token exchange helper (moved to keycloak-express-middleware) | Core |
-| `auth()` | Deprecated backward-compatible alias of `login()` | Core |
+| Legacy OIDC helpers | Backward-compatibility methods (`login`, `generateAuthorizationUrl`, `loginPKCE`, `auth`) | Core |
 | `stop()` | Stop token refresh timer | Core |
 | `realms` | Realm management | realmsHandler |
 | `users` | User management | usersHandler |
@@ -99,6 +97,8 @@ KeycloakManager.stop();
 | `clientPolicies` | Client policy management | clientPoliciesHandler |
 | `serverInfo` | Server information | serverInfoHandler |
 
+For deprecation status and migration guidance, see [README - OIDC Deprecation Notice](../README.md#oidc-deprecation-notice).
+
 ## Parameter Conventions
 
 Throughout the API:

package/docs/architecture.md

@@ -15,10 +15,9 @@ This package exposes a single runtime (`index.js`) that initializes one Keycloak
    - Keeps active session/token management in place.
 
 3. `login(credentials)`
-   - Direct token endpoint call for explicit OIDC login/token flows.
-   - Intended for application-level third-party authentication use-cases.
+   - Legacy OIDC helper kept for backward compatibility.
    - Does not mutate the internal admin client session established by `configure()`.
-   - `auth(credentials)` remains available as backward-compatible alias.
+   - For deprecation and migration guidance, see the README OIDC Deprecation Notice.
 
 4. `stop()`
    - Stops refresh timer for clean process termination.

package/docs/guides/PKCE-Login-Flow.md

@@ -1,21 +1,8 @@
-# PKCE Login Flow (Deprecated In This Package)
+# PKCE Login Flow
 
-This package is focused on Keycloak Admin API resource management.
+PKCE and user-authentication helpers in this package are deprecated and retained only for backward compatibility.
 
-PKCE and user-authentication helpers in this package are deprecated since v6.0.0 and kept only for backward compatibility:
-
-- `generateAuthorizationUrl(options)`
-- `loginPKCE(credentials)`
-- `login(credentials)`
-- `auth(credentials)`
-
-These methods are planned for removal in v7.0.0.
-
-For production user authentication flows (including Authorization Code + PKCE), use:
-
-- https://github.com/smartenv-crs4/keycloak-express-middleware
-
-Migration references:
+For the canonical deprecation notice and migration path, see:
 
+- [README - OIDC Deprecation Notice](../../README.md#oidc-deprecation-notice)
 - [OIDC Migration Plan](../../OIDC_MIGRATION_PLAN.md)
-- [Configuration & Authentication](../api/configuration.md)

package/docs/test-configuration.md

@@ -1,43 +1,5 @@
 # Test Configuration
 
-Test configuration is managed through `propertiesmanager` with layered files.
+This file has been merged into the unified [Testing Guide](testing.md).
 
-## 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.
+See [Testing Guide — Test Configuration](testing.md#test-configuration) for all config details.

package/docs/testing.md

@@ -1,6 +1,199 @@
 # Testing Guide
 
-The test suite validates the package against a real Keycloak server.
+The test suite validates the package against a real Keycloak server. This guide covers both test environment setup and configuration.
+
+## Table of Contents
+
+- [Quick Start](#quick-start-end-to-end)
+- [Test Configuration](#test-configuration)
+- [Test Architecture](#test-architecture)
+- [Test Layout](#current-test-layout)
+- [Commands](#commands)
+- [HTTPS Variant](#https-variant)
+- [Setup Flow](#setup-flow)
+- [Writing New Tests](#writing-new-tests)
+
+---
+
+## Quick Start (End-to-End)
+
+### 1) Install dependencies
+
+```bash
+npm install
+npm --prefix test install
+```
+
+### 2) Prepare local test config
+
+Create local override files from the provided examples:
+
+```bash
+cp test/config/local.json.example test/config/local.json
+cp test/config/secrets.json.example test/config/secrets.json
+```
+
+Then edit:
+
+- `test/config/local.json` to set the Keycloak URL you can reach locally.
+- `test/config/secrets.json` to set admin credentials.
+
+For local Docker on default HTTP port:
+
+```json
+{
+  "test": {
+    "keycloak": {
+      "baseUrl": "http://127.0.0.1:8080",
+      "password": "admin"
+    }
+  }
+}
+```
+
+### 3) Prepare Keycloak for tests (choose one mode)
+
+Choose one of the following modes.
+
+#### Mode A: Existing Keycloak instance (no Docker startup here)
+
+If you already have a reachable Keycloak instance:
+
+- set `test.keycloak.baseUrl` in `test/config/local.json` to that instance URL
+- ensure admin credentials in `test/config/secrets.json` are valid for that instance
+- skip any startup command and run tests directly
+
+Example using an existing instance:
+
+```json
+{
+  "test": {
+    "keycloak": {
+      "baseUrl": "https://my-keycloak.company.net"
+    }
+  }
+}
+```
+
+Then run:
+
+```bash
+npm test
+```
+
+#### Mode B: Automated setup with `npm run setup-keycloak`
+
+Use this when you do not already have a ready instance and want the helper to provision one.
+
+```bash
+npm run setup-keycloak
+```
+
+What this command does:
+
+- runs an interactive setup (local or remote, HTTP or HTTPS)
+- starts Keycloak via Docker Compose in the selected mode
+- waits for readiness
+- updates `test/config/default.json` with the generated `test.keycloak.baseUrl`
+
+#### Mode C: Manual Docker startup
+
+Use this if you prefer full manual control instead of the setup helper:
+
+```bash
+docker compose -f test/docker-keycloak/docker-compose.yml up -d
+```
+
+Wait until ready:
+
+```bash
+docker compose -f test/docker-keycloak/docker-compose.yml ps
+curl -f http://127.0.0.1:8080/health/ready
+```
+
+### 4) Run tests
+
+```bash
+npm test
+```
+
+### 5) Stop environment (optional but recommended)
+
+```bash
+docker compose -f test/docker-keycloak/docker-compose.yml down
+```
+
+To also remove container volumes:
+
+```bash
+docker compose -f test/docker-keycloak/docker-compose.yml down -v
+```
+
+---
+
+## Test Configuration
+
+Test configuration uses `propertiesmanager` with a layered file strategy. Files are merged in this priority order (higher overrides lower):
+
+1. `test/config/default.json` — committed defaults, non-sensitive
+2. `test/config/secrets.json` — gitignored, admin credentials and passwords
+3. `test/config/local.json` — gitignored, machine-specific host/port overrides
+
+The active section is selected by `NODE_ENV` (defaults to `test` in suite bootstrap).
+
+### Required Configuration Keys
+
+| Key | Description |
+|-----|-------------|
+| `test.keycloak.baseUrl` | Keycloak server URL |
+| `test.keycloak.realmName` | Realm used for authentication |
+| `test.keycloak.clientId` | Client ID (usually `admin-cli`) |
+| `test.keycloak.username` | Admin username |
+| `test.keycloak.password` | Admin password (put in `secrets.json`) |
+| `test.keycloak.grantType` | Usually `password` |
+
+### Recommended Pattern
+
+- Keep defaults and non-sensitive values in `default.json`.
+- Put admin passwords and test user passwords in `secrets.json`.
+- Put local machine-specific URLs/ports in `local.json`.
+
+Example `local.json`:
+
+```json
+{
+  "test": {
+    "keycloak": {
+      "baseUrl": "http://127.0.0.1:8080"
+    }
+  }
+}
+```
+
+Example `secrets.json`:
+
+```json
+{
+  "test": {
+    "keycloak": {
+      "password": "your-admin-password-here"
+    },
+    "realm": {
+      "user": {
+        "password": "test-password"
+      }
+    }
+  }
+}
+```
+
+### Security Rules
+
+- Never commit `secrets.json` or `local.json`.
+- Never commit production credentials.
+- Keep `default.json` non-sensitive.
+
+---
 
 ## Test Architecture
 
@@ -12,6 +205,8 @@ The suite uses a shared realm strategy:
 
 This improves speed and keeps the environment deterministic.
 
+---
+
 ## Current Test Layout
 
 ```text
@@ -26,9 +221,14 @@ test/
     testConfig.js
 ```
 
+---
+
 ## Commands
 
 ```bash
+# interactive provisioning helper (starts docker and sets baseUrl)
+npm run setup-keycloak
+
 # full suite
 npm test
 
@@ -40,6 +240,41 @@ npm --prefix test test -- --grep "Organizations Handler Tests"
 npm --prefix test test -- --grep "Matrix -"
 ```
 
+### Command Difference: `npm test` vs `npm --prefix test test`
+
+- `npm test` (from repository root): runs the root test script, which first installs test workspace dependencies and then executes the suite.
+- `npm --prefix test test`: runs the test workspace script directly, without performing the install step.
+
+Current root script behavior:
+
+```text
+npm test => npm --prefix test install && npm --prefix test test
+```
+
+Practical rule:
+
+- use `npm test` when setting up a fresh environment or after dependency changes
+- use `npm --prefix test test` for faster repeated runs when dependencies are already installed
+
+---
+
+## HTTPS Variant
+
+For HTTPS-like environments use the dedicated compose file:
+
+```bash
+export KEYCLOAK_CERT_PATH=/absolute/path/to/certs
+export KEYCLOAK_HOSTNAME=keycloak.local
+docker compose -f test/docker-keycloak/docker-compose-https.yml up -d
+```
+
+The cert directory must contain:
+
+- `keycloak.crt`
+- `keycloak.key`
+
+---
+
 ## Setup Flow
 
 `test/support/setup.js` runs before all suites and executes `test/support/enableServerFeatures.js` to provision:
@@ -52,6 +287,10 @@ npm --prefix test test -- --grep "Matrix -"
 - client scope
 - fine-grained permissions (when feature-enabled)
 
+The same bootstrap also performs cleanup in global teardown by deleting the shared test realm.
+
+---
+
 ## Writing New Tests
 
 - Import config from `test/testConfig.js`.