keycloak-api-manager 5.0.7 → 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:
 
@@ -158,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,6 +349,95 @@ 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.

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

@@ -72,98 +72,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 +133,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 +182,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 +189,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 +207,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 +248,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 +270,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;
     

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.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": {