keycloak-api-manager 5.0.7 → 6.0.1

package/OIDC_MIGRATION_PLAN.md

@@ -0,0 +1,294 @@
+# OIDC Methods Migration Plan - keycloak-api-manager
+
+## 🚀 Current Status: v6.0.0 - MIGRATION RELEASED
+
+✅ **OIDC Methods Deprecated:** All OIDC authentication methods are now marked `@deprecated` in v6.0.0.
+
+✅ **keycloak-express-middleware v6.1.0 Released:** OIDC methods now available in middleware package with full test coverage.
+
+📅 **Removal Timeline:**
+- **v6.0.0** (NOW) - Methods work but marked @deprecated
+- **v7.0.0** (FUTURE) - Methods will be permanently removed
+
+---
+
+## Overview
+
+L'architettura prevede una **migrazione pianificata** dei metodi OIDC (`auth()`, `login()`, `loginPKCE()`) da `keycloak-api-manager` a `keycloak-express-middleware`.
+
+## Current State (v5.0.8)
+
+**In keycloak-api-manager:**
+- ✅ `auth(credentials)` - OIDC token endpoint wrapper
+- ✅ `login(credentials)` - Generic token grant helper
+- ✅ `generateAuthorizationUrl(options)` - PKCE URL generator
+- ✅ `loginPKCE(credentials)` - PKCE token exchange
+
+## Current State (v6.0.0) - NOW
+
+**Status Changes in keycloak-api-manager:**
+- ⚠️ `auth(credentials)` - Marked @deprecated
+- ⚠️ `login(credentials)` - Marked @deprecated
+- ⚠️ `generateAuthorizationUrl(options)` - Marked @deprecated
+- ⚠️ `loginPKCE(credentials)` - Marked @deprecated
+
+✅ Methods **still work** but show deprecation warnings in JSDoc and IDE.
+
+**Status in keycloak-express-middleware v6.1.0:**
+- ✅ `generateAuthorizationUrl(options)` - Fully implemented & tested
+- ✅ `login(credentials)` - Fully implemented & tested
+- ✅ `loginPKCE(credentials)` - Fully implemented & tested
+- ✅ All 21 tests passing
+
+## Why This Migration?
+
+### Separation of Concerns
+
+```
+keycloak-api-manager (Admin API Management)
+├── configure()          ← Admin setup
+├── Users.find()        ← Admin operations
+├── Realms.create()     ← Admin operations
+└── ❌ login() / auth()   ← Should NOT be here!
+
+keycloak-express-middleware (User Authentication)
+├── protectMiddleware()  ← Route protection
+├── Express integration  ← Session, cookies
+└── ✅ generateAuthorizationUrl()  ← Belongs here
+└── ✅ login()           ← Belongs here
+└── ✅ loginPKCE()       ← Belongs here
+```
+
+### Why Middleware is Better
+
+1. **Natural Context:** Express app has sessions, cookies, redirects
+2. **No Admin Context:** Users don't need admin API management
+3. **Tighter Integration:** Works with middleware ecosystem
+4. **Cleaner Namespaces:** Each package has clear responsibilities
+
+## Migration Timeline
+
+### Phase 1: ✅ DONE (Now)
+- [x] Create ready-to-integrate files in middleware (`oidc-methods.js`)
+- [x] Write comprehensive tests (21 tests, all passing)
+- [x] Document integration guide
+- [x] Commit to middleware repo
+- [x] Integrate OIDC methods into keycloak-express-middleware v6.1.0
+- [x] Release keycloak-express-middleware v6.1.0 to npm
+
+**Status:** ✅ COMPLETE & RELEASED
+
+### Phase 2: ✅ DONE (Done)
+- [x] Mark methods as @deprecated in keycloak-api-manager index.js
+- [x] Update README with deprecation notices
+- [x] Update API documentation with deprecation notices
+- [x] Add migration guide in PKCE-Login-Flow docs
+- [x] Release keycloak-api-manager v6.0.0
+
+**Status:** ✅ COMPLETE - v6.0.0 released with @deprecated warnings
+
+### Phase 3: TODO (Future - v7.0.0)
+- [ ] Remove OIDC methods from keycloak-api-manager
+- [ ] Release keycloak-api-manager v7.0.0 (breaking change)
+- [ ] Update all documentation to reference keycloak-express-middleware only
+
+**Timeline:** TBD based on user feedback and adoption
+
+---
+
+## What You Need to Know
+
+### For Current Users (v5.0.8 or earlier)
+
+**Action Required:** Migrate to keycloak-express-middleware before v7.0.0.
+
+**Timeline:** v6.0.0 is deprecated (warnings only), v7.0.0 will remove methods entirely.
+
+**Steps:**
+1. Install keycloak-express-middleware v6.1.0+
+2. Replace method calls (see examples below)
+3. Test thoroughly
+4. Deploy before v7.0.0 is released
+
+### For New Projects
+
+**Action Required:** Do NOT use OIDC methods from keycloak-api-manager.
+
+**Recommendation:** Use keycloak-express-middleware v6.1.0+ for all user authentication.
+
+---
+
+## NPM Packages
+
+### keycloak-api-manager
+
+| Version | OIDC Methods | Status |
+|---------|------------|--------|
+| v5.0.8 | Supported | Legacy (should migrate) |
+| v6.0.0 | Deprecated | Current (shows warnings) |
+| v7.0.0 | Removed | Future (no OIDC methods) |
+
+**NPM:** https://www.npmjs.com/package/keycloak-api-manager
+
+### keycloak-express-middleware
+
+| Version | OIDC Methods | Status |
+|---------|------------|--------|
+| < 6.1.0 | Not available | Legacy |
+| v6.1.0+ | Available | Current - RECOMMENDED |
+
+**NPM:** https://www.npmjs.com/package/keycloak-express-middleware
+
+**GitHub:** https://github.com/smartenv-crs4/keycloak-express-middleware
+
+---
+
+### `auth(credentials)` - Generic OIDC Token Grant (DEPRECATED)
+
+```javascript
+// ⚠️ DEPRECATED - Don't use in new code
+const token = await KeycloakManager.auth({
+  grant_type: 'password',
+  username: 'user',
+  password: 'pass'
+});
+```
+
+**Migration Path:**
+```javascript
+// ✅ NEW - Use keycloak-express-middleware instead
+const token = await keycloakMiddleware.login({
+  grant_type: 'password',
+  username: 'user',
+  password: 'pass'
+});
+```
+
+---
+
+### `login(credentials)` - Preferred Alias (DEPRECATED)
+
+```javascript
+// ⚠️ DEPRECATED - Don't use in new code
+const token = await KeycloakManager.login({
+  grant_type: 'client_credentials'
+});
+```
+
+**Migration Path:**
+```javascript
+// ✅ NEW - Use keycloak-express-middleware instead
+const token = await keycloakMiddleware.login({
+  grant_type: 'client_credentials'
+});
+```
+
+---
+
+### `generateAuthorizationUrl(options)` - PKCE URL Generator (DEPRECATED)
+
+```javascript
+// ⚠️ DEPRECATED - Don't use in new code
+const pkceFlow = KeycloakManager.generateAuthorizationUrl({
+  redirect_uri: 'https://app/callback'
+});
+```
+
+**Migration Path:**
+```javascript
+// ✅ NEW - Use keycloak-express-middleware instead
+const pkceFlow = keycloakMiddleware.generateAuthorizationUrl({
+  redirect_uri: 'https://app/callback'
+});
+```
+
+---
+
+### `loginPKCE(credentials)` - PKCE Token Exchange (DEPRECATED)
+
+```javascript
+// ⚠️ DEPRECATED - Don't use in new code
+const token = await KeycloakManager.loginPKCE({
+  code: req.query.code,
+  redirect_uri: 'https://app/callback',
+  code_verifier: req.session.verifier
+});
+```
+
+**Migration Path:**
+```javascript
+// ✅ NEW - Use keycloak-express-middleware instead
+const token = await keycloakMiddleware.loginPKCE({
+  code: req.query.code,
+  redirect_uri: 'https://app/callback',
+  code_verifier: req.session.verifier
+});
+```
+
+**Migration Path:**
+```javascript
+// Move to middleware
+const token = await keycloakMiddleware.loginPKCE({
+  code: req.query.code,
+  redirect_uri: 'https://app/callback',
+  code_verifier: req.session.verifier
+});
+```
+
+---
+
+## What Stays in keycloak-api-manager
+
+✅ **These remain unchanged forever:**
+- `configure(credentials)` - Admin authentication
+- `setConfig(overrides)` - Configuration management
+- `getToken()` - Get current admin token
+- `stop()` - Cleanup
+- **All handlers:** `users`, `realms`, `clients`, `groups`, `roles`, etc.
+
+The package remains the **dedicated Admin API Manager** - exactly what it should be.
+
+## Migration Guide for Users (TBD)
+
+When ready, we'll publish:
+
+```markdown
+# Migrating OIDC Methods from keycloak-api-manager to keycloak-express-middleware
+
+## Version Support
+
+| Method | deprecated | removed | alternative |
+|--------|-----------|---------|-------------|
+| `auth()` | v6.0.0 | v7.0.0 | middleware.login() |
+| `login()` | v6.0.0 | v7.0.0 | middleware.login() |
+| `generateAuthorizationUrl()` | v6.0.0 | v7.0.0 | middleware.generateAuthorizationUrl() |
+| `loginPKCE()` | v6.0.0 | v7.0.0 | middleware.loginPKCE() |
+
+## Migration Steps
+
+1. Install/update middleware
+2. Replace method calls
+3. Update imports
+4. Test
+```
+
+## Next Actions
+
+### You Should Do:
+1. Review `keycloak-express-middleware/OIDC_INTEGRATION_GUIDE.md`
+2. Decide if you want to integrate manually or have me automate it
+3. Once middleware is ready, let me know
+
+### I Will Do (When You Say):
+1. Integrate methods into middleware `index.js`
+2. Release `keycloak-express-middleware v6.1.0`
+3. Deprecate in `keycloak-api-manager v6.0.0`
+4. Create migration guide
+5. Update all documentation
+
+## Questions?
+
+- How should we handle the transition period?
+- Do we support both packages simultaneously?
+- Timeline for full migration?
+- Any concerns about the approach?

