keycloak-express-middleware 6.1.1 → 6.1.2

package/MIGRATION_STATUS.md

@@ -1,162 +1,48 @@
-# OIDC Methods Migration - Status Report
-
-## 📋 Summary
-
-Ho creato una soluzione **pronta all'uso** per migrare i metodi OIDC da `keycloak-api-manager` a `keycloak-express-middleware`.
-
-## ✅ What's Been Done
-
-### 1. **Ready-to-Integrate File: `oidc-methods.js`**
-- ✅ 3 metodi pronti: `generateAuthorizationUrl()`, `login()`, `loginPKCE()`
-- ✅ Full JSDoc documentation
-- ✅ No external dependencies (only Node.js crypto)
-- ✅ Copy-paste ready into the middleware class
-- ✅ Tested and verified
-
-### 2. **Comprehensive Test Suite: `test/oidc-methods.test.js`**
-- ✅ 21 test cases, all passing
-- ✅ Tests configuration, PKCE generation, token exchange
-- ✅ Error handling and edge cases covered
-- ✅ Mock fetch to avoid external calls
-- ✅ Run with: `npm test`
-
-### 3. **Integration Guide: `OIDC_INTEGRATION_GUIDE.md`**
-- ✅ Step-by-step instructions
-- ✅ Copy-paste code snippets
-- ✅ Troubleshooting guide
-- ✅ Usage examples
-- ✅ Verification checklist
-
-### 4. **Files Location (keycloak-express-middleware)**
-```
-keycloak-express-middleware/
-├── oidc-methods.js                    ← Copy methods from here
-├── test/
-│   └── oidc-methods.test.js          ← Tests (21 passing ✓)
-└── OIDC_INTEGRATION_GUIDE.md         ← Integration instructions
-```
-
-## 🚀 Next Steps
-
-### **Option 1: Manual Integration (Safe & Controlled)**
-Follow the `OIDC_INTEGRATION_GUIDE.md`:
-1. Add 2 lines to constructor (save clientId, clientSecret)
-2. Copy 3 methods from `oidc-methods.js` into the class
-3. Run `npm test` to verify
-4. Deploy
-
-### **Option 2: I Can Automate It**
-If you want me to:
-1. Integrate the methods directly into `index.js`
-2. Run full test suite
-3. Create release v6.1.0 with OIDC support
-4. Push to git and npm
-
-Just let me know!
-
-## 📊 Test Results
-
-```
-✔ generateAuthorizationUrl() - 10 tests passing
-  ✓ Generates valid authorization URLs with all OAuth2 parameters
-  ✓ PKCE pair generation (random, cryptographically secure)
-  ✓ SHA256 code_challenge validation
-  ✓ Custom scope and state support
-  ✓ CamelCase parameter aliasing
-  ✓ Error handling for missing parameters
-
-✔ login() - 6 tests passing
-  ✓ Auto-append clientId and clientSecret
-  ✓ Token endpoint communication
-  ✓ Success and error response handling
-  ✓ Credential construction
-
-✔ loginPKCE() - 5 tests passing
-  ✓ Parameter validation (code, verifier, redirect_uri)
-  ✓ CamelCase aliases support
-  ✓ PKCE token exchange construction
-  ✓ Delegation to login()
-
-Total: 21 passing (57ms)
-```
-
-## 🎯 Architecture Decision
-
-**Why move from keycloak-api-manager to keycloak-express-middleware?**
-
-| Aspect | API Manager | Express Middleware |
-|--------|------------|-------------------|
-| Purpose | Admin resource management | User application auth |
-| OAuth2 Context | ❌ Not needed | ✅ Natural fit |
-| Session/Cookies | ❌ Not part of it | ✅ Full support |
-| Express integration | ❌ No | ✅ Yes |
-| Dependencies | ✅ keycloak-admin-client | ✅ keycloak-connect |
-
-**Result:** OIDC methods belong in the middleware package.
-
-## 📝 Git History
-
-```
-keycloak-express-middleware/main
-├── ef61793 Feat: add ready-to-integrate OIDC methods (generateAuthorizationUrl, login, loginPKCE) with comprehensive tests
-├── [previous middleware commits...]
-```
-
-## ⚠️ Important Notes
-
-### ✅ Backward Compatibility
-- No breaking changes planned
-- Existing middleware functionality untouched
-- New methods are additions only
-
-### 🔐 Security Considerations
-- PKCE verifier stored server-side only (session)
-- State parameter for CSRF protection
-- Tokens in HttpOnly cookies recommended
-- Code uses Go crypto best practices
-
-### 📦 Dependencies
-- No new npm packages needed
-- Uses Node.js 18+ global fetch
-- For Node 16-17: `npm install node-fetch`
-
-## 🎬 What You Can Do Now
-
-### Test Everything Works
-```bash
-cd keycloak-express-middleware
-npm test  # All 21 tests pass ✓
-```
-
-### Review the Code
-- Open `oidc-methods.js` - See the implementation
-- Open `test/oidc-methods.test.js` - See comprehensive tests
-- Open `OIDC_INTEGRATION_GUIDE.md` - Integration instructions
-
-### Integrate When Ready
-Follow `OIDC_INTEGRATION_GUIDE.md` to add to `index.js` class
-
-## 🔄 Next: keycloak-api-manager Updates
-
-Once integrated in middleware, we should:
-
-1. **Deprecate in keycloak-api-manager v6.0.0**
-   - Mark `auth()`, `login()`, `loginPKCE()` as deprecated
-   - Update docs with migration guide
-   - Keep methods working (backward compat)
-
-2. **Update documentation**
-   - Remove OIDC docs from API manager
-   - Add migration guide to middleware
-   - Update PKCE guide to use middleware
+# OIDC Migration Status
 
