keycloak-api-manager 5.0.0 → 5.0.2

package/Handlers/groupsHandler.js

@@ -1,4 +1,3 @@
-const Keycloak = require("keycloak-connect");
 /**
  * **************************************************************************************************
  * **************************************************************************************************

package/Handlers/rolesHandler.js

@@ -1,4 +1,3 @@
-const Keycloak = require("keycloak-connect");
 /**
  * **************************************************************************************************
  * **************************************************************************************************

package/README.md

@@ -89,6 +89,22 @@ Configured handler namespaces:
 
 All documentation is centralized under `docs/`.
 
+- [API Reference (Index)](docs/api-reference.md)
+- [API - Configuration](docs/api/configuration.md)
+- [API - Realms](docs/api/realms.md)
+- [API - Users](docs/api/users.md)
+- [API - Clients](docs/api/clients.md)
+- [API - Client Scopes](docs/api/client-scopes.md)
+- [API - Groups](docs/api/groups.md)
+- [API - Roles](docs/api/roles.md)
+- [API - Identity Providers](docs/api/identity-providers.md)
+- [API - Components](docs/api/components.md)
+- [API - Authentication Management](docs/api/authentication-management.md)
+- [API - Attack Detection](docs/api/attack-detection.md)
+- [API - Organizations](docs/api/organizations.md)
+- [API - User Profile](docs/api/user-profile.md)
+- [API - Client Policies](docs/api/client-policies.md)
+- [API - Server Info](docs/api/server-info.md)
 - [Architecture and Runtime](docs/architecture.md)
 - [Keycloak Setup and Feature Flags](docs/keycloak-setup.md)
 - [Testing Guide](docs/testing.md)
@@ -125,7 +141,7 @@ docs/               # Centralized documentation
 
 ## Versioning and Compatibility
 
-- Package version: `4.1.0`
+- Package version: `5.0.1`
 - Keycloak Admin client dependency: `@keycloak/keycloak-admin-client`
 - Main compatibility target: Keycloak 25/26
 

package/docs/api/attack-detection.md

@@ -0,0 +1,42 @@
+# Attack Detection API
+
+Brute-force and login-failure management endpoints.
+
+**Namespace:** `KeycloakManager.attackDetection`
+
+## Methods
+
+### getBruteForceStatus(filter)
+Get brute-force status for all users or query context depending on endpoint wrapper.
+
+- **Optional**: realm context fields
+- **Returns**: Promise<object>
+
+### getUserBruteForceStatus(filter)
+Get brute-force status for one user.
+
+- **Required**: `filter.userId` (or `filter.id` based on wrapper usage)
+- **Returns**: Promise<object>
+
+### clearUserLoginFailures(filter)
+Clear failed login attempts for one user.
+
+- **Required**: `filter.userId` (or equivalent id field)
+- **Returns**: Promise<void>
+
+### clearAllLoginFailures(filter)
+Clear failed login attempts for all users in realm.
+
+- **Optional**: realm context fields
+- **Returns**: Promise<void>
+
+## Example
+
+```js
+const status = await KeycloakManager.attackDetection.getUserBruteForceStatus({ userId });
+await KeycloakManager.attackDetection.clearUserLoginFailures({ userId });
+```
+
+## See Also
+- [API Reference](../api-reference.md)
+- [Users](users.md)

package/docs/api/authentication-management.md

@@ -0,0 +1,160 @@
+# Authentication Management API
+
+Manage required actions, authentication flows, executions, and execution configs.
+
+**Namespace:** `KeycloakManager.authenticationManagement`
+
+## 1) Required Actions
+
+### getRequiredActions()
+- **Returns**: Promise<Array<object>>
+
+### getUnregisteredRequiredActions()
+- **Returns**: Promise<Array<object>>
+
+### registerRequiredAction(actionRepresentation)
+- **Required**: `alias`, `name`, `providerId`
+- **Optional**: `defaultAction`, `enabled`, `priority`, `config`
+- **Returns**: Promise<void>
+
+### getRequiredActionForAlias(filter)
+- **Required**: `filter.alias`
+- **Returns**: Promise<object>
+
+### updateRequiredAction(filter, actionRepresentation)
+- **Required**: `filter.alias`
+- **Required**: updated representation
+- **Returns**: Promise<void>
+
+### deleteRequiredAction(filter)
+- **Required**: `filter.alias`
+- **Returns**: Promise<void>
+
+### raiseRequiredActionPriority(filter)
+### lowerRequiredActionPriority(filter)
+- **Required**: `filter.alias`
+- **Returns**: Promise<void>
+
+### getRequiredActionConfigDescription(filter)
+- **Required**: `filter.alias`
+- **Returns**: Promise<object>
+
+### getRequiredActionConfig(filter)
+- **Required**: `filter.alias`
+- **Returns**: Promise<object>
+
+### updateRequiredActionConfig(filter, actionConfigRepresentation)
+- **Required**: `filter.alias`
+- **Required**: config representation
+- **Returns**: Promise<void>
+
+### removeRequiredActionConfig(filter)
+- **Required**: `filter.alias`
+- **Returns**: Promise<void>
+
+## 2) Authenticator / Provider Discovery
+
+### getClientAuthenticatorProviders()
+### getFormActionProviders()
+### getAuthenticatorProviders()
+### getFormProviders()
+- **Params**: none
+- **Returns**: Promise<Array<object>>
+
+## 3) Authentication Flows
+
+### getFlows()
+- **Returns**: Promise<Array<object>>
+
+### createFlow(flowRepresentation)
+- **Required**: `alias`, `providerId`, `topLevel`, `builtIn`
+- **Optional**: `description`
+- **Returns**: Promise<void>
+
+### updateFlow(filter, flowRepresentation)
+- **Required**: `filter.id` or `filter.alias` (as expected by endpoint)
+- **Required**: representation
+- **Returns**: Promise<void>
+
+### deleteFlow(filter)
+- **Required**: flow identifier (`id` or `alias`, per endpoint)
+- **Returns**: Promise<void>
+
+### copyFlow(filter)
+- **Required**: source flow id/alias
+- **Required**: `filter.newName`
+- **Returns**: Promise<void>
+
+### getFlow(filter)
+- **Required**: flow identifier
+- **Returns**: Promise<object>
+
+## 4) Flow Executions
+
+### getExecutions(filter)
+- **Required**: `filter.flowAlias`
+- **Returns**: Promise<Array<object>>
+
+### addExecutionToFlow(filter)
+- **Required**: `filter.flowAlias`
+- **Required**: `filter.provider`
+- **Returns**: Promise<void>
+
+### addFlowToFlow(filter)
+- **Required**: `filter.flowAlias`
+- **Required**: nested flow payload
+- **Returns**: Promise<void>
+
+### updateExecution(filter, executionRepresentation)
+- **Required**: execution reference fields
+- **Required**: execution representation
+- **Returns**: Promise<void>
+
+### delExecution(filter)
+- **Required**: execution id reference
+- **Returns**: Promise<void>
+
+### raisePriorityExecution(filter)
+### lowerPriorityExecution(filter)
+- **Required**: execution reference fields
+- **Returns**: Promise<void>
+
+## 5) Execution Config
+
+### createConfig(filter)
+- **Required**: execution reference + config payload
+- **Returns**: Promise<object>
+
+### getConfig(filter)
+- **Required**: `filter.id` (config id)
+- **Returns**: Promise<object>
+
+### updateConfig(filter)
+- **Required**: config id + updated payload
+- **Returns**: Promise<void>
+
+### delConfig(filter)
+- **Required**: `filter.id` (config id)
+- **Returns**: Promise<void>
+
+### getConfigDescription(filter)
+- **Required**: provider id / execution reference as required by endpoint
+- **Returns**: Promise<object>
+
+## Example
+
+```js
+const flows = await KeycloakManager.authenticationManagement.getFlows();
+
+await KeycloakManager.authenticationManagement.createFlow({
+  alias: 'custom-browser',
+  description: 'Custom browser flow',
+  providerId: 'basic-flow',
+  topLevel: true,
+  builtIn: false
+});
+```
+
+## See Also
+- [API Reference](../api-reference.md)
+- [Realms](realms.md)

package/docs/api/client-policies.md

@@ -0,0 +1,66 @@
+# Client Policies API
+
+Manage Client Policies and Client Profiles.
+
+**Namespace:** `KeycloakManager.clientPolicies`  
+**Required Feature Flag:** `client-policies`
+
+## Methods
+
+### getPolicies(filter)
+Get current client policies configuration.
+
+- **Optional**: realm context fields
+- **Returns**: Promise<object>
+
+### updatePolicies(filter, policiesRepresentation)
+Update client policies.
+
+- **Optional**: realm context fields
+- **Required**: `policiesRepresentation` (full/partial policies object)
+- **Returns**: Promise<void|object>
+
+### getProfiles(filter)
+Get current client profiles configuration.
+
+- **Optional**: realm context fields
+- **Returns**: Promise<object>
+
+### updateProfiles(filter, profilesRepresentation)
+Update client profiles.
+
+- **Optional**: realm context fields
+- **Required**: `profilesRepresentation`
+- **Returns**: Promise<void|object>
+
+## Feature Enablement
+
+Run Keycloak with:
+
+```bash
+--features=client-policies
+```
+
+## Example
+
+```js
+const policies = await KeycloakManager.clientPolicies.getPolicies();
+
+await KeycloakManager.clientPolicies.updatePolicies({}, {
+  ...policies,
+  policies: [
+    ...(policies.policies || []),
+    {
+      name: 'enforce-pkce',
+      description: 'Require PKCE',
+      enabled: true,
+      conditions: [{ condition: 'client-access-type', configuration: { type: ['PUBLIC'] } }],
+      profiles: ['pkce-profile']
+    }
+  ]
+});
+```
+
+## See Also
+- [API Reference](../api-reference.md)
+- [Clients](clients.md)

package/docs/api/client-scopes.md

@@ -0,0 +1,194 @@
+# Client Scopes API
+
+Manage client scopes, protocol mappers, and role scope mappings.
+
+**Namespace:** `KeycloakManager.clientScopes`
+
+## Scope CRUD
+
+### create(scopeRepresentation)
+- **Required**: `scopeRepresentation.name` (string)
+- **Optional**: `description`, `protocol` (`openid-connect` or `saml`), `attributes`
+- **Returns**: Promise<object>
+
+### find(filter)
+- **Optional**: `search`, `first`, `max`
+- **Returns**: Promise<Array<ClientScopeRepresentation>>
+
+### findOne(filter)
+- **Required**: `filter.id` (scope id)
+- **Returns**: Promise<ClientScopeRepresentation>
+
+### findOneByName(filter)
+- **Required**: `filter.name` (scope name)
+- **Returns**: Promise<ClientScopeRepresentation|null>
+
+### update(filter, scopeRepresentation)
+- **Required**: `filter.id` (scope id)
+- **Required**: `scopeRepresentation` (partial)
+- **Returns**: Promise<void>
+
+### del(filter)
+- **Required**: `filter.id` (scope id)
+- **Returns**: Promise<void>
+
+### delByName(filter)
+- **Required**: `filter.name` (scope name)
+- **Returns**: Promise<void>
+
+## Realm Default Scopes
+
+### listDefaultClientScopes(filter)
+- **Optional**: `filter.realm`
+- **Returns**: Promise<Array<ClientScopeRepresentation>>
+
+### addDefaultClientScope(filter)
+- **Required**: `filter.id` (scope id)
+- **Returns**: Promise<void>
+
+### delDefaultClientScope(filter)
+- **Required**: `filter.id` (scope id)
+- **Returns**: Promise<void>
+
+### listDefaultOptionalClientScopes(filter)
+- **Optional**: `filter.realm`
+- **Returns**: Promise<Array<ClientScopeRepresentation>>
+
+### addDefaultOptionalClientScope(filter)
+- **Required**: `filter.id` (scope id)
+- **Returns**: Promise<void>
+
+### delDefaultOptionalClientScope(filter)
+- **Required**: `filter.id` (scope id)
+- **Returns**: Promise<void>
+
+## Protocol Mappers
+
+### listProtocolMappers(filter)
+- **Required**: `filter.id` (scope id)
+- **Returns**: Promise<Array<ProtocolMapperRepresentation>>
+
+### findProtocolMapper(filter)
+- **Required**: `filter.id` (scope id)
+- **Required**: `filter.mapperId` (mapper id)
+- **Returns**: Promise<ProtocolMapperRepresentation>
+
+### findProtocolMapperByName(filter)
+- **Required**: `filter.id` (scope id)
+- **Required**: `filter.name` (mapper name)
+- **Returns**: Promise<ProtocolMapperRepresentation>
+
+### findProtocolMappersByProtocol(filter)
+- **Required**: `filter.id` (scope id)
+- **Required**: `filter.protocol` (`openid-connect` or `saml`)
+- **Returns**: Promise<Array<ProtocolMapperRepresentation>>
+
+### addProtocolMapper(filter, protocolMapper)
+- **Required**: `filter.id` (scope id)
+- **Required**: `protocolMapper.name`
+- **Required**: `protocolMapper.protocol`
+- **Required**: `protocolMapper.protocolMapper`
+- **Optional**: `protocolMapper.config`
+- **Returns**: Promise<object>
+
+### addMultipleProtocolMappers(filter, protocolMappers)
+- **Required**: `filter.id` (scope id)
+- **Required**: `protocolMappers` (Array<ProtocolMapperRepresentation>)
+- **Returns**: Promise<void>
+
+### updateProtocolMapper(filter, protocolMapper)
+- **Required**: `filter.id` (scope id)
+- **Required**: `filter.mapperId` (mapper id)
+- **Required**: `protocolMapper` (updated representation)
+- **Returns**: Promise<void>
+
+### delProtocolMapper(filter)
+- **Required**: `filter.id` (scope id)
+- **Required**: `filter.mapperId` (mapper id)
+- **Returns**: Promise<void>
+
+## Client Scope Role Mappings (for one client scope)
+
+### listScopeMappings(filter)
+- **Required**: `filter.id` (scope id)
+- **Returns**: Promise<object>
+
+### listAvailableClientScopeMappings(filter)
+- **Required**: `filter.id` (scope id)
+- **Required**: `filter.clientUniqueId` (client UUID)
+- **Returns**: Promise<Array<RoleRepresentation>>
+
+### addClientScopeMappings(filter, roleRepresentation)
+- **Required**: `filter.id` (scope id)
+- **Required**: `filter.clientUniqueId` (client UUID)
+- **Required**: `roleRepresentation` (Array<{id,name}> or role-like object depending on endpoint)
+- **Returns**: Promise<void>
+
+### delClientScopeMappings(filter, roleRepresentation)
+- **Required**: `filter.id` (scope id)
+- **Required**: `filter.clientUniqueId` (client UUID)
+- **Required**: `roleRepresentation`
+- **Returns**: Promise<void>
+
+### listClientScopeMappings(filter)
+- **Required**: `filter.id` (scope id)
+- **Required**: `filter.clientUniqueId` (client UUID)
+- **Returns**: Promise<Array<RoleRepresentation>>
+
+### listCompositeClientScopeMappings(filter)
+- **Required**: `filter.id` (scope id)
+- **Required**: `filter.clientUniqueId` (client UUID)
+- **Returns**: Promise<Array<RoleRepresentation>>
+
+## Realm Scope Mappings (for one client scope)
+
+### listAvailableRealmScopeMappings(filter)
+- **Required**: `filter.id` (scope id)
+- **Returns**: Promise<Array<RoleRepresentation>>
+
+### addRealmScopeMappings(filter, roleRepresentation)
+- **Required**: `filter.id` (scope id)
+- **Required**: `roleRepresentation`
+- **Returns**: Promise<void>
+
+### delRealmScopeMappings(filter, RoleRepresentation)
+- **Required**: `filter.id` (scope id)
+- **Required**: `RoleRepresentation`
+- **Returns**: Promise<void>
+
+### listRealmScopeMappings(filter)
+- **Required**: `filter.id` (scope id)
+- **Returns**: Promise<Array<RoleRepresentation>>
+
+### listCompositeRealmScopeMappings(filter)
+- **Required**: `filter.id` (scope id)
+- **Returns**: Promise<Array<RoleRepresentation>>
+
+## Example
+
+```js
+const scope = await KeycloakManager.clientScopes.create({
+  name: 'profile-extended',
+  protocol: 'openid-connect'
+});
+
+await KeycloakManager.clientScopes.addProtocolMapper(
+  { id: scope.id },
+  {
+    name: 'department',
+    protocol: 'openid-connect',
+    protocolMapper: 'oidc-usermodel-attribute-mapper',
+    config: {
+      'user.attribute': 'department',
+      'claim.name': 'department',
+      'jsonType.label': 'String',
+      'id.token.claim': 'true',
+      'access.token.claim': 'true'
+    }
+  }
+);
+```
+
+## See Also
+- [API Reference](../api-reference.md)
+- [Clients](clients.md)