keycloak-api-manager 6.0.2 → 6.0.4

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

@@ -25,11 +25,13 @@ 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.
+## OIDC Deprecation Notice
+
+DEPRECATION NOTICE (v6.0.0): The OIDC authentication methods (login(), loginPKCE(), generateAuthorizationUrl(), auth()) have been deprecated and moved to 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
 
@@ -46,6 +48,8 @@ await KeycloakManager.configure({
   tokenLifeSpan: 60
 });
 
+// Alternative after configure(): update runtime context (for example realm)
+// without re-authenticating or calling configure() again.
 KeycloakManager.setConfig({ realmName: 'my-realm' });
 
 const users = await KeycloakManager.users.find({ max: 20 });
@@ -54,19 +58,41 @@ 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:
+Some APIs exposed by this package depend on Keycloak server features that are disabled by default. Enable these flags when you want full endpoint coverage (local dev, CI, or production environments that use these modules):
 
 ```bash
 --features=admin-fine-grained-authz:v1,organization,client-policies
 ```
 
-### Why `admin-fine-grained-authz:v1`
+What each flag is for:
+
+- `admin-fine-grained-authz:v1`: enables management-permissions endpoints used by group/user fine-grained permission flows.
+- `organization`: enables Organizations APIs.
+- `client-policies`: enables Client Policies and Client Profiles APIs.
+
+When you can skip them:
+
+- If you only use core admin operations (for example realms/users/clients CRUD), the package still works without these flags.
+- If you use `organizations`, `clientPolicies`, or management-permissions methods, these flags are required.
+
+### Why `admin-fine-grained-authz:v1` in Keycloak 26.x
 
-In Keycloak 26.x, management-permissions APIs used by group/user fine-grained tests are compatible with `v1`.
+In Keycloak 26.x, the management-permissions APIs used by this package are compatible with the `v1` variant, so `admin-fine-grained-authz:v1` is the recommended setting.
+
+### Example (Docker)
+
+```bash
+docker run -d --name keycloak \
+  -p 8080:8080 \
+  -e KEYCLOAK_ADMIN=admin \
+  -e KEYCLOAK_ADMIN_PASSWORD=admin \
+  -e KC_FEATURES=admin-fine-grained-authz:v1,organization,client-policies \
+  quay.io/keycloak/keycloak:latest start-dev
+```
+
+See [Keycloak Setup and Feature Flags](docs/keycloak-setup.md) for full setup details.
 
 ## Public API Entry Points
 
@@ -74,12 +100,6 @@ In Keycloak 26.x, management-permissions APIs used by group/user fine-grained te
 - `setConfig(overrides)`
 - `getToken()`
 - `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
-
-**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:
 
@@ -104,7 +124,7 @@ All documentation is centralized under `docs/`.
 
 ### Guides
 
-- [OIDC Migration Plan](OIDC_MIGRATION_PLAN.md) - Deprecation status and migration notes to keycloak-express-middleware
+- [OIDC Migration Plan](OIDC_MIGRATION_PLAN.md) - Migration notes for legacy OIDC helpers
 
 ### API Reference
 
@@ -129,13 +149,13 @@ All documentation is centralized under `docs/`.
 
 - [Architecture and Runtime](docs/architecture.md)
 - [Keycloak Setup and Feature Flags](docs/keycloak-setup.md)
-- [Testing Guide](docs/testing.md)
-- [Test Configuration](docs/test-configuration.md)
+- [Testing Guide](docs/testing.md) — setup, configuration, commands, and test architecture
 - [Deployment (Local/Remote, HTTP/HTTPS)](docs/deployment.md)
 
 ## Testing
 
 ```bash
+npm run setup-keycloak
 npm test
 ```
 
@@ -145,6 +165,8 @@ Or test workspace only:
 npm --prefix test test
 ```
 
+`npm run setup-keycloak` is an interactive helper that can start Keycloak via Docker Compose (local/remote, HTTP/HTTPS) and update the test `baseUrl` in config.
+
 The suite runs against a real Keycloak instance and provisions a shared test realm during setup.
 
 ## Repository Structure
@@ -163,14 +185,13 @@ docs/               # Centralized documentation
 
 ## Versioning and Compatibility
 
-- Package version: `6.0.1`
+- Package version: `6.0.3`
 - 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.
+See OIDC Deprecation Notice.
 
 ## License
 

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)