-3. **Release cycle**
-   - keycloak-express-middleware v6.1.0 with OIDC support
-   - keycloak-api-manager v6.0.0 with deprecation warnings
+## Summary
 
-## 📞 Questions?
-
-All documentation is in:
-- `OIDC_INTEGRATION_GUIDE.md` - How to integrate
-- `oidc-methods.js` - Full JSDoc comments
-- `test/oidc-methods.test.js` - Real usage examples
+OIDC runtime helpers are now documented and implemented in `keycloak-express-middleware`, with test coverage and integration guidance aligned to the current constructor-based API.
+
+## Implemented Scope
+
+The following helper methods are part of the migration scope:
+
+- `generateAuthorizationUrl(options)`
+- `loginWithCredentials(credentials)`
+- `loginPKCE(credentials)`
+
+These methods are documented in:
+
+- `docs/api/oidc-token-endpoint.md`
+- `docs/OIDC_INTEGRATION_GUIDE.md`
+
+## Validation Status
+
+- OIDC helper methods documented with parameters, return values, and examples
+- Integration guide updated to reflect constructor-based initialization
+- Naming consistency aligned with code (`keyCloackConfig`, `keyCloackOptions`)
+- Error handling guidance included for common runtime failures
+
+## Design Rationale
+
+OIDC login flow helpers belong in the Express middleware package because they are coupled to request/session lifecycle and application routing concerns.
+
+| Aspect | keycloak-api-manager | keycloak-express-middleware |
+|--------|----------------------|-----------------------------|
+| Primary purpose | Admin API orchestration | Application authentication and authorization |
+| Session/cookie awareness | No | Yes |
+| Express routing integration | No | Yes |
+| OIDC runtime flow fit | Limited | Native |
+
+## Compatibility Notes
+
+- The migration is additive for middleware users.
+- Existing middleware behavior remains unchanged.
+- Runtime requirements remain compatible with Node.js 18+ (`fetch` available globally).
+
+## Recommended Next Steps
+
+1. Validate your local environment with `npm test`.
+2. Review `docs/OIDC_INTEGRATION_GUIDE.md` for implementation-level guidance.
+3. Use `docs/api-reference.md` as the canonical API entry point.

package/OIDC_INTEGRATION_GUIDE.md

@@ -1,248 +1,23 @@
-# Integration Guide: Adding OIDC Methods to keycloak-express-middleware
+# OIDC Integration Guide
 
