keycloak-api-manager 6.0.2 → 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/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/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/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/README.md

@@ -163,7 +163,7 @@ docs/               # Centralized documentation
 
 ## Versioning and Compatibility
 
-- Package version: `6.0.1`
+- 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)