keycloak-api-manager 6.0.3 → 6.0.4

package/README.md

@@ -25,11 +25,13 @@ It provides a stable, function-oriented interface for managing Keycloak resource
 npm install keycloak-api-manager
 ```
 
-> **⚠️ DEPRECATION NOTICE (v6.0.0):** The OIDC authentication methods (`login()`, `loginPKCE()`, `generateAuthorizationUrl()`, `auth()`) have been **deprecated** and moved to [`keycloak-express-middleware`](https://github.com/smartenv-crs4/keycloak-express-middleware).
-> 
-> **This package is now exclusively for Keycloak admin resource management.** For user authentication flows, use `keycloak-express-middleware` instead.
-> 
-> See [OIDC_MIGRATION_PLAN.md](OIDC_MIGRATION_PLAN.md) for migration details.
+## OIDC Deprecation Notice
+
+DEPRECATION NOTICE (v6.0.0): The OIDC authentication methods (login(), loginPKCE(), generateAuthorizationUrl(), auth()) have been deprecated and moved to keycloak-express-middleware.
+
+This package is now exclusively for Keycloak admin resource management. For user authentication flows, use keycloak-express-middleware instead.
+
+See [OIDC_MIGRATION_PLAN.md](OIDC_MIGRATION_PLAN.md) for migration details.
 
 ## Quick Start
 
@@ -46,6 +48,8 @@ await KeycloakManager.configure({
   tokenLifeSpan: 60
 });
 
+// Alternative after configure(): update runtime context (for example realm)
+// without re-authenticating or calling configure() again.
 KeycloakManager.setConfig({ realmName: 'my-realm' });
 
 const users = await KeycloakManager.users.find({ max: 20 });
@@ -54,19 +58,41 @@ console.log(users.length);
 KeycloakManager.stop();
 ```
 