-This guide explains how to integrate the new OIDC authentication methods (`generateAuthorizationUrl()`, `login()`, `loginPKCE()`) into the `keycloak-express-middleware` class.
+This root-level guide is intentionally kept short to avoid drift.
+The canonical and maintained version is:
 
-## Files Created
+- docs/OIDC_INTEGRATION_GUIDE.md
 
-- **`oidc-methods.js`** - Ready-to-use OIDC methods (no external dependencies)
-- **`test/oidc-methods.test.js`** - Complete test suite (run with `npm test`)
+Current OIDC helper methods in code are:
 
-## Integration Steps
+- generateAuthorizationUrl(options)
+- loginWithCredentials(credentials)
+- loginPKCE(credentials)
 
-### Step 1: Run Tests (Verify Methods Work)
+Important alignment notes with current implementation:
 
-```bash
-npm test
-```
+- Initialization is constructor-based, not configure-based.
+- Use a middleware instance created with:
+  new keycloackAdapter(app, keyCloackConfig, keyCloackOptions)
+- For generic token endpoint exchange use loginWithCredentials, not login.
 
-Expected output: All tests should pass (20+ assertions)
+Quick verification command:
 
-### Step 2: Locate the Constructor in index.js
-
-Find the `keycloakExpressMiddleware` constructor:
-
-```javascript
-constructor(app, keyCloackConfig, keyCloackOptions) {
-    this.keycloak = null;
-    this.ready = false;
-    this.readyQueue = [];
-    this.realmName = keyCloackConfig.realm || keyCloackOptions.realmName;
-    this.authServerUrl = keyCloackConfig['auth-server-url'];
-    // ... rest of constructor
-}
-```
-
-### Step 3: Save Configuration in Constructor
-
-Add these lines after `this.authServerUrl`:
-
-```javascript
-// Store OIDC configuration for token endpoint helpers
-this.clientId = keyCloackConfig.resource || keyCloackOptions.clientId;
-this.clientSecret = keyCloackConfig.credentials?.secret || keyCloackOptions.clientSecret;
-```
-
-**Full example:**
-
-```javascript
-constructor(app, keyCloackConfig, keyCloackOptions) {
-    this.keycloak = null;
-    this.ready = false;
-    this.readyQueue = [];
-    this.realmName = keyCloackConfig.realm || keyCloackOptions.realmName;
-    this.authServerUrl = keyCloackConfig['auth-server-url'];
-    
-    // NEW: Store OIDC configuration
-    this.clientId = keyCloackConfig.resource || keyCloackOptions.clientId;
-    this.clientSecret = keyCloackConfig.credentials?.secret || keyCloackOptions.clientSecret;
-    
-    // ... rest of constructor (unchanged)
-}
-```
-
-### Step 4: Add Methods to the Class
-
-At the end of the `keycloakExpressMiddleware` class (before the closing brace), add these three methods from `oidc-methods.js`:
-
-```javascript
-    // ===== OIDC Authentication Methods =====
-    
-    /**
-     * Generate Authorization URL + PKCE pair for OAuth2 flow
-     * See oidc-methods.js for full documentation
-     */
-    generateAuthorizationUrl(options = {}) {
-        // ... copy from oidc-methods.js
-    }
-
-    /**
-     * Exchange credentials for OIDC tokens (generic token endpoint)
-     * See oidc-methods.js for full documentation
-     */
-    async login(credentials = {}) {
-        // ... copy from oidc-methods.js
-    }
-
-    /**
-     * Exchange authorization code + PKCE verifier for tokens
-     * See oidc-methods.js for full documentation
-     */
-    async loginPKCE(credentials = {}) {
-        // ... copy from oidc-methods.js
-    }
-```
-
-**Option: Copy-Paste from oidc-methods.js**
-
-You can copy the entire content from `oidc-methods.js` (lines with the three functions) directly into the class.
-
-### Step 5: Run Tests Again
-
-```bash
-npm test
-```
-
-Verify that all tests pass with the new methods integrated.
-
-### Step 6: Test in Your Application
-
-Create a simple test to verify the middleware works:
-
-```javascript
-const keycloakAdapter = require('keycloak-express-middleware');
-const express = require('express');
-
-const app = express();
-
-// Configure middleware
-await keycloakAdapter.configure({
-  app,
-  keyCloakConfig: {
-    realm: 'my-realm',
-    'auth-server-url': 'https://keycloak.example.com/',
-    resource: 'my-client',
-    credentials: { secret: 'my-secret' }
-  }
-});
-
-// Test PKCE flow initialization
-const pkceFlow = keycloakAdapter.generateAuthorizationUrl({
-  redirect_uri: 'http://localhost:3000/auth/callback'
-});
-
-```
-
-## Key Points
-
-### 1. No External Dependencies
-- Uses only Node.js built-in `crypto` module
-- Uses global `fetch` (available in Node 18+)
-- No new npm packages needed
-
-### 2. Backward Compatibility
-- All existing middleware functionality remains unchanged
-- New methods are optional additions
-- No breaking changes to existing API
-
-### 3. Configuration Sources
-The three methods use these configuration values from the middleware:
-- `this.authServerUrl` - From `keyCloakConfig['auth-server-url']`
-- `this.realmName` - From `keyCloakConfig.realm`
-- `this.clientId` - From `keyCloakConfig.resource` (or `keyCloackOptions.clientId`)
-- `this.clientSecret` - From `keyCloakConfig.credentials.secret` (or `keyCloackOptions.clientSecret`)
-
-### 4. Usage Examples
-
-#### Generate Authorization URL (for PKCE login initiation)
-
-```javascript
-const pkceFlow = keycloakAdapter.generateAuthorizationUrl({
-  redirect_uri: 'https://app.example.com/auth/callback',
-  scope: 'openid profile email'  // optional
-});
-
-req.session.pkce_state = pkceFlow.state;
-req.session.pkce_verifier = pkceFlow.codeVerifier;
-
-res.redirect(pkceFlow.authUrl);
-```
-
-#### Exchange Code for Token (for PKCE callback)
-
-```javascript
-const tokens = await keycloakAdapter.loginPKCE({
-  code: req.query.code,
-  redirect_uri: 'https://app.example.com/auth/callback',
-  code_verifier: req.session.pkce_verifier
-});
-
-res.cookie('access_token', tokens.access_token, { httpOnly: true });
-res.redirect('/dashboard');
-```
-
-#### Direct Token Grant
-
-```javascript
-// Password grant
-const tokens = await keycloakAdapter.login({
-  grant_type: 'password',
-  username: 'user@example.com',
-  password: 'password123'
-});
-
-// Client credentials
-const tokens = await keycloakAdapter.login({
-  grant_type: 'client_credentials'
-});
-
-// Refresh token
-const newTokens = await keycloakAdapter.login({
-  grant_type: 'refresh_token',
-  refresh_token: oldRefreshToken
-});
-```
-
-## Verification Checklist
-
-- [ ] All tests in `test/oidc-methods.test.js` pass
-- [ ] Constructor saves `clientId` and `clientSecret`
-- [ ] Three methods added to the class
-- [ ] `generateAuthorizationUrl()` works
-- [ ] `login()` works
-- [ ] `loginPKCE()` works
-- [ ] Existing middleware functionality still works
-- [ ] No runtime errors
-
-## Troubleshooting
-
-### Error: "requires middleware to be initialized"
-- Ensure `configure()` was called before using OIDC methods
-- Verify `authServerUrl`, `realmName`, and `clientId` are set
-
-### Error: "generateAuthorizationUrl requires redirect_uri"
-- Pass `redirect_uri` or `redirectUri` in options object
-
-### Fetch errors
-- Ensure Node.js 18+ (for global fetch)
-- For Node 16-17, add: `npm install node-fetch`
-
-## Testing Checklist
-
-Run tests to verify:
-
-```bash
-# All tests pass
-npm test
-
-# Test output shows:
-# - 20+ assertions passing
-# - No failures
-# - OIDC Methods suite: ✓
-```
-
-## Questions?
-
-Refer to:
-- `oidc-methods.js` - Method implementations and full JSDoc documentation
-- `test/oidc-methods.test.js` - Test examples showing all use cases
-- [PKCE Login Flow Guide](../keycloak-api-manager/docs/guides/PKCE-Login-Flow.md) - Real-world usage patterns
+- npm test