keycloak-api-manager 6.0.1 → 6.0.3

package/Handlers/attackDetectionHandler.js

@@ -15,10 +15,11 @@ exports.setKcAdminClient = function(kcAdminClient) {
 
 /**
  * ***************************** - getBruteForceStatus - *******************************
- * Get brute force detection status for all users in a realm
+ * Get brute force detection status in the current realm context.
  * 
  * @parameters:
- * - realm: (string, required) - The realm name
+ * - filter: (object, optional) request filter object.
+ *    - realm: (string, optional) Realm override for this call.
  * @returns: Array of user brute force status objects
  */
 exports.getBruteForceStatus = function(filter) {
@@ -27,11 +28,12 @@ exports.getBruteForceStatus = function(filter) {
 
 /**
  * ***************************** - getUserBruteForceStatus - *******************************
- * Get brute force detection status for a specific user
+ * Get brute force detection status for one user.
  * 
  * @parameters:
- * - realm: (string, required) - The realm name  
- * - id: (string, required) - The user ID
+ * - filter: (object, required) request filter object.
+ *    - id: (string, required) User ID.
+ *    - realm: (string, optional) Realm override for this call.
  * @returns: User brute force status object
  */
 exports.getUserBruteForceStatus = function(filter) {
@@ -43,8 +45,9 @@ exports.getUserBruteForceStatus = function(filter) {
  * Clear all login failures for a specific user
  * 
  * @parameters:
- * - realm: (string, required) - The realm name
- * - id: (string, required) - The user ID
+ * - filter: (object, required) request filter object.
+ *    - id: (string, required) User ID.
+ *    - realm: (string, optional) Realm override for this call.
  * @returns: Promise
  */
 exports.clearUserLoginFailures = function(filter) {
@@ -56,7 +59,8 @@ exports.clearUserLoginFailures = function(filter) {
  * Clear all login failures for all users in a realm
  * 
  * @parameters:
- * - realm: (string, required) - The realm name
+ * - filter: (object, optional) request filter object.
+ *    - realm: (string, optional) Realm override for this call.
  * @returns: Promise
  */
 exports.clearAllLoginFailures = function(filter) {

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/clientScopesHandler.js

@@ -389,7 +389,7 @@ exports.listScopeMappings=function(filter){
  * @parameters:
  * - filter: parameter provided as a JSON object that accepts the following filter:
  *     - id: [required] The ID of the client scope to list available scope mapping.
- *     - client: [required] The client ID (client UUID or client identifier) from which to list available roles
+ *     - clientUniqueId: [required] The client UUID from which to list available roles.
  *     - realm: [optional] The realm where the client scope is defined
  */
 exports.listAvailableClientScopeMappings=function(filter){
@@ -405,9 +405,9 @@ exports.listAvailableClientScopeMappings=function(filter){
  * @parameters:
  * - filter: parameter provided as a JSON object that accepts the following filter:
  *     - id: [required] ID of the client scope.
- *     - client: [required] The client ID (client UUID or client identifier) whose roles are being mapped.
+ *     - clientUniqueId: [required] The client UUID whose roles are being mapped.
  *     - realm : [optional] The realm where the client scope is defined.
- * - RoleRepresentation: An array of role definitions to add. Each RoleRepresentation typically includes(or at least their id and/or name):
+ * - roleRepresentation: An array of role definitions to add. Each RoleRepresentation typically includes(or at least their id and/or name):
  *     - id : [optional] The role ID.
  *     - name : [optional] The role name.
  *     - description: [optional] A description of the role.
@@ -428,7 +428,7 @@ exports.addClientScopeMappings=function(filter,roleRepresentation){
  * @parameters:
  * - filter: parameter provided as a JSON object that accepts the following filter:
  *     - id: [required] ID of the client scope.
- *     - client: [required] The client ID (client UUID or client identifier) from which the roles are being removed.
+ *     - clientUniqueId: [required] The client UUID from which the roles are being removed.
  *     - realm : [optional] The realm where the client scope is defined.
  * - roleRepresentation: An array of role objects (or at least their id and/or name) to be removed from the client scope.
  *     - id : [optional] The role ID
@@ -451,7 +451,7 @@ exports.delClientScopeMappings=function(filter,roleRepresentation){
  * @parameters:
  * - filter: parameter provided as a JSON object that accepts the following filter:
  *     - id: [required] The ID of the client scope
- *     - client: [required]: The client ID (client UUID or client identifier) whose mapped roles you want to list
+ *     - clientUniqueId: [required] The client UUID whose mapped roles you want to list.
  *     - realm: [optional] The realm where the client scope is defined
  */
 exports.listClientScopeMappings=function(filter){
@@ -467,7 +467,7 @@ exports.listClientScopeMappings=function(filter){
  * @parameters:
  * - filter: parameter provided as a JSON object that accepts the following filter:
  *     - id: [required] The ID of the client scope.
- *     - client: [required]: The client ID (client UUID or client identifier) whose mapped roles you want to list.
+ *     - clientUniqueId: [required] The client UUID whose mapped roles you want to list.
  *     - realm: [optional] The realm where the client scope is defined.
  */
 exports.listCompositeClientScopeMappings=function(filter){
@@ -522,15 +522,15 @@ exports.addRealmScopeMappings=function(filter,roleRepresentation){
  * - filter: parameter provided as a JSON object that accepts the following filter:
  *     - id: [required] The ID of the client scope.
  *     - realm: [optional] The realm where the client scope is defined.
- * - RoleRepresentation: Each role should include at least its id and/or name
+ * - roleRepresentation: Each role should include at least its id and/or name
  *     - id: [required] The role ID.
  *     - name: [required] The role name.
  *     - description: [optional] Description of the role.
  *     - clientRole: [optional] Should be false for realm roles.
  *     - containerId: [optional] The ID of the realm containing the role.
  */
-exports.delRealmScopeMappings=function(filter,RoleRepresentation){
- return (kcAdminClientHandler.clientScopes.delRealmScopeMappings(filter,RoleRepresentation));
+exports.delRealmScopeMappings=function(filter,roleRepresentation){
+ return (kcAdminClientHandler.clientScopes.delRealmScopeMappings(filter,roleRepresentation));
 }
 
 

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/groupsHandler.js

@@ -14,10 +14,11 @@ exports.setKcAdminClient=function(kcAdminClient){
 
 /**
  * ***************************** - CREATE - *******************************
- * Create a new group in the current realme
+ * Create a new group in the current realm.
   * @parameters:
  * - groupRepresentation:An object representing the new state of the group. You can update properties such as:
- *     - name: [optional] New name of the group
+ *     - name: [required] Group name.
+ *     - parentId: [optional] Parent group id. If provided, the group is created as a child group.
  *     - attributes: [optional] Custom attributes up field
  *     - path: [optional] full path of the group
  *     - subGroups: [optional] List of child groups (can also be updated separately)

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/rolesHandler.js

@@ -55,7 +55,7 @@ exports.createComposite=function(filters,roles){
  *      - realm (string, optional: if set globally in the client): The realm from which to retrieve roles.
  *      - first (number, optional): Index of the first result to return (used for pagination).
  *      - max (number, optional): Maximum number of results to return.
- *      - name (string, optional): Search string to filter roles by name.
+ *      - search (string, optional): Search string to filter roles by name.
  */
 exports.find=function(filters){
  return (kcAdminClientHandler.roles.find(filters));
@@ -81,7 +81,7 @@ exports.findOneByName=function(filters){
  * Get a role by its Id
  * @parameters:
  * - filters: parameter provided as a JSON object that accepts the following parameters:
- *     - Id (string, required) — The Id of the role to retrieve.
+ *     - id (string, required) — The Id of the role to retrieve.
  *     - realm (string, optional if set globally) — The realm where the role is defined.
  */
 exports.findOneById=function(filters){
@@ -94,7 +94,7 @@ exports.findOneById=function(filters){
  * Update a role by its name
  * @parameters:
  * - filters: parameter provided as a JSON object that accepts the following parameters:
- *     - name (string, required) — The exact name of the role to retrieve.
+ *     - name (string, required) — The exact name of the role to update.
  *     - realm (string, optional if set globally) — The realm where the role is defined.
  * - role_dictionary: A JSON object representing a role dictionary as defined in Keycloak
  */
@@ -109,7 +109,7 @@ exports.updateByName=function(filters,role_dictionary){
  * Update a role by its Id
  * @parameters:
  * - filters: parameter provided as a JSON object that accepts the following parameters:
- *     - name (string, required) — The exact name of the role to retrieve.
+ *     - id (string, required) — The Id of the role to update.
  *     - realm (string, optional if set globally) — The realm where the role is defined.
  * - role_dictionary: A JSON object representing a role dictionary as defined in Keycloak
  */
@@ -134,8 +134,8 @@ exports.delByName=function(filters){
  * ***************************** - findUsersWithRole - *******************************
  * Find all users associated with a specific role
  * - filters: parameter provided as a JSON object that accepts the following parameters:
- *     - name: (string, optional) — The exact name of the role to retrieve.
- *     - id: (string, optional) — The Id of the role to retrieve.
+ *     - name: (string, required) — The exact name of the role.
+ *     - id: (string, optional) — Optional role id depending on endpoint support.
  *     - realm: (string, optional if set globally) — The realm where the role is defined.
  */
 exports.findUsersWithRole=function(filters){
@@ -148,8 +148,8 @@ exports.findUsersWithRole=function(filters){
  * ***************************** - getCompositeRoles - *******************************
  * Find all composite roles associated with a specific role.
  * - filters: parameter provided as a JSON object that accepts the following parameters:
- *     - name: (string, optional) — The exact name of the role to retrieve.
- *     - id: (string, optional) — The Id of the role to retrieve.
+ *     - id: (string, required) — The Id of the role to retrieve.
+ *     - realm: (string, optional) — Realm override.
  */
 exports.getCompositeRoles=function(filters){
  return (kcAdminClientHandler.roles.getCompositeRoles(filters));
@@ -161,13 +161,14 @@ exports.getCompositeRoles=function(filters){
  * associated with a given composite role.
  * When a role is defined as composite, it can include other roles either from the same
  * realm or from different clients. This specific method returns only the realm-level roles
- * that have been added to the composite role. It requires the roleId of the target role as a
+ * that have been added to the composite role. It requires the id of the target role as a
  * parameter and returns an array of RoleRepresentation objects. If the role is not composite
  * or has no associated realm roles, the result will be an empty array. This method is useful
  * for understanding and managing hierarchical role structures within a realm in Keycloak.
  * @parameters:
  * - filters: parameter provided as a JSON object that accepts the following parameters:
- *     - roleId: (string, required) — The Id of the role to retrieve
+ *     - id: (string, required) — The Id of the role to retrieve.
+ *     - realm: (string, optional) — Realm override.
  */
 exports.getCompositeRolesForRealm=function(filters){
  return (kcAdminClientHandler.roles.getCompositeRolesForRealm(filters));
@@ -180,14 +181,15 @@ exports.getCompositeRolesForRealm=function(filters){
  * associated with a given composite role.
  * Composite roles in Keycloak can include roles from different clients,
  * and this method specifically returns the roles belonging to a specified client that
- * are part of the composite role. It requires the roleId of the composite role
+ * are part of the composite role. It requires the id of the composite role
  * and the clientId of the client whose roles you want to retrieve. The function returns an array of
  * RoleRepresentation objects representing the client roles included in the composite.
  * This helps manage and inspect client-specific role hierarchies within the composite role structure in Keycloak.
  * @parameters:
  * - filters: parameter provided as a JSON object that accepts the following parameters:
- *     - roleId: (string, required) — The Id of the role to retrieve
+ *     - id: (string, required) — The Id of the role to retrieve.
  *     - clientId: (string, required) — The Id of the client to search for composite roles
+ *     - realm: (string, optional) — Realm override.
  *
  */
 exports.getCompositeRolesForClient=function(filters){

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,8 @@
 # OIDC Methods Migration Plan - keycloak-api-manager
 
-## 🚀 Current Status: v6.0.0 - MIGRATION RELEASED
+## 🚀 Current Status: v6.0.1 - Migration Released
 
-✅ **OIDC Methods Deprecated:** All OIDC authentication methods are now marked `@deprecated` in v6.0.0.
+✅ **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.
 
@@ -14,7 +14,7 @@
 
 ## 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)
 
@@ -24,7 +24,7 @@ L'architettura prevede una **migrazione pianificata** dei metodi OIDC (`auth()`,
 - ✅ `generateAuthorizationUrl(options)` - PKCE URL generator
 - ✅ `loginPKCE(credentials)` - PKCE token exchange
 
-## Current State (v6.0.0) - NOW
+## Current State (v6.0.1) - NOW
 
 **Status Changes in keycloak-api-manager:**
 - ⚠️ `auth(credentials)` - Marked @deprecated
@@ -125,7 +125,7 @@ keycloak-express-middleware (User Authentication)
 | Version | OIDC Methods | Status |
 |---------|------------|--------|
 | v5.0.8 | Supported | Legacy (should migrate) |
-| v6.0.0 | Deprecated | Current (shows warnings) |
+| v6.0.1 | Deprecated | Current (shows warnings) |
 | v7.0.0 | Removed | Future (no OIDC methods) |
 
 **NPM:** https://www.npmjs.com/package/keycloak-api-manager
@@ -225,16 +225,6 @@ const token = await keycloakMiddleware.loginPKCE({
 });
 ```
 
-**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

package/README.md

@@ -54,7 +54,7 @@ console.log(users.length);
 KeycloakManager.stop();
 ```
 
-> **💡 Tip:** For user authentication (login with credentials, PKCE flow, token exchange), use [`keycloak-express-middleware`](https://github.com/smartenv-crs4/keycloak-express-middleware) instead. See [PKCE Login Flow Guide](docs/guides/PKCE-Login-Flow.md#-migration-to-keycloak-express-middleware-recommended) for migration examples.
+> **💡 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
 
@@ -102,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
 
@@ -163,7 +163,7 @@ docs/               # Centralized documentation
 
 ## Versioning and Compatibility
 
-- Package version: `6.0.0`
+- Package version: `6.0.2`
 - Keycloak Admin client dependency: `@keycloak/keycloak-admin-client`
 - Main compatibility target: Keycloak 25/26
 

package/docs/api/attack-detection.md

@@ -2,41 +2,107 @@
 
 Brute-force and login-failure management endpoints.
 
-**Namespace:** `KeycloakManager.attackDetection`
+Namespace: KeycloakManager.attackDetection
+
+## Overview
+
+This handler wraps Keycloak Attack Detection endpoints used to:
+
+- Inspect lock/failure status.
+- Clear failures for one user.
+- Clear failures for the entire realm.
+
+These operations are usually used by support/admin tooling and automated account recovery flows.
 
 ## Methods
 
 ### getBruteForceStatus(filter)
-Get brute-force status for all users or query context depending on endpoint wrapper.
 
-- **Optional**: realm context fields
-- **Returns**: Promise<object>
+Read global brute-force status context from the configured realm.
+
+Parameters:
+
+- filter (object, optional):
+- realm (string, optional): override target realm for this call.
+
+Returns:
+
+- Promise<object>: realm brute-force status payload returned by Keycloak.
+
+Example:
+
+```js
+const status = await KeycloakManager.attackDetection.getBruteForceStatus();
+console.log(status);
+```
 
 ### getUserBruteForceStatus(filter)
-Get brute-force status for one user.
 
-- **Required**: `filter.userId` (or `filter.id` based on wrapper usage)
-- **Returns**: Promise<object>
+Read brute-force status for one user.
+
+Parameters:
+
+- filter (object, required):
+- id (string, required): user id.
+- realm (string, optional): override target realm.
+
+Returns:
+
+- Promise<object>: user brute-force state (for example temporary lock status, failures metadata).
+
+Example:
+
+```js
+const userStatus = await KeycloakManager.attackDetection.getUserBruteForceStatus({
+	id: userId,
+});
+```
 
 ### clearUserLoginFailures(filter)
-Clear failed login attempts for one user.
 
-- **Required**: `filter.userId` (or equivalent id field)
-- **Returns**: Promise<void>
+Clear failed-login counters for one user.
+
+Parameters:
+
+- filter (object, required):
+- id (string, required): user id.
+- realm (string, optional): override target realm.
+
+Returns:
+
+- Promise<void>
+
+Example:
+
+```js
+await KeycloakManager.attackDetection.clearUserLoginFailures({ id: userId });
+```
 
 ### clearAllLoginFailures(filter)
-Clear failed login attempts for all users in realm.
 
-- **Optional**: realm context fields
-- **Returns**: Promise<void>
+Clear failed-login counters for all users in the realm.
+
+Parameters:
+
+- filter (object, optional):
+- realm (string, optional): override target realm.
+
+Returns:
 
-## Example
+- Promise<void>
+
+Example:
 
 ```js
-const status = await KeycloakManager.attackDetection.getUserBruteForceStatus({ userId });
-await KeycloakManager.attackDetection.clearUserLoginFailures({ userId });
+await KeycloakManager.attackDetection.clearAllLoginFailures();
 ```
 
+## Error Notes
+
+- Some Keycloak distributions/versions may not expose attack-detection endpoints in the same way.
+- If endpoint support is missing, Keycloak may return 404.
+
 ## See Also
+
 - [API Reference](../api-reference.md)
 - [Users](users.md)