package/README.md

@@ -25,6 +25,12 @@ 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.
+
 ## Quick Start
 
 ```js
@@ -48,6 +54,8 @@ console.log(users.length);
 KeycloakManager.stop();
 ```
 
+> **💡 Tip:** For user authentication (login with credentials, PKCE flow, token exchange), use [`keycloak-express-middleware`](https://github.com/smartenv-crs4/keycloak-express-middleware) instead. See [PKCE Login Flow Guide](docs/guides/PKCE-Login-Flow.md#-migration-to-keycloak-express-middleware-recommended) for migration examples.
+
 ## Keycloak Feature Flags
 
 For full API coverage in this package (especially Organizations, Client Policies, User Profile, Group permissions), run Keycloak with:
@@ -65,16 +73,13 @@ In Keycloak 26.x, management-permissions APIs used by group/user fine-grained te
 - `configure(credentials)`
 - `setConfig(overrides)`
 - `getToken()`
-- `login(credentials)`
-- `loginPKCE(credentials)`
-- `auth(credentials)`
 - `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
 
-`login(credentials)` is the preferred OIDC token endpoint helper for login/token grant flows (user/client).
-
-`loginPKCE(credentials)` is a specialized helper for Authorization Code + PKCE token exchange.
-
-`auth(credentials)` is kept as backward-compatible alias and does not replace the internal admin session configured by `configure()`.
+**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:
 
@@ -158,10 +163,15 @@ docs/               # Centralized documentation
 
 ## Versioning and Compatibility
 
-- Package version: `5.0.1`
+- Package version: `6.0.0`
 - 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.
+
 ## License
 
 MIT

package/docs/api/configuration.md

@@ -8,6 +8,7 @@ Core API methods for initializing and managing the Keycloak Admin Client connect
 - [setConfig()](#setconfig)
 - [getToken()](#gettoken)
 - [login()](#login)
+- [generateAuthorizationUrl()](#generateauthorizationurl)
 - [loginPKCE()](#loginpkce)
 - [auth()](#auth)
 - [stop()](#stop)
@@ -238,9 +239,15 @@ const response = await axios.get('https://keycloak.example.com/admin/realms/mast
 
 ## auth()
 
-Backward-compatible alias of `login()`.
+⚠️ **DEPRECATED (v6.0.0)** - Use [`keycloak-express-middleware.login()`](https://github.com/smartenv-crs4/keycloak-express-middleware) instead.
 
-Use `login()` in new code for clearer intent.
+This method will be removed in v7.0.0. For user authentication flows, use `keycloak-express-middleware` v6.1.0+.
+
+See: [Migration Guide](../guides/PKCE-Login-Flow.md#-migration-to-keycloak-express-middleware-recommended)
+
+---
+
+**Legacy Note:** Backward-compatible alias of `login()`. Use `login()` instead (also deprecated).
 
 **Syntax:**
 ```javascript
@@ -255,6 +262,14 @@ await KeycloakManager.auth(credentials)
 
 ## login()
 
+⚠️ **DEPRECATED (v6.0.0)** - Use [`keycloak-express-middleware.login()`](https://github.com/smartenv-crs4/keycloak-express-middleware) instead.
+
+This method will be removed in v7.0.0. For user authentication flows, use `keycloak-express-middleware` v6.1.0+.
+
+See: [Migration Guide](../guides/PKCE-Login-Flow.md#-migration-to-keycloak-express-middleware-recommended)
+
+---
+
 Request tokens from Keycloak via the OIDC token endpoint.
 
 This method is intended for application-level login/token flows (for users, service clients, or third-party integrations) using this package as a wrapper.
@@ -348,13 +363,118 @@ console.log(refreshed.access_token);
 
 ---
 
+## generateAuthorizationUrl()
+
+⚠️ **DEPRECATED (v6.0.0)** - Use [`keycloak-express-middleware.generateAuthorizationUrl()`](https://github.com/smartenv-crs4/keycloak-express-middleware) instead.
+
+This method will be removed in v7.0.0. For PKCE authentication flows, use `keycloak-express-middleware` v6.1.0+.
+
+See: [Migration Guide](../guides/PKCE-Login-Flow.md#-migration-to-keycloak-express-middleware-recommended)
+
+---
+
+Generate OAuth2 Authorization Code + PKCE flow initialization. Returns a ready-to-use authorization URL and PKCE pair for server-side session storage.
+
+This helper simplifies the first step of PKCE login: generating the authorization URL with PKCE challenge and state parameter.
+
+**Syntax:**
+```javascript
+const pkceFlow = KeycloakManager.generateAuthorizationUrl(options)
+```
+
+### Parameters
+
+#### options (Object) ⚠️ Required
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `redirect_uri` | string | ⚠️ Yes* | Redirect URI where user returns after login |
+| `redirectUri` | string | ⚠️ Yes* | CamelCase alias of `redirect_uri` |
+| `scope` | string | 📋 Optional | Space-separated scopes (default: `'openid profile email'`) |
+| `state` | string | 📋 Optional | Custom state value (auto-generated if not provided) |
+
+`*` required with either snake_case or camelCase form.
+
+### Returns
+
+**Object** - PKCE flow initialization data:
+
+```javascript
+{
+  authUrl: 'https://keycloak.example.com/realms/my-realm/protocol/openid-connect/auth?...',
+  state: 'random_state_string',
+  codeVerifier: 'random_code_verifier_string'
+}
+```
+
+- `authUrl`: Ready-to-use authorization URL to redirect user to
+- `state`: CSRF token to validate in callback (store in session)
+- `codeVerifier`: PKCE proof to exchange for code in callback (store in session, **never expose to client**)
+
+### Example
+
+```javascript
+// Step 1: Generate authorization URL
+app.get('/auth/login', (req, res) => {
+  const pkceFlow = KeycloakManager.generateAuthorizationUrl({
+    redirect_uri: `${process.env.APP_URL}/auth/callback`,
+    scope: 'openid profile email'
+  });
+  
+  // Store in session server-side
+  req.session.pkce_state = pkceFlow.state;
+  req.session.pkce_verifier = pkceFlow.codeVerifier;
+  
+  // Redirect user to Keycloak
+  res.redirect(pkceFlow.authUrl);
+});
+
+// Step 2: In callback, recover verifier and exchange code
+app.get('/auth/callback', async (req, res) => {
+  const { code, state } = req.query;
+  
+  // Validate state
+  if (state !== req.session.pkce_state) {
+    return res.status(400).send('CSRF attack detected');
+  }
+  
+  // Exchange code for token
+  const tokens = await KeycloakManager.loginPKCE({
+    code,
+    redirect_uri: `${process.env.APP_URL}/auth/callback`,
+    code_verifier: req.session.pkce_verifier
+  });
+  
+  // Use tokens...
+});
+```
+
+### Notes
+
+- `generateAuthorizationUrl()` does **not** call Keycloak; it generates URLs and PKCE values locally.
+- `state` and `codeVerifier` must be stored **server-side only** in session storage, never in cookies or local storage.
+- `codeVerifier` must be kept secret and never exposed to the browser.
+- `state` provides CSRF protection and must be validated in the callback.
+- Uses cryptographically secure random generation for `codeVerifier` and `state`.
+- Code challenge is SHA256-hashed (S256 method), not plain text.
+
+---
+
 ## loginPKCE()
 
+⚠️ **DEPRECATED (v6.0.0)** - Use [`keycloak-express-middleware.loginPKCE()`](https://github.com/smartenv-crs4/keycloak-express-middleware) instead.
+
+This method will be removed in v7.0.0. For PKCE authentication flows, use `keycloak-express-middleware` v6.1.0+.
+
+See: [Migration Guide](../guides/PKCE-Login-Flow.md#-migration-to-keycloak-express-middleware-recommended)
+
+---
+
 Perform Authorization Code + PKCE token exchange.
 
 This helper is intended for the callback step after user login on Keycloak, where your backend receives an authorization `code` and exchanges it with `code_verifier`.
 
-> **📖 For a complete step-by-step guide on implementing PKCE flow in your application, see [PKCE Login Flow Guide](../guides/PKCE-Login-Flow.md)**
+> **📖 For a complete step-by-step guide on implementing PKCE flow in your application, see [PKCE Login Flow Guide](../guides/PKCE-Login-Flow.md#-migration-to-keycloak-express-middleware-recommended)**
 
 **Syntax:**
 ```javascript

package/docs/api-reference.md

@@ -80,6 +80,7 @@ KeycloakManager.stop();
 | `setConfig()` | Runtime configuration | Core |
 | `getToken()` | Get current access token | Core |
 | `login()` | Preferred OIDC token grant/login endpoint wrapper | Core |
+| `generateAuthorizationUrl()` | Generate PKCE authorization URL and verifier pair | Core |
 | `loginPKCE()` | Authorization Code + PKCE token exchange helper | Core |
 | `auth()` | Backward-compatible alias of `login()` | Core |
 | `stop()` | Stop token refresh timer | Core |

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

@@ -1,5 +1,13 @@
 # PKCE Login Flow Guide
 
+⚠️ **DEPRECATION NOTICE (v6.0.0):** This guide describes PKCE implementation using **deprecated methods** in keycloak-api-manager. 
+
+**👉 NEW APPROACH (Recommended):** For user authentication flows, use [`keycloak-express-middleware v6.1.0+`](https://github.com/smartenv-crs4/keycloak-express-middleware) instead. The middleware package provides a more integrated and Express-native implementation of PKCE flows.
+
+**See:** Migration instructions at the end of this guide.
+
+---
+
 This guide walks you through implementing OAuth2 Authorization Code + PKCE flow in your application using Keycloak and the keycloak-api-manager library.
 
 ## Overview
@@ -72,98 +80,51 @@ PKCE (Proof Key for Code Exchange) is the modern, secure way for browser-based a
 
 ## Step-by-Step Implementation
 
-### Step 1: Generate PKCE Pair
+### Step 1: Generate Authorization URL
 
-When the user clicks "Login", your backend generates a PKCE pair and stores it securely:
+When the user clicks "Login", use `generateAuthorizationUrl()` from keycloak-api-manager to generate the PKCE pair and authorization URL:
 
 ```javascript
-const crypto = require('crypto');
-
-function base64url(buf) {
-  return buf
-    .toString('base64')
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_')
-    .replace(/=/g, '');
-}
+const pkceFlow = KeycloakManager.generateAuthorizationUrl({
+  redirect_uri: `${process.env.APP_URL}/auth/callback`,
+  scope: 'openid profile email' // optional, defaults to 'openid profile email'
+});
 
-function createPkcePair() {
-  // Generate code_verifier (random 128-char string)
-  const code_verifier = base64url(crypto.randomBytes(96));
-  
-  // Generate code_challenge (SHA256 hash of verifier)
-  const code_challenge = base64url(
-    crypto.createHash('sha256').update(code_verifier).digest()
-  );
-  
-  // Generate state (CSRF protection)
-  const state = base64url(crypto.randomBytes(32));
-  
-  return { code_verifier, code_challenge, state };
-}
+// Result contains:
+// {
+//   authUrl: 'https://keycloak.example.com/realms/my-realm/protocol/openid-connect/auth?...',
+//   state: 'random_state_value',
+//   codeVerifier: 'random_verifier_value'
+// }
 ```
 
-**Why this works:**
-- `code_verifier`: A random, unguessable string
-- `code_challenge`: The SHA256 hash of the verifier, sent to Keycloak during login
-- `state`: A random token to prevent CSRF attacks; Keycloak will return it unchanged
-
-### Step 2: Redirect to Keycloak Authorization Endpoint
-
-Store the PKCE pair in the session, then redirect the user to Keycloak:
+Store the `state` and `codeVerifier` in your session, then redirect the user to the authorization URL:
 
 ```javascript
-const express = require('express');
-const session = require('express-session');
-const KeycloakManager = require('keycloak-api-manager');
-
-const app = express();
-
-// Session configuration (store verifier securely server-side)
-app.use(session({
-  secret: 'your-secret-key',
-  resave: false,
-  saveUninitialized: true,
-  cookie: { httpOnly: true, secure: true } // secure: true in production (HTTPS only)
-}));
-
-// 1. User clicks "Login" button
 app.get('/auth/login', (req, res) => {
-  const { code_verifier, code_challenge, state } = createPkcePair();
-  
-  // Store verifier and state in session (server-side only!)
-  req.session.pkce_verifier = code_verifier;
-  req.session.pkce_state = state;
-  
-  // Build Keycloak authorization URL
-  const keycloakAuthUrl = `${process.env.KEYCLOAK_URL}/auth/realms/${process.env.KEYCLOAK_REALM}/protocol/openid-connect/auth`;
-  const authUrl = new URL(keycloakAuthUrl);
+  const pkceFlow = KeycloakManager.generateAuthorizationUrl({
+    redirect_uri: `${process.env.APP_URL}/auth/callback`
+  });
   
-  authUrl.searchParams.append('client_id', process.env.KEYCLOAK_CLIENT_ID);
-  authUrl.searchParams.append('redirect_uri', `${process.env.APP_URL}/auth/callback`);
-  authUrl.searchParams.append('response_type', 'code');
-  authUrl.searchParams.append('scope', 'openid profile email');
-  authUrl.searchParams.append('code_challenge', code_challenge);
-  authUrl.searchParams.append('code_challenge_method', 'S256'); // S256 = SHA256
-  authUrl.searchParams.append('state', state);
+  // Store state and verifier in session for callback validation
+  req.session.pkce_state = pkceFlow.state;
+  req.session.pkce_verifier = pkceFlow.codeVerifier;
   
-  // Redirect user to Keycloak login page
-  res.redirect(authUrl.toString());
+  // Redirect user to Keycloak login
+  res.redirect(pkceFlow.authUrl);
 });
 ```
 
-**What happens:**
-- User is redirected to Keycloak
-- They see the login page
-- They enter their username/password
-- On successful auth, Keycloak redirects back to your `/auth/callback` endpoint with `code` and `state`
-
-### Step 3: Exchange Authorization Code for Token
+**Why this works:**
+- `generateAuthorizationUrl()` handles all PKCE complexity internally
+- Returns a ready-to-use authorization URL
+- State parameter provides CSRF protection
+- Code verifier is stored server-side (never exposed to client)
 
-When Keycloak redirects back with the authorization code, you exchange it for an access token:
+When Keycloak redirects back with the authorization code, you exchange it for an access token using `loginPKCE()`:
 
 ```javascript
-// 2. Keycloak redirects back with authorization code
+// User callback after Keycloak login
 app.get('/auth/callback', async (req, res) => {
   try {
     const { code, state, error } = req.query;
@@ -180,18 +141,15 @@ app.get('/auth/callback', async (req, res) => {
     
     // 3. Retrieve stored verifier from session
     const code_verifier = req.session.pkce_verifier;
-    
     if (!code_verifier) {
       return res.status(400).send('PKCE verifier not found in session');
     }
     
-    // 4. Exchange code for token using loginPKCE()
+    // 4. Exchange code for token using keycloak-api-manager
     const tokenResponse = await KeycloakManager.loginPKCE({
       code,
       redirect_uri: `${process.env.APP_URL}/auth/callback`,
-      code_verifier,
-      client_id: process.env.KEYCLOAK_CLIENT_ID,
-      client_secret: process.env.KEYCLOAK_CLIENT_SECRET
+      code_verifier
     });
     
     // 5. Set secure HTTPOnly cookie with access token
@@ -232,35 +190,6 @@ app.get('/auth/callback', async (req, res) => {
 - ✅ Store token in HttpOnly cookie (prevents XSS theft)
 - ✅ Clear sensitive session data
 
-### Step 4: Use the Access Token
-
-Now the user has an access token in a secure cookie. Use it to access protected resources:
-
-```javascript
-// Middleware to verify access token
-app.use((req, res, next) => {
-  const token = req.cookies.access_token;
-  
-  if (!token) {
-    return res.status(401).send('Not authenticated');
-  }
-  
-  // Verify and decode the token
-  try {
-    const decoded = jwt.verify(token, process.env.JWT_PUBLIC_KEY);
-    req.user = decoded; // User data available in request
-    next();
-  } catch (error) {
-    return res.status(401).send('Invalid token');
-  }
-});
-
-// Protected route
-app.get('/dashboard', (req, res) => {
-  res.send(`Welcome, ${req.user.preferred_username}!`);
-});
-```
-
 ## Complete Working Example
 
 Here's a complete Express.js application with PKCE flow:
@@ -268,7 +197,6 @@ Here's a complete Express.js application with PKCE flow:
 ```javascript
 const express = require('express');
 const session = require('express-session');
-const crypto = require('crypto');
 const jwt = require('jsonwebtoken');
 const cookieParser = require('cookie-parser');
 const KeycloakManager = require('keycloak-api-manager');
@@ -287,55 +215,34 @@ app.use(session({
 
 // Initialize Keycloak Manager
 KeycloakManager.configure({
+  baseUrl: process.env.KEYCLOAK_URL,
   realmName: process.env.KEYCLOAK_REALM,
   clientId: process.env.KEYCLOAK_CLIENT_ID,
   clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
-  keycloakUrl: process.env.KEYCLOAK_URL
+  grantType: 'client_credentials'
 });
 
-// Helper functions
-function base64url(buf) {
-  return buf
-    .toString('base64')
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_')
-    .replace(/=/g, '');
-}
-
-function createPkcePair() {
-  const code_verifier = base64url(crypto.randomBytes(96));
-  const code_challenge = base64url(
-    crypto.createHash('sha256').update(code_verifier).digest()
-  );
-  const state = base64url(crypto.randomBytes(32));
-  return { code_verifier, code_challenge, state };
-}
-
 // Routes
 app.get('/auth/login', (req, res) => {
-  const { code_verifier, code_challenge, state } = createPkcePair();
-  
-  req.session.pkce_verifier = code_verifier;
-  req.session.pkce_state = state;
-  
-  const keycloakAuthUrl = `${process.env.KEYCLOAK_URL}/auth/realms/${process.env.KEYCLOAK_REALM}/protocol/openid-connect/auth`;
-  const authUrl = new URL(keycloakAuthUrl);
+  // Generate PKCE pair and authorization URL
+  const pkceFlow = KeycloakManager.generateAuthorizationUrl({
+    redirect_uri: `${process.env.APP_URL}/auth/callback`,
+    scope: 'openid profile email'
+  });
   
-  authUrl.searchParams.append('client_id', process.env.KEYCLOAK_CLIENT_ID);
-  authUrl.searchParams.append('redirect_uri', `${process.env.APP_URL}/auth/callback`);
-  authUrl.searchParams.append('response_type', 'code');
-  authUrl.searchParams.append('scope', 'openid profile email');
-  authUrl.searchParams.append('code_challenge', code_challenge);
-  authUrl.searchParams.append('code_challenge_method', 'S256');
-  authUrl.searchParams.append('state', state);
+  // Store state and verifier in session (server-side only!)
+  req.session.pkce_state = pkceFlow.state;
+  req.session.pkce_verifier = pkceFlow.codeVerifier;
   
-  res.redirect(authUrl.toString());
+  // Redirect user to Keycloak login
+  res.redirect(pkceFlow.authUrl);
 });
 
 app.get('/auth/callback', async (req, res) => {
   try {
     const { code, state, error } = req.query;
     
+    // Validate state (CSRF protection)
     if (state !== req.session.pkce_state) {
       return res.status(400).send('Invalid state parameter');
     }
@@ -349,13 +256,11 @@ app.get('/auth/callback', async (req, res) => {
       return res.status(400).send('PKCE verifier not found');
     }
     
-    // Exchange code for token
+    // Exchange code for token (client_id + client_secret from configure())
     const tokenResponse = await KeycloakManager.loginPKCE({
       code,
       redirect_uri: `${process.env.APP_URL}/auth/callback`,
-      code_verifier,
-      client_id: process.env.KEYCLOAK_CLIENT_ID,
-      client_secret: process.env.KEYCLOAK_CLIENT_SECRET
+      code_verifier
     });
     
     // Set secure cookies
@@ -373,6 +278,7 @@ app.get('/auth/callback', async (req, res) => {
       maxAge: 7 * 24 * 60 * 60 * 1000
     });
     
+    // Clear sensitive data
     delete req.session.pkce_verifier;
     delete req.session.pkce_state;
     
@@ -608,3 +514,154 @@ function verifyToken(token) {
 - [login() API Reference](../api/configuration.md#login)
 - [OAuth2 PKCE Specification](https://tools.ietf.org/html/rfc7636)
 - [Keycloak Authorization Code Flow](https://www.keycloak.org/docs/latest/server_admin/#_oidc)
+
+---
+
+## 🚀 Migration to keycloak-express-middleware (Recommended)
+
+The methods described in this guide (`generateAuthorizationUrl()`, `loginPKCE()`, `login()`) are **deprecated in v6.0.0** and will be removed in v7.0.0.
+
+### Why Migrate?
+
+`keycloak-express-middleware` provides:
+- ✅ Native Express integration (sessions, cookies, redirects)
+- ✅ Cleaner PKCE implementation focused on user authentication
+- ✅ Better separation of concerns (admin API vs user auth)
+- ✅ Tighter integration with Express middleware patterns
+
+### Migration Example
+
+**Old Code (keycloak-api-manager, DEPRECATED):**
+```javascript
+const KeycloakManager = require('keycloak-api-manager');
+
+// Configure admin API
+await KeycloakManager.configure({
+  baseUrl: 'https://keycloak:8443',
+  realmName: 'master',
+  clientId: 'admin-cli',
+  username: 'admin',
+  password: 'admin'
+});
+
+// Use OIDC methods (deprecated)
+const pkceFlow = KeycloakManager.generateAuthorizationUrl({
+  redirect_uri: 'http://localhost:3000/callback'
+});
+
+const tokens = await KeycloakManager.loginPKCE({
+  code: req.query.code,
+  redirect_uri: 'http://localhost:3000/callback',
+  code_verifier: req.session.pkce_verifier
+});
+```
+
+**New Code (keycloak-express-middleware, RECOMMENDED):**
+```javascript
+const KeycloakMiddleware = require('keycloak-express-middleware');
+
+// Configure middleware for user authentication
+const keycloakMiddleware = new KeycloakMiddleware({
+  baseUrl: 'https://keycloak:8443',
+  realmName: 'my-realm',
+  clientId: 'my-app',
+  clientSecret: 'my-app-secret'
+});
+
+// Use OIDC methods from middleware
+const pkceFlow = keycloakMiddleware.generateAuthorizationUrl({
+  redirect_uri: 'http://localhost:3000/callback'
+});
+
+const tokens = await keycloakMiddleware.loginPKCE({
+  code: req.query.code,
+  redirect_uri: 'http://localhost:3000/callback',
+  code_verifier: req.session.pkce_verifier
+});
+```
+
+### Step-by-Step Migration
+
+**1. Install keycloak-express-middleware:**
+```bash
+npm install keycloak-express-middleware@6.1.0
+npm uninstall keycloak-api-manager  # if no longer needed for admin operations
+```
+
+**2. Initialize middleware instead of manager:**
+```javascript
+// Replace this:
+// const KeycloakManager = require('keycloak-api-manager');
+// await KeycloakManager.configure({...});
+
+// With this:
+const KeycloakMiddleware = require('keycloak-express-middleware');
+const keycloakMiddleware = new KeycloakMiddleware({
+  baseUrl: process.env.KEYCLOAK_URL,
+  realmName: process.env.KEYCLOAK_REALM,
+  clientId: process.env.KEYCLOAK_CLIENT_ID,
+  clientSecret: process.env.KEYCLOAK_CLIENT_SECRET
+});
+```
+
+**3. Replace method calls:**
+```javascript
+// Old (keycloak-api-manager)
+const pkceFlow = KeycloakManager.generateAuthorizationUrl({...});
+const tokens = await KeycloakManager.loginPKCE({...});
+const newTokens = await KeycloakManager.login({...});
+
+// New (keycloak-express-middleware)
+const pkceFlow = keycloakMiddleware.generateAuthorizationUrl({...});
+const tokens = await keycloakMiddleware.loginPKCE({...});
+const newTokens = await keycloakMiddleware.login({...});
+```
+
+**4. Keep using keycloak-api-manager for admin operations (unchanged):**
+```javascript
+const KeycloakManager = require('keycloak-api-manager');
+
+await KeycloakManager.configure({
+  baseUrl: 'https://keycloak:8443',
+  realmName: 'master',
+  clientId: 'admin-cli',
+  username: 'admin',
+  password: 'admin'
+});
+
+// Admin operations still work the same
+const users = await KeycloakManager.users.find();
+const realms = await KeycloakManager.realms.find();
+```
+
+### API Comparison
+
+| Operation | keycloak-api-manager (Deprecated) | keycloak-express-middleware (Recommended) |
+|-----------|-----------------------------------|------------------------------------------|
+| Generate PKCE URL | `KeycloakManager.generateAuthorizationUrl()` | `middleware.generateAuthorizationUrl()` |
+| Login PKCE | `KeycloakManager.loginPKCE()` | `middleware.loginPKCE()` |
+| Token Grant | `KeycloakManager.login()` | `middleware.login()` |
+| Deprecated Alias | `KeycloakManager.auth()` | *(Use login()*)  |
+
+### Additional Resources
+
+- **Middleware Documentation:** https://github.com/smartenv-crs4/keycloak-express-middleware
+- **Migration Guide:** https://github.com/smartenv-crs4/keycloak-api-manager/blob/main/OIDC_MIGRATION_PLAN.md
+- **Middleware Integration Report:** See keycloak-express-middleware/DETAILED_INTEGRATION_REPORT.md
+
+### Deprecation Timeline
+
+| Version | Status | Notes |
+|---------|--------|-------|
+| v5.0.8  | Supported | Last version with working OIDC methods |
+| v6.0.0  | Deprecated | Methods work but marked @deprecated |
+| v7.0.0  | Removed | OIDC methods will be permanently removed |
+
+**Action Required:** Migrate to keycloak-express-middleware before v7.0.0 is released.
+
+## Related Documentation
+
+- [loginPKCE() API Reference](../api/configuration.md#loginpkce)
+- [login() API Reference](../api/configuration.md#login)
+- [OAuth2 PKCE Specification](https://tools.ietf.org/html/rfc7636)
+- [Keycloak Authorization Code Flow](https://www.keycloak.org/docs/latest/server_admin/#_oidc)

package/index.js

@@ -177,14 +177,50 @@ async function requestOidcToken(credentials = {}) {
     return payload;
 }
 
+/**
+ * @deprecated v6.0.0 - This method has been moved to keycloak-express-middleware.
+ * Use the middleware package for user authentication instead. See:
+ * https://github.com/smartenv-crs4/keycloak-express-middleware#oidc-authentication
+ * 
+ * This API manager is intended for Keycloak admin resource management only.
+ * For user authentication flows, import from keycloak-express-middleware.
+ * 
+ * @see {@link https://github.com/smartenv-crs4/keycloak-express-middleware|keycloak-express-middleware}
+ * @param {object} credentials - OIDC token request credentials
+ * @returns {Promise<object>} Token response containing access_token, refresh_token, etc.
+ */
 exports.auth = async function auth(credentials = {}) {
     return requestOidcToken(credentials);
 };
 
+/**
+ * @deprecated v6.0.0 - This method has been moved to keycloak-express-middleware.
+ * Use the middleware package for user authentication instead. See:
+ * https://github.com/smartenv-crs4/keycloak-express-middleware#oidc-authentication
+ * 
+ * This API manager is intended for Keycloak admin resource management only.
+ * For user authentication flows, import from keycloak-express-middleware.
+ * 
+ * @see {@link https://github.com/smartenv-crs4/keycloak-express-middleware|keycloak-express-middleware}
+ * @param {object} credentials - OIDC token request credentials (supports any OAuth2 grant type)
+ * @returns {Promise<object>} Token response containing access_token, refresh_token, etc.
+ */
 exports.login = async function login(credentials = {}) {
     return requestOidcToken(credentials);
 };
 
+/**
+ * @deprecated v6.0.0 - This method has been moved to keycloak-express-middleware.
+ * Use the middleware package for user authentication instead. See:
+ * https://github.com/smartenv-crs4/keycloak-express-middleware#oidc-pkce-flow
+ * 
+ * This API manager is intended for Keycloak admin resource management only.
+ * For user authentication flows, import from keycloak-express-middleware.
+ * 
+ * @see {@link https://github.com/smartenv-crs4/keycloak-express-middleware|keycloak-express-middleware}
+ * @param {object} credentials - PKCE authorization code exchange parameters
+ * @returns {Promise<object>} Token response containing access_token, refresh_token, etc.
+ */
 exports.loginPKCE = async function loginPKCE(credentials = {}) {
     const {
         code,
@@ -225,3 +261,75 @@ exports.loginPKCE = async function loginPKCE(credentials = {}) {
         ...rest
     });
 };
+
+/**
+ * @deprecated v6.0.0 - This method has been moved to keycloak-express-middleware.
+ * Use the middleware package for user authentication instead. See:
+ * https://github.com/smartenv-crs4/keycloak-express-middleware#generating-authorization-urls
+ * 
+ * This API manager is intended for Keycloak admin resource management only.
+ * For user authentication flows, import from keycloak-express-middleware.
+ * 
+ * @see {@link https://github.com/smartenv-crs4/keycloak-express-middleware|keycloak-express-middleware}
+ * @param {object} options - Authorization URL generation options
+ * @returns {object} Object with { authUrl, state, codeVerifier } for PKCE flow
+ */
+exports.generateAuthorizationUrl = function generateAuthorizationUrl(options = {}) {
+    assertConfigured();
+    
+    const { 
+        redirect_uri,
+        redirectUri,
+        scope,
+        state: customState
+    } = options;
+
+    const resolvedRedirectUri = redirect_uri || redirectUri;
+    if (!resolvedRedirectUri) {
+        throw new Error('generateAuthorizationUrl requires "redirect_uri" (or "redirectUri").');
+    }
+
+    const crypto = require('crypto');
+
+    // Helper to encode bytes to base64url
+    function base64url(buffer) {
+        return buffer
+            .toString('base64')
+            .replace(/\+/g, '-')
+            .replace(/\//g, '_')
+            .replace(/=/g, '');
+    }
+
+    // Generate PKCE pair
+    const codeVerifier = base64url(crypto.randomBytes(96));
+    const codeChallenge = base64url(
+        crypto.createHash('sha256').update(codeVerifier).digest()
+    );
+
+    // Generate or use provided state
+    const state = customState || base64url(crypto.randomBytes(32));
+
+    // Build authorization URL
+    const authUrl = new URL(
+        `${runtimeConfig.baseUrl}/realms/${runtimeConfig.realmName}/protocol/openid-connect/auth`
+    );
+    
+    authUrl.searchParams.append('client_id', runtimeConfig.clientId);
+    authUrl.searchParams.append('response_type', 'code');
+    authUrl.searchParams.append('redirect_uri', resolvedRedirectUri);
+    authUrl.searchParams.append('code_challenge', codeChallenge);
+    authUrl.searchParams.append('code_challenge_method', 'S256');
+    authUrl.searchParams.append('state', state);
+    
+    if (scope) {
+        authUrl.searchParams.append('scope', scope);
+    } else {
+        authUrl.searchParams.append('scope', 'openid profile email');
+    }
+
+    return {
+        authUrl: authUrl.toString(),
+        state,
+        codeVerifier
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keycloak-api-manager",
-  "version": "5.0.7",
+  "version": "6.0.1",
   "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": {

package/test-output.log

@@ -1,72 +0,0 @@
-
-> keycloak-api-manager@4.1.0 test
-> npm --prefix test install && npm --prefix test test
-
-
-up to date, audited 260 packages in 2s
-
-48 packages are looking for funding
-  run `npm fund` for details
-
-12 vulnerabilities (3 low, 3 moderate, 4 high, 2 critical)
-
-To address all issues possible (including breaking changes), run:
-  npm audit fix --force
-
-Some issues need review, and may require choosing
-a different dependency.
-
-Run `npm audit` for details.
-
-> keycloak-api-manager-tests@1.0.0 test
-> NODE_ENV=test NODE_PATH=./node_modules mocha --exit
-
-
- Exception during run: /Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/Handlers/userProfileHandler.js:79
-        body: JSON.strasync function(filter) {
-                            ^^^^^^^^
-
-SyntaxError: Unexpected token 'function'
-    at wrapSafe (node:internal/modules/cjs/loader:1515:18)
-    at Module._compile (node:internal/modules/cjs/loader:1537:20)
-    at Object..js (node:internal/modules/cjs/loader:1708:10)
-    at Module.load (node:internal/modules/cjs/loader:1318:32)
-    at Function._load (node:internal/modules/cjs/loader:1128:12)
-    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
-    at wrapModuleLoad (node:internal/modules/cjs/loader:219:24)
-    at Module.require (node:internal/modules/cjs/loader:1340:12)
-    at require (node:internal/modules/helpers:138:16)
-    at Object.<anonymous> (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/index.js:15:24)
-    at Module._compile (node:internal/modules/cjs/loader:1565:14)
-    at Object..js (node:internal/modules/cjs/loader:1708:10)
-    at Module.load (node:internal/modules/cjs/loader:1318:32)
-    at Function._load (node:internal/modules/cjs/loader:1128:12)
-    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
-    at wrapModuleLoad (node:internal/modules/cjs/loader:219:24)
-    at Module.require (node:internal/modules/cjs/loader:1340:12)
-    at require (node:internal/modules/helpers:138:16)
-    at Object.<anonymous> (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/test/enableServerFeatures.js:47:25)
-    at Module._compile (node:internal/modules/cjs/loader:1565:14)
-    at Object..js (node:internal/modules/cjs/loader:1708:10)
-    at Module.load (node:internal/modules/cjs/loader:1318:32)
-    at Function._load (node:internal/modules/cjs/loader:1128:12)
-    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
-    at wrapModuleLoad (node:internal/modules/cjs/loader:219:24)
-    at Module.require (node:internal/modules/cjs/loader:1340:12)
-    at require (node:internal/modules/helpers:138:16)
-    at Object.<anonymous> (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/test/setup.js:29:30)
-    at Module._compile (node:internal/modules/cjs/loader:1565:14)
-    at Object..js (node:internal/modules/cjs/loader:1708:10)
-    at Module.load (node:internal/modules/cjs/loader:1318:32)
-    at Function._load (node:internal/modules/cjs/loader:1128:12)
-    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
-    at wrapModuleLoad (node:internal/modules/cjs/loader:219:24)
-    at cjsLoader (node:internal/modules/esm/translators:263:5)
-    at ModuleWrap.<anonymous> (node:internal/modules/esm/translators:196:7)
-    at ModuleJob.run (node:internal/modules/esm/module_job:271:25)
-    at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:547:26)
-    at async formattedImport (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/test/node_modules/mocha/lib/nodejs/esm-utils.js:9:14)
-    at async exports.requireOrImport (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/test/node_modules/mocha/lib/nodejs/esm-utils.js:42:28)
-    at async exports.loadFilesAsync (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/test/node_modules/mocha/lib/nodejs/esm-utils.js:100:20)
-    at async singleRun (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/test/node_modules/mocha/lib/cli/run-helpers.js:162:3)
-    at async exports.handler (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/test/node_modules/mocha/lib/cli/run.js:375:5)