keycloak-api-manager 5.0.6 → 6.0.0

package/OIDC_MIGRATION_PLAN.md

@@ -0,0 +1,214 @@
+# OIDC Methods Migration Plan - keycloak-api-manager
+
+## 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
+
+## 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
+
+**Status:** Ready for integration into `keycloak-express-middleware`
+
+### Phase 2: Manual Integration (When You're Ready)
+- [ ] Integrate `oidc-methods.js` into middleware `index.js`
+- [ ] Run tests to verify
+- [ ] Release `keycloak-express-middleware v6.1.0`
+
+**Your Action:** Follow `keycloak-express-middleware/OIDC_INTEGRATION_GUIDE.md`
+
+### Phase 3: Deprecation in keycloak-api-manager (v6.0.0)
+
+Once middleware integration is confirmed:
+
+1. **Mark methods as deprecated** in index.js:
+   ```javascript
+   exports.auth = async function auth(credentials = {}) {
+       console.warn('⚠️ DEPRECATED: auth() is deprecated in v6.0. ' +
+           'Use keycloak-express-middleware.login() instead. ' +
+           'See: https://...');
+       return requestOidcToken(credentials);
+   };
+   ```
+
+2. **Update documentation:**
+   - Add migration guide in README
+   - Mark OIDC methods as deprecated in API docs
+   - Link to middleware documentation
+
+3. **Release v6.0.0:**
+   - Update package.json version
+   - Add breaking change notice
+   - Include migration guide in release notes
+
+4. **Future (v7.0.0):**
+   - Optionally remove these methods entirely
+   - Keep at least 1 major version for migration
+
+## Current keycloak-api-manager Methods
+
+### `auth(credentials)` - Generic OIDC Token Grant
+```javascript
+// Still works, but should use middleware
+const token = await KeycloakManager.auth({
+  grant_type: 'password',
+  username: 'user',
+  password: 'pass'
+});
+```
+
+**Migration Path:**
+```javascript
+// Instead use middleware
+const token = await keycloakMiddleware.login({
+  grant_type: 'password',
+  username: 'user',
+  password: 'pass'
+});
+```
+
+### `login(credentials)` - Preferred Alias
+```javascript
+// Currently the preferred way in API manager
+const token = await KeycloakManager.login({
+  grant_type: 'client_credentials'
+});
+```
+
+**Migration Path:**
+```javascript
+// Move to middleware
+const token = await keycloakMiddleware.login({
+  grant_type: 'client_credentials'
+});
+```
+
+### `generateAuthorizationUrl(options)` - PKCE URL Generator
+```javascript
+// Generates OAuth2 authorization URL + PKCE pair
+const pkceFlow = KeycloakManager.generateAuthorizationUrl({
+  redirect_uri: 'https://app/callback'
+});
+```
+
+**Migration Path:**
+```javascript
+// Move to middleware
+const pkceFlow = keycloakMiddleware.generateAuthorizationUrl({
+  redirect_uri: 'https://app/callback'
+});
+```
+
+### `loginPKCE(credentials)` - PKCE Token Exchange
+```javascript
+// Exchange auth code for tokens in callback
+const token = await KeycloakManager.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
@@ -65,16 +71,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:
 
@@ -97,6 +100,12 @@ Configured handler namespaces:
 
 All documentation is centralized under `docs/`.
 
+### Guides (Practical Implementation)
+
+- [PKCE Login Flow Guide](docs/guides/PKCE-Login-Flow.md) - Step-by-step guide for implementing OAuth2 Authorization Code + PKCE authentication
+
+### API Reference
+
 - [API Reference (Index)](docs/api-reference.md)
 - [API - Configuration](docs/api/configuration.md)
 - [API - Realms](docs/api/realms.md)
@@ -113,6 +122,9 @@ All documentation is centralized under `docs/`.
 - [API - User Profile](docs/api/user-profile.md)
 - [API - Client Policies](docs/api/client-policies.md)
 - [API - Server Info](docs/api/server-info.md)
+
+### General Documentation
+
 - [Architecture and Runtime](docs/architecture.md)
 - [Keycloak Setup and Feature Flags](docs/keycloak-setup.md)
 - [Testing Guide](docs/testing.md)
@@ -149,10 +161,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)
@@ -348,12 +349,103 @@ console.log(refreshed.access_token);
 
 ---
 
+## generateAuthorizationUrl()
+
+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()
 
 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)**
+
 **Syntax:**
 ```javascript
 await KeycloakManager.loginPKCE(credentials)

