keycloak-api-manager 6.0.0 → 6.0.2

package/Handlers/clientPoliciesHandler.js

@@ -42,7 +42,8 @@ exports.getPolicies = function(filter) {
  *     - profiles: (array) - Profiles to apply when policy matches
  */
 exports.updatePolicies = async function(filter, policiesRepresentation) {
-    // Direct API call since @keycloak/keycloak-admin-client doesn't support this
+    // Direct API call: admin-client support for client-policies update endpoints
+    // is incomplete/inconsistent across versions.
     const realm = filter?.realm || kcAdminClientHandler.realmName;
     const baseUrl = kcAdminClientHandler.baseUrl;
     const token = kcAdminClientHandler.accessToken;
@@ -95,7 +96,8 @@ exports.getProfiles = function(filter) {
  *       - configuration: (object) - Executor-specific configuration
  */
 exports.updateProfiles = async function(filter, profilesRepresentation) {
-    // Direct API call since @keycloak/keycloak-admin-client doesn't support this
+    // Direct API call: admin-client support for client-policies update endpoints
+    // is incomplete/inconsistent across versions.
     const realm = filter?.realm || kcAdminClientHandler.realmName;
     const baseUrl = kcAdminClientHandler.baseUrl;
     const token = kcAdminClientHandler.accessToken;

package/Handlers/clientsHandler.js

@@ -14,6 +14,7 @@ exports.setKcAdminClient=function(kcAdminClient){
 /**
  * Helper function to make direct HTTP calls to Keycloak Admin API.
  * Used when @keycloak/keycloak-admin-client has bugs or inconsistencies.
+ * This keeps behavior aligned with server endpoints even when upstream wrappers lag behind.
  * 
  * @param {string} path - API path relative to baseUrl (e.g., '/admin/realms/...')
  * @param {string} method - HTTP method (GET, POST, PUT, DELETE)
@@ -551,19 +552,6 @@ exports.listAvailableRealmScopeMappings=function(filter){
 }
 
 
-/**
- * ***************************** - listAvailableRealmScopeMappings - *******************************
- * The method is used to retrieve all realm-level roles that are available to be assigned to a specific client.
- * These are roles defined at the realm level that the client does not yet have mapped, allowing you to see what can be added.
- * @parameters:
- * - filter: JSON structure that defines the filter parameters:
- *     - id: [required] The ID of the client for which you want to list available realm-level role mappings.
- */
-exports.listAvailableRealmScopeMappings=function(filter){
- return (kcAdminClientHandler.clients.listAvailableRealmScopeMappings(filter));
-}
-
-
 /**
  * ***************************** - listRealmScopeMappings - *******************************
  * The method retrieves the realm-level roles currently assigned to a client as part of its scope mappings.

package/Handlers/organizationsHandler.js

@@ -17,7 +17,8 @@ exports.setKcAdminClient = function(kcAdminClient) {
 }
 
 /**
- * Helper function to make direct API calls to Keycloak
+ * Helper to perform direct Admin REST calls for Organizations endpoints.
+ * This bypasses admin-client gaps for some Keycloak versions/features.
  */
 async function makeDirectApiCall(method, endpoint, body = null) {
     const baseUrl = kcAdminClientHandler.baseUrl;

package/Handlers/realmsHandler.js

@@ -1,4 +1,3 @@
-
 /**
  * **************************************************************************************************
  * **************************************************************************************************

package/Handlers/userProfileHandler.js

@@ -23,7 +23,7 @@ exports.setKcAdminClient = function(kcAdminClient) {
  * @returns: User profile configuration object with attributes, groups, etc.
  */
 exports.getConfiguration = async function(filter) {
-    // Direct API call for better compatibility
+    // Direct API call: this endpoint is not consistently exposed across admin-client versions.
     const realm = filter?.realm || kcAdminClientHandler.realmName;
     const baseUrl = kcAdminClientHandler.baseUrl;
     const token = kcAdminClientHandler.accessToken;
@@ -63,7 +63,7 @@ exports.getConfiguration = async function(filter) {
  *   - unmanagedAttributePolicy: (string) - Policy for unmanaged attributes
  */
 exports.updateConfiguration = async function(filter, userProfileConfig) {
-    // Direct API call for better compatibility
+    // Direct API call: this endpoint is not consistently exposed across admin-client versions.
     const realm = filter?.realm || kcAdminClientHandler.realmName;
     const baseUrl = kcAdminClientHandler.baseUrl;
     const token = kcAdminClientHandler.accessToken;

package/OIDC_MIGRATION_PLAN.md

@@ -1,8 +1,20 @@
 # OIDC Methods Migration Plan - keycloak-api-manager
 
+## 🚀 Current Status: v6.0.1 - Migration Released
+
+✅ **OIDC Methods Deprecated:** All OIDC authentication methods are marked `@deprecated` since 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`.
+This architecture follows a **planned migration** of OIDC methods (`auth()`, `login()`, `loginPKCE()`) from `keycloak-api-manager` to `keycloak-express-middleware`.
 
 ## Current State (v5.0.8)
 
@@ -12,6 +24,22 @@ L'architettura prevede una **migrazione pianificata** dei metodi OIDC (`auth()`,
 - ✅ `generateAuthorizationUrl(options)` - PKCE URL generator
 - ✅ `loginPKCE(credentials)` - PKCE token exchange
 
+## Current State (v6.0.1) - 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
@@ -45,49 +73,80 @@ keycloak-express-middleware (User Authentication)
 - [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
 
-**Status:** Ready for integration into `keycloak-express-middleware`
+### For Current Users (v5.0.8 or earlier)
 
-### 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`
+**Action Required:** Migrate to keycloak-express-middleware before v7.0.0.
 
-**Your Action:** Follow `keycloak-express-middleware/OIDC_INTEGRATION_GUIDE.md`
+**Timeline:** v6.0.0 is deprecated (warnings only), v7.0.0 will remove methods entirely.
 
-### Phase 3: Deprecation in keycloak-api-manager (v6.0.0)
+**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
 
-Once middleware integration is confirmed:
+### For New Projects
 
-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);
-   };
-   ```
+**Action Required:** Do NOT use OIDC methods from keycloak-api-manager.
 
-2. **Update documentation:**
-   - Add migration guide in README
-   - Mark OIDC methods as deprecated in API docs
-   - Link to middleware documentation
+**Recommendation:** Use keycloak-express-middleware v6.1.0+ for all user authentication.
 
-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
+## NPM Packages
 
-## Current keycloak-api-manager Methods
+### keycloak-api-manager
+
+| Version | OIDC Methods | Status |
+|---------|------------|--------|
+| v5.0.8 | Supported | Legacy (should migrate) |
+| v6.0.1 | 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)
 
-### `auth(credentials)` - Generic OIDC Token Grant
 ```javascript
-// Still works, but should use middleware
+// ⚠️ DEPRECATED - Don't use in new code
 const token = await KeycloakManager.auth({
   grant_type: 'password',
   username: 'user',
@@ -97,7 +156,7 @@ const token = await KeycloakManager.auth({
 
 **Migration Path:**
 ```javascript
-// Instead use middleware
+// ✅ NEW - Use keycloak-express-middleware instead
 const token = await keycloakMiddleware.login({
   grant_type: 'password',
   username: 'user',
@@ -105,9 +164,12 @@ const token = await keycloakMiddleware.login({
 });
 ```
 
-### `login(credentials)` - Preferred Alias
+---
+
+### `login(credentials)` - Preferred Alias (DEPRECATED)
+
 ```javascript
-// Currently the preferred way in API manager
+// ⚠️ DEPRECATED - Don't use in new code
 const token = await KeycloakManager.login({
   grant_type: 'client_credentials'
 });
@@ -115,15 +177,18 @@ const token = await KeycloakManager.login({
 
 **Migration Path:**
 ```javascript
-// Move to middleware
+// ✅ NEW - Use keycloak-express-middleware instead
 const token = await keycloakMiddleware.login({
   grant_type: 'client_credentials'
 });
 ```
 
-### `generateAuthorizationUrl(options)` - PKCE URL Generator
+---
+
+### `generateAuthorizationUrl(options)` - PKCE URL Generator (DEPRECATED)
+
 ```javascript
-// Generates OAuth2 authorization URL + PKCE pair
+// ⚠️ DEPRECATED - Don't use in new code
 const pkceFlow = KeycloakManager.generateAuthorizationUrl({
   redirect_uri: 'https://app/callback'
 });
@@ -131,15 +196,18 @@ const pkceFlow = KeycloakManager.generateAuthorizationUrl({
 
 **Migration Path:**
 ```javascript
-// Move to middleware
+// ✅ NEW - Use keycloak-express-middleware instead
 const pkceFlow = keycloakMiddleware.generateAuthorizationUrl({
   redirect_uri: 'https://app/callback'
 });
 ```
 
-### `loginPKCE(credentials)` - PKCE Token Exchange
+---
+
+### `loginPKCE(credentials)` - PKCE Token Exchange (DEPRECATED)
+
 ```javascript
-// Exchange auth code for tokens in callback
+// ⚠️ DEPRECATED - Don't use in new code
 const token = await KeycloakManager.loginPKCE({
   code: req.query.code,
   redirect_uri: 'https://app/callback',
@@ -149,7 +217,7 @@ const token = await KeycloakManager.loginPKCE({
 
 **Migration Path:**
 ```javascript
-// Move to middleware
+// ✅ NEW - Use keycloak-express-middleware instead
 const token = await keycloakMiddleware.loginPKCE({
   code: req.query.code,
   redirect_uri: 'https://app/callback',
@@ -157,6 +225,8 @@ const token = await keycloakMiddleware.loginPKCE({
 });
 ```
 
+---
+
 ## What Stays in keycloak-api-manager
 
 ✅ **These remain unchanged forever:**

package/README.md

@@ -54,6 +54,8 @@ console.log(users.length);
 KeycloakManager.stop();
 ```
 
+> **💡 Tip:** For user authentication (including Authorization Code + PKCE), use [`keycloak-express-middleware`](https://github.com/smartenv-crs4/keycloak-express-middleware). OIDC methods in this package are deprecated and kept only for backward compatibility.
+
 ## Keycloak Feature Flags
 
 For full API coverage in this package (especially Organizations, Client Policies, User Profile, Group permissions), run Keycloak with:
@@ -100,9 +102,9 @@ Configured handler namespaces:
 
 All documentation is centralized under `docs/`.
 
-### Guides (Practical Implementation)
+### Guides
 
-- [PKCE Login Flow Guide](docs/guides/PKCE-Login-Flow.md) - Step-by-step guide for implementing OAuth2 Authorization Code + PKCE authentication
+- [OIDC Migration Plan](OIDC_MIGRATION_PLAN.md) - Deprecation status and migration notes to keycloak-express-middleware
 
 ### API Reference
 
@@ -161,7 +163,7 @@ docs/               # Centralized documentation
 
 ## Versioning and Compatibility
 
-- Package version: `6.0.0`
+- Package version: `6.0.1`
 - Keycloak Admin client dependency: `@keycloak/keycloak-admin-client`
 - Main compatibility target: Keycloak 25/26