-> **💡 Tip:** For user authentication (including Authorization Code + PKCE), use [`keycloak-express-middleware`](https://github.com/smartenv-crs4/keycloak-express-middleware). OIDC methods in this package are deprecated and kept only for backward compatibility.
-
 ## Keycloak Feature Flags
 
-For full API coverage in this package (especially Organizations, Client Policies, User Profile, Group permissions), run Keycloak with:
+Some APIs exposed by this package depend on Keycloak server features that are disabled by default. Enable these flags when you want full endpoint coverage (local dev, CI, or production environments that use these modules):
 
 ```bash
 --features=admin-fine-grained-authz:v1,organization,client-policies
 ```
 
-### Why `admin-fine-grained-authz:v1`
+What each flag is for:
+
+- `admin-fine-grained-authz:v1`: enables management-permissions endpoints used by group/user fine-grained permission flows.
+- `organization`: enables Organizations APIs.
+- `client-policies`: enables Client Policies and Client Profiles APIs.
+
+When you can skip them:
+
+- If you only use core admin operations (for example realms/users/clients CRUD), the package still works without these flags.
+- If you use `organizations`, `clientPolicies`, or management-permissions methods, these flags are required.
+
+### Why `admin-fine-grained-authz:v1` in Keycloak 26.x
 
-In Keycloak 26.x, management-permissions APIs used by group/user fine-grained tests are compatible with `v1`.
+In Keycloak 26.x, the management-permissions APIs used by this package are compatible with the `v1` variant, so `admin-fine-grained-authz:v1` is the recommended setting.
+
+### Example (Docker)
+
+```bash
+docker run -d --name keycloak \
+  -p 8080:8080 \
+  -e KEYCLOAK_ADMIN=admin \
+  -e KEYCLOAK_ADMIN_PASSWORD=admin \
+  -e KC_FEATURES=admin-fine-grained-authz:v1,organization,client-policies \
+  quay.io/keycloak/keycloak:latest start-dev
+```
+
+See [Keycloak Setup and Feature Flags](docs/keycloak-setup.md) for full setup details.
 
 ## Public API Entry Points
 
@@ -74,12 +100,6 @@ In Keycloak 26.x, management-permissions APIs used by group/user fine-grained te
 - `setConfig(overrides)`
 - `getToken()`
 - `stop()`
-- ~~`login(credentials)`~~ **DEPRECATED** - moved to keycloak-express-middleware
-- ~~`generateAuthorizationUrl(options)`~~ **DEPRECATED** - moved to keycloak-express-middleware
-- ~~`loginPKCE(credentials)`~~ **DEPRECATED** - moved to keycloak-express-middleware
-- ~~`auth(credentials)`~~ **DEPRECATED** - moved to keycloak-express-middleware
-
-**Note:** OIDC authentication methods have been deprecated in v6.0.0. Use [`keycloak-express-middleware`](https://github.com/smartenv-crs4/keycloak-express-middleware) for user authentication flows.
 
 Configured handler namespaces:
 
@@ -104,7 +124,7 @@ All documentation is centralized under `docs/`.
 
 ### 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
 
 ### API Reference
 
@@ -129,13 +149,13 @@ All documentation is centralized under `docs/`.
 
 - [Architecture and Runtime](docs/architecture.md)
 - [Keycloak Setup and Feature Flags](docs/keycloak-setup.md)
-- [Testing Guide](docs/testing.md)
-- [Test Configuration](docs/test-configuration.md)
+- [Testing Guide](docs/testing.md) — setup, configuration, commands, and test architecture
 - [Deployment (Local/Remote, HTTP/HTTPS)](docs/deployment.md)
 
 ## Testing
 
 ```bash
+npm run setup-keycloak
 npm test
 ```
 
@@ -145,6 +165,8 @@ Or test workspace only:
 npm --prefix test test
 ```
 
+`npm run setup-keycloak` is an interactive helper that can start Keycloak via Docker Compose (local/remote, HTTP/HTTPS) and update the test `baseUrl` in config.
+
 The suite runs against a real Keycloak instance and provisions a shared test realm during setup.
 
 ## Repository Structure
@@ -163,14 +185,13 @@ docs/               # Centralized documentation
 
 ## Versioning and Compatibility
 
-- Package version: `6.0.2`
+- Package version: `6.0.3`
 - Keycloak Admin client dependency: `@keycloak/keycloak-admin-client`
 - Main compatibility target: Keycloak 25/26
 
 ### Breaking Changes in v6.0.0
 
-OIDC authentication methods (`login()`, `loginPKCE()`, `generateAuthorizationUrl()`, `auth()`) are now deprecated.
-These methods will be removed in v7.0.0. Migrate to `keycloak-express-middleware` for user authentication.
+See OIDC Deprecation Notice.
 
 ## License
 

package/docs/api/configuration.md

@@ -7,7 +7,7 @@ Core API methods for initializing and managing the Keycloak Admin Client connect
 - [configure()](#configure)
 - [setConfig()](#setconfig)
 - [getToken()](#gettoken)
-- [Deprecated OIDC Methods](#deprecated-oidc-methods)
+- [OIDC Deprecation Notice](#oidc-deprecation-notice)
 - [stop()](#stop)
 
 ---
@@ -243,23 +243,13 @@ const response = await axios.get('https://keycloak.example.com/admin/realms/mast
 
 ---
 
-## Deprecated OIDC Methods
+## OIDC Deprecation Notice
 
-The following methods are still available only for backward compatibility and are deprecated since v6.0.0:
+OIDC authentication helpers are deprecated and retained only for backward compatibility.
 
-- `auth(credentials)`
-- `login(credentials)`
-- `generateAuthorizationUrl(options)`
-- `loginPKCE(credentials)`
-
-These methods will be removed in v7.0.0.
-
-For all user authentication flows (including Authorization Code + PKCE), use keycloak-express-middleware:
-
-- https://github.com/smartenv-crs4/keycloak-express-middleware
-
-Migration notes:
+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)
 
 ---
@@ -338,7 +328,7 @@ process.on('SIGTERM', () => {
 ### Notes
 
 - Always call `stop()` before application exit to prevent dangling timers.
-- After calling `stop()`, you can call `configure()` or `auth()` again to restart.
+- After calling `stop()`, you can call `configure()` again to restart.
 - Not calling `stop()` may prevent Node.js process from exiting cleanly.
 
 ---

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,61 +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`
-
-## Recommended Local Setup
-
-1. Keep non-sensitive defaults in `default.json`.
-2. Put secrets in `secrets.json`.
-3. Override per-machine host/ports in `local.json`.
-
-Example `local.json` for local Docker Keycloak:
-
-```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`.
-- 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,10 +1,21 @@
 # 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.
 
-## Quick Start (End-to-End)
+## 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)
 
-Use these steps to create the test environment, start it, and run the suite.
+---
+
+## Quick Start (End-to-End)
 
 ### 1) Install dependencies
 
@@ -15,7 +26,7 @@ npm --prefix test install
 
 ### 2) Prepare local test config
 
-Create local override files from examples:
+Create local override files from the provided examples:
 
 ```bash
 cp test/config/local.json.example test/config/local.json
@@ -27,7 +38,7 @@ 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, a common value is:
+For local Docker on default HTTP port:
 
 ```json
 {
@@ -40,7 +51,54 @@ For local Docker on default HTTP port, a common value is:
 }
 ```
 
-### 3) Start Keycloak for tests
+### 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
@@ -65,12 +123,78 @@ npm test
 docker compose -f test/docker-keycloak/docker-compose.yml down
 ```
 
-If you want to remove container volumes too:
+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
 
 The suite uses a shared realm strategy:
@@ -81,6 +205,8 @@ The suite uses a shared realm strategy:
 
 This improves speed and keeps the environment deterministic.
 
+---
+
 ## Current Test Layout
 
 ```text
@@ -95,9 +221,14 @@ test/
     testConfig.js
 ```
 
+---
+
 ## Commands
 
 ```bash
+# interactive provisioning helper (starts docker and sets baseUrl)
+npm run setup-keycloak
+
 # full suite
 npm test
 
@@ -109,6 +240,24 @@ 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:
@@ -124,6 +273,8 @@ 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:
@@ -138,6 +289,8 @@ The cert directory must contain:
 
 The same bootstrap also performs cleanup in global teardown by deleting the shared test realm.
 
+---
+
 ## Writing New Tests
 
 - Import config from `test/testConfig.js`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keycloak-api-manager",
-  "version": "6.0.3",
+  "version": "6.0.4",
   "description": "Enhanced Node.js wrapper for Keycloak Admin REST API. Professional alternative to @keycloak/keycloak-admin-client with advanced features, bug fixes, automatic token refresh, Organizations API support, fine-grained permissions, and comprehensive resource management. Battle-tested with 113+ integration tests.",
   "main": "index.js",
   "scripts": {