package/docs/api-reference.md

@@ -4,6 +4,9 @@ Complete API documentation for keycloak-api-manager.
 
 ## Table of Contents
 
+### Guides (Practical Implementation)
+- [PKCE Login Flow Guide](guides/PKCE-Login-Flow.md) - Step-by-step OAuth2 Authorization Code + PKCE implementation guide
+
 ### Core API
 - [Configuration & Authentication](api/configuration.md) - Setup, authentication, and lifecycle management
 
@@ -77,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

@@ -0,0 +1,508 @@
+# PKCE Login Flow Guide
+
+This guide walks you through implementing OAuth2 Authorization Code + PKCE flow in your application using Keycloak and the keycloak-api-manager library.
+
+## Overview
+
+PKCE (Proof Key for Code Exchange) is the modern, secure way for browser-based and mobile applications to authenticate users through Keycloak. Unlike the legacy resource owner password grant, PKCE:
+
+- ✅ Never exposes user passwords to your backend
+- ✅ Works seamlessly with Keycloak's authorization server
+- ✅ Provides built-in CSRF protection via state parameter
+- ✅ Protects against authorization code interception attacks
+- ✅ Is the OAuth2 standard for public clients
+
+## Flow Diagram
+
+```
+┌─────────────┐                                    ┌──────────────┐
+│   Browser   │                                    │  Keycloak    │
+│  (User)     │                                    │   Server     │
+└──────┬──────┘                                    └──────────────┘
+       │                                                  ▲
+       │  1. Click "Login"                               │
+       ├─────────────────────────────────────────────────►
+       │                                                  │
+       │  2. Verify state, generate PKCE pair             │
+       │  3. Redirect to Keycloak /auth with              │
+       │     code_challenge & state                       │
+       │                                                  │
+       │◄─────────────────────────────────────────────────┤
+       │     Keycloak login page                          │
+       │                                                  │
+       │  4. User enters credentials                      │
+       ├─────────────────────────────────────────────────►
+       │                                                  │
+       │  5. Verify credentials                           │
+       │  6. Redirect to /callback with                   │
+       │     code + state                                 │
+       │                                                  │
+       │◄─────────────────────────────────────────────────┤
+       │  code=abc123&state=xyz789                        │
+       │                                                  │
+       │  7. Exchange code for token                      │
+       │  (with code_verifier)                            │
+       │──────────────────────────────────────────────────►
+       │     POST /auth/callback backend                  │
+       │                                                  │
+       │                                    ┌────────────┐
+       │                                    │  Backend   │
+       │                                    │  (Node.js) │
+       │                                    └────────────┘
+       │                                           ▲
+       │                                           │
+       │                                           │
+       │                          8. Call loginPKCE()
+       │                          with code, verifier
+       │                                           │
+       │                      Keycloak validates
+       │                      code_challenge vs
+       │                      code_verifier
+       │                                           │
+       │                     9. Return access token
+       │                        (JWT)
+       │                                           │
+       │  10. Set secure HttpOnly cookie           │
+       │◄──────────────────────────────────────────┤
+       │  (with access_token + refresh_token)      │
+       │                                           │
+       │  Browser is now authenticated!            │
+       │                                           │
+```
+
+## Step-by-Step Implementation
+
+### Step 1: Generate Authorization URL
+
+When the user clicks "Login", use `generateAuthorizationUrl()` from keycloak-api-manager to generate the PKCE pair and authorization URL:
+
+```javascript
+const pkceFlow = KeycloakManager.generateAuthorizationUrl({
+  redirect_uri: `${process.env.APP_URL}/auth/callback`,
+  scope: 'openid profile email' // optional, defaults to 'openid profile email'
+});
+
+// Result contains:
+// {
+//   authUrl: 'https://keycloak.example.com/realms/my-realm/protocol/openid-connect/auth?...',
+//   state: 'random_state_value',
+//   codeVerifier: 'random_verifier_value'
+// }
+```
+
+Store the `state` and `codeVerifier` in your session, then redirect the user to the authorization URL:
+
+```javascript
+app.get('/auth/login', (req, res) => {
+  const pkceFlow = KeycloakManager.generateAuthorizationUrl({
+    redirect_uri: `${process.env.APP_URL}/auth/callback`
+  });
+  
+  // 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
+  res.redirect(pkceFlow.authUrl);
+});
+```
+
+**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 using `loginPKCE()`:
+
+```javascript
+// User callback after Keycloak login
+app.get('/auth/callback', async (req, res) => {
+  try {
+    const { code, state, error } = req.query;
+    
+    // 1. Validate state parameter (CSRF protection)
+    if (state !== req.session.pkce_state) {
+      return res.status(400).send('Invalid state parameter - CSRF attack detected');
+    }
+    
+    // 2. Check for authorization errors
+    if (error) {
+      return res.status(400).send(`Authorization failed: ${error}`);
+    }
+    
+    // 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 keycloak-api-manager
+    const tokenResponse = await KeycloakManager.loginPKCE({
+      code,
+      redirect_uri: `${process.env.APP_URL}/auth/callback`,
+      code_verifier
+    });
+    
+    // 5. Set secure HTTPOnly cookie with access token
+    res.cookie('access_token', tokenResponse.access_token, {
+      httpOnly: true,        // Prevent XSS access
+      secure: true,          // HTTPS only
+      sameSite: 'strict',    // CSRF protection
+      maxAge: tokenResponse.expires_in * 1000
+    });
+    
+    // Also store refresh token separately
+    res.cookie('refresh_token', tokenResponse.refresh_token, {
+      httpOnly: true,
+      secure: true,
+      sameSite: 'strict',
+      maxAge: 7 * 24 * 60 * 60 * 1000 // 7 days
+    });
+    
+    // 6. Clear sensitive session data
+    delete req.session.pkce_verifier;
+    delete req.session.pkce_state;
+    
+    // Redirect to application home
+    res.redirect('/dashboard');
+    
+  } catch (error) {
+    console.error('Token exchange failed:', error);
+    res.status(500).send('Authentication failed');
+  }
+});
+```
+
+**Security checks in this step:**
+- ✅ Validate `state` matches what we stored (CSRF protection)
+- ✅ Check for authorization errors
+- ✅ Verify `code_verifier` exists in session
+- ✅ Exchange code with verifier (proves we initiated the flow)
+- ✅ Store token in HttpOnly cookie (prevents XSS theft)
+- ✅ Clear sensitive session data
+
+## Complete Working Example
+
+Here's a complete Express.js application with PKCE flow:
+
+```javascript
+const express = require('express');
+const session = require('express-session');
+const jwt = require('jsonwebtoken');
+const cookieParser = require('cookie-parser');
+const KeycloakManager = require('keycloak-api-manager');
+
+const app = express();
+
+// Middleware
+app.use(express.json());
+app.use(cookieParser());
+app.use(session({
+  secret: process.env.SESSION_SECRET || 'dev-secret',
+  resave: false,
+  saveUninitialized: true,
+  cookie: { httpOnly: true, secure: false } // Set secure: true in production
+}));
+
+// 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,
+  grantType: 'client_credentials'
+});
+
+// Routes
+app.get('/auth/login', (req, res) => {
+  // Generate PKCE pair and authorization URL
+  const pkceFlow = KeycloakManager.generateAuthorizationUrl({
+    redirect_uri: `${process.env.APP_URL}/auth/callback`,
+    scope: 'openid profile email'
+  });
+  
+  // Store state and verifier in session (server-side only!)
+  req.session.pkce_state = pkceFlow.state;
+  req.session.pkce_verifier = pkceFlow.codeVerifier;
+  
+  // 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');
+    }
+    
+    if (error) {
+      return res.status(400).send(`Authorization failed: ${error}`);
+    }
+    
+    const code_verifier = req.session.pkce_verifier;
+    if (!code_verifier) {
+      return res.status(400).send('PKCE verifier not found');
+    }
+    
+    // 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
+    });
+    
+    // Set secure cookies
+    res.cookie('access_token', tokenResponse.access_token, {
+      httpOnly: true,
+      secure: true,
+      sameSite: 'strict',
+      maxAge: tokenResponse.expires_in * 1000
+    });
+    
+    res.cookie('refresh_token', tokenResponse.refresh_token, {
+      httpOnly: true,
+      secure: true,
+      sameSite: 'strict',
+      maxAge: 7 * 24 * 60 * 60 * 1000
+    });
+    
+    // Clear sensitive data
+    delete req.session.pkce_verifier;
+    delete req.session.pkce_state;
+    
+    res.redirect('/dashboard');
+    
+  } catch (error) {
+    console.error('Token exchange failed:', error);
+    res.status(500).send('Authentication failed');
+  }
+});
+
+app.get('/dashboard', (req, res) => {
+  const token = req.cookies.access_token;
+  if (!token) {
+    return res.redirect('/auth/login');
+  }
+  
+  try {
+    const decoded = jwt.decode(token); // Or verify with public key in production
+    res.send(`Welcome, ${decoded.preferred_username}!`);
+  } catch (error) {
+    res.redirect('/auth/login');
+  }
+});
+
+app.get('/logout', (req, res) => {
+  res.clearCookie('access_token');
+  res.clearCookie('refresh_token');
+  req.session.destroy();
+  res.redirect('/');
+});
+
+// Start server
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+  console.log('Login at http://localhost:3000/auth/login');
+});
+```
+
+## Environment Variables
+
+```bash
+KEYCLOAK_URL=http://localhost:8080
+KEYCLOAK_REALM=master
+KEYCLOAK_CLIENT_ID=my-app
+KEYCLOAK_CLIENT_SECRET=your-client-secret
+APP_URL=http://localhost:3000
+SESSION_SECRET=your-session-secret
+```
+
+## Security Best Practices
+
+### ✅ DO
+
+- ✅ Store PKCE verifier in **secure server-side session**, never in cookies
+- ✅ Validate state parameter every time (CSRF protection)
+- ✅ Use **HttpOnly cookies** for tokens (prevents XSS theft)
+- ✅ Use **Secure flag** on cookies (HTTPS only in production)
+- ✅ Use **SameSite=strict** on cookies (CSRF protection)
+- ✅ Clear sensitive data from session after token exchange
+- ✅ Use SHA256 for code_challenge (`S256` method)
+- ✅ Generate cryptographically secure random values (use `crypto` module)
+
+### ❌ DON'T
+
+- ❌ Store code_verifier in browser (localStorage, sessionStorage, etc.)
+- ❌ Skip state parameter validation
+- ❌ Use weak random generators
+- ❌ Expose tokens in URL parameters
+- ❌ Store tokens in browser storage (vulnerable to XSS)
+- ❌ Use plain HTTP (always HTTPS in production)
+- ❌ Reuse PKCE pairs or state values
+
+## Common Issues & Troubleshooting
+
+### "Invalid state parameter - CSRF attack detected"
+
+**Cause:** Browser tabs have separate sessions, or cookies are not being persisted.
+
+**Solution:**
+```javascript
+// Ensure session cookies are sent with redirects
+app.use(session({
+  cookie: { 
+    httpOnly: true, 
+    secure: true,
+    sameSite: 'lax'  // Allow cross-site for redirects
+  }
+}));
+```
+
+### "PKCE verifier not found in session"
+
+**Cause:** Session was lost between `/auth/login` and `/auth/callback`.
+
+**Debug:**
+```javascript
+app.get('/auth/callback', (req, res) => {
+  console.log('Session ID:', req.sessionID);
+  console.log('Session data:', req.session);
+  // ... rest of callback
+});
+```
+
+### "Invalid code_challenge"
+
+**Cause:** The code_challenge calculated by Keycloak doesn't match our SHA256 hash.
+
+**Verify:** The `createPkcePair()` function uses S256 (SHA256). Ensure code_challenge is:
+1. Lowercase base64url-encoded
+2. Derived from code_verifier with SHA256, not any other hash
+
+### Access token not being set
+
+**Cause:** `loginPKCE()` threw an error that wasn't caught, or response format is different.
+
+**Debug:**
+```javascript
+const tokenResponse = await KeycloakManager.loginPKCE({...});
+console.log('Token response:', JSON.stringify(tokenResponse, null, 2));
+```
+
+Expected response:
+```json
+{
+  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "expires_in": 300,
+  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "Bearer",
+  "scope": "openid profile email"
+}
+```
+
+## Production Considerations
+
+### 1. Session Storage
+
+For production, use Redis instead of in-memory sessions:
+
+```javascript
+const RedisStore = require('connect-redis').default;
+const { createClient } = require('redis');
+
+const redisClient = createClient();
+redisClient.connect();
+
+app.use(session({
+  store: new RedisStore({ client: redisClient }),
+  secret: process.env.SESSION_SECRET,
+  resave: false,
+  saveUninitialized: false,
+  cookie: { 
+    httpOnly: true,
+    secure: true,
+    sameSite: 'strict',
+    maxAge: 1000 * 60 * 60 * 24 // 24 hours
+  }
+}));
+```
+
+### 2. Token Refresh
+
+Access tokens expire. Implement refresh token logic:
+
+```javascript
+function isTokenExpiring(token) {
+  const decoded = jwt.decode(token);
+  const now = Math.floor(Date.now() / 1000);
+  return decoded.exp - now < 60; // Refresh if less than 60 seconds left
+}
+
+app.use(async (req, res, next) => {
+  const token = req.cookies.access_token;
+  const refreshToken = req.cookies.refresh_token;
+  
+  if (!token) return next();
+  
+  if (isTokenExpiring(token) && refreshToken) {
+    try {
+      const newTokens = await KeycloakManager.login({
+        grant_type: 'refresh_token',
+        refresh_token: refreshToken,
+        client_id: process.env.KEYCLOAK_CLIENT_ID,
+        client_secret: process.env.KEYCLOAK_CLIENT_SECRET
+      });
+      
+      res.cookie('access_token', newTokens.access_token, { httpOnly: true, secure: true });
+      res.cookie('refresh_token', newTokens.refresh_token, { httpOnly: true, secure: true });
+    } catch (error) {
+      res.clearCookie('access_token');
+      res.clearCookie('refresh_token');
+    }
+  }
+  
+  next();
+});
+```
+
+### 3. Token Verification
+
+Always verify tokens using Keycloak's public key:
+
+```javascript
+const jwksClient = require('jwks-rsa');
+
+const client = jwksClient({
+  jwksUri: `${process.env.KEYCLOAK_URL}/auth/realms/${process.env.KEYCLOAK_REALM}/protocol/openid-connect/certs`
+});
+
+function getKey(header, callback) {
+  client.getSigningKey(header.kid, (err, key) => {
+    if (err) return callback(err);
+    callback(null, key.getPublicKey());
+  });
+}
+
+function verifyToken(token) {
+  return new Promise((resolve, reject) => {
+    jwt.verify(token, getKey, {
+      algorithms: ['RS256'],
+      issuer: `${process.env.KEYCLOAK_URL}/auth/realms/${process.env.KEYCLOAK_REALM}`,
+      audience: process.env.KEYCLOAK_CLIENT_ID
+    }, (err, decoded) => {
+      err ? reject(err) : resolve(decoded);
+    });
+  });
+}
+```
+
+## 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.6",
+  "version": "6.0.0",
   "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": {