keycloak-api-manager 4.0.0 → 5.0.0

package/Handlers/attackDetectionHandler.js

@@ -0,0 +1,64 @@
+/**
+ * **************************************************************************************************
+ * **************************************************************************************************
+ * The Attack Detection entity provides functionality for managing brute force attack detection
+ * in Keycloak. This allows you to detect and prevent brute force login attempts, lock users,
+ * and clear login failures.
+ * **************************************************************************************************
+ * **************************************************************************************************
+ */
+let kcAdminClientHandler = null;
+
+exports.setKcAdminClient = function(kcAdminClient) {
+    kcAdminClientHandler = kcAdminClient;
+}
+
+/**
+ * ***************************** - getBruteForceStatus - *******************************
+ * Get brute force detection status for all users in a realm
+ * 
+ * @parameters:
+ * - realm: (string, required) - The realm name
+ * @returns: Array of user brute force status objects
+ */
+exports.getBruteForceStatus = function(filter) {
+    return kcAdminClientHandler.attackDetection.findAll(filter);
+}
+
+/**
+ * ***************************** - getUserBruteForceStatus - *******************************
+ * Get brute force detection status for a specific user
+ * 
+ * @parameters:
+ * - realm: (string, required) - The realm name  
+ * - id: (string, required) - The user ID
+ * @returns: User brute force status object
+ */
+exports.getUserBruteForceStatus = function(filter) {
+    return kcAdminClientHandler.attackDetection.findOne(filter);
+}
+
+/**
+ * ***************************** - clearUserLoginFailures - *******************************
+ * Clear all login failures for a specific user
+ * 
+ * @parameters:
+ * - realm: (string, required) - The realm name
+ * - id: (string, required) - The user ID
+ * @returns: Promise
+ */
+exports.clearUserLoginFailures = function(filter) {
+    return kcAdminClientHandler.attackDetection.del(filter);
+}
+
+/**
+ * ***************************** - clearAllLoginFailures - *******************************
+ * Clear all login failures for all users in a realm
+ * 
+ * @parameters:
+ * - realm: (string, required) - The realm name
+ * @returns: Promise
+ */
+exports.clearAllLoginFailures = function(filter) {
+    return kcAdminClientHandler.attackDetection.delAll(filter);
+}

package/Handlers/clientPoliciesHandler.js

@@ -0,0 +1,120 @@
+/**
+ * **************************************************************************************************
+ * **************************************************************************************************
+ * The Client Policies entity (Keycloak 12+) provides governance and security policies
+ * for client applications. Client policies allow administrators to enforce security
+ * requirements, configure client behavior, and ensure compliance across all clients.
+ * **************************************************************************************************
+ * **************************************************************************************************
+ */
+let kcAdminClientHandler = null;
+
+exports.setKcAdminClient = function(kcAdminClient) {
+    kcAdminClientHandler = kcAdminClient;
+}
+
+/**
+ * ***************************** - getPolicies - *******************************
+ * Get all client policies for a realm
+ * 
+ * @parameters:
+ * - filter: [optional] parameter
+ *   - realm: (string, optional) - The realm name
+ * @returns: Object containing policies array
+ */
+exports.getPolicies = function(filter) {
+    return kcAdminClientHandler.clientPolicies.listPolicies(filter);
+}
+
+/**
+ * ***************************** - updatePolicies - *******************************
+ * Update client policies configuration
+ * 
+ * @parameters:
+ * - filter: [optional] parameter
+ *   - realm: (string, optional) - The realm name
+ * - policiesRepresentation: Object with policies array
+ *   - policies: (array) - Array of policy objects
+ *     - name: (string) - Policy name
+ *     - description: (string) - Policy description
+ *     - enabled: (boolean) - Whether policy is enabled
+ *     - conditions: (array) - Conditions that trigger the policy
+ *     - 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
+    const realm = filter?.realm || kcAdminClientHandler.realmName;
+    const baseUrl = kcAdminClientHandler.baseUrl;
+    const token = kcAdminClientHandler.accessToken;
+    
+    const url = `${baseUrl}/admin/realms/${realm}/client-policies/policies`;
+    
+    const response = await fetch(url, {
+        method: 'PUT',
+        headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${token}`
+        },
+        body: JSON.stringify(policiesRepresentation)
+    });
+    
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Failed to update client policies: ${error}`);
+    }
+    
+    return response.status === 204 ? undefined : response.json();
+}
+
+/**
+ * ***************************** - getProfiles - *******************************
+ * Get all client profiles for a realm
+ * 
+ * @parameters:
+ * - filter: [optional] parameter
+ *   - realm: (string, optional) - The realm name
+ * @returns: Object containing profiles array
+ */
+exports.getProfiles = function(filter) {
+    return kcAdminClientHandler.clientPolicies.listProfiles(filter);
+}
+
+/**
+ * ***************************** - updateProfiles - *******************************
+ * Update client profiles configuration
+ * 
+ * @parameters:
+ * - filter: [optional] parameter
+ *   - realm: (string, optional) - The realm name
+ * - profilesRepresentation: Object with profiles array
+ *   - profiles: (array) - Array of profile objects
+ *     - name: (string) - Profile name
+ *     - description: (string) - Profile description
+ *     - executors: (array) - Executors that enforce security requirements
+ *       - executor: (string) - Executor type
+ *       - configuration: (object) - Executor-specific configuration
+ */
+exports.updateProfiles = async function(filter, profilesRepresentation) {
+    // Direct API call since @keycloak/keycloak-admin-client doesn't support this
+    const realm = filter?.realm || kcAdminClientHandler.realmName;
+    const baseUrl = kcAdminClientHandler.baseUrl;
+    const token = kcAdminClientHandler.accessToken;
+    
+    const url = `${baseUrl}/admin/realms/${realm}/client-policies/profiles`;
+    
+    const response = await fetch(url, {
+        method: 'PUT',
+        headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${token}`
+        },
+        body: JSON.stringify(profilesRepresentation)
+    });
+    
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Failed to update client profiles: ${error}`);
+    }
+    
+    return response.status === 204 ? undefined : response.json();
+}

package/Handlers/groupsHandler.js

@@ -306,3 +306,35 @@ exports.delClientRoleMappings=function(filters){
  return (kcAdminClientHandler.groups.delClientRoleMappings(filters));
 }
 
+
+/**
+ * ***************************** - setPermissions - *******************************
+ * Enable or update permission settings for a group.
+ * This allows fine-grained control over who can manage group membership and permissions.
+ * @parameters:
+ * - filters: parameter provided as a JSON object that accepts the following parameters:
+ *     - id: [required] The ID of the group
+ * - permissionRepresentation: Object with permission settings
+ *     - enabled: [required] (boolean) Whether permissions are enabled
+ */
+exports.setPermissions=function(filters, permissionRepresentation){
+ return (kcAdminClientHandler.groups.updatePermission(filters, permissionRepresentation));
+}
+
+
+/**
+ * ***************************** - listPermissions - *******************************
+ * Get the current permission settings for a group.
+ * Returns information about who can manage the group, view members, etc.
+ * @parameters:
+ * - filters: parameter provided as a JSON object that accepts the following parameters:
+ *     - id: [required] The ID of the group
+ * @returns: Object with permission configuration including:
+ *     - enabled: (boolean) Whether permissions are enabled
+ *     - resource: (string) Associated authorization resource ID
+ *     - scopePermissions: (object) Map of scope permissions
+ */
+exports.listPermissions=function(filters){
+ return (kcAdminClientHandler.groups.listPermissions(filters));
+}
+

package/Handlers/organizationsHandler.js

@@ -0,0 +1,243 @@
+/**
+ * **************************************************************************************************
+ * **************************************************************************************************
+ * The Organizations entity (Keycloak 25+) allows managing organizations for multi-tenancy.
+ * Organizations provide a way to group users, identity providers, and domains together,
+ * enabling better isolation and management of different organizational units.
+ * 
+ * NOTE: Some Organizations APIs are not fully supported by @keycloak/keycloak-admin-client
+ * so this handler uses direct REST API calls for those endpoints.
+ * **************************************************************************************************
+ * **************************************************************************************************
+ */
+let kcAdminClientHandler = null;
+
+exports.setKcAdminClient = function(kcAdminClient) {
+    kcAdminClientHandler = kcAdminClient;
+}
+
+/**
+ * Helper function to make direct API calls to Keycloak
+ */
+async function makeDirectApiCall(method, endpoint, body = null) {
+    const baseUrl = kcAdminClientHandler.baseUrl;
+    const realmName = kcAdminClientHandler.realmName;
+    const accessToken = kcAdminClientHandler.accessToken;
+    
+    const url = `${baseUrl}/admin/realms/${realmName}${endpoint}`;
+    
+    const options = {
+        method,
+        headers: {
+            'Authorization': `Bearer ${accessToken}`,
+            'Content-Type': 'application/json'
+        }
+    };
+    
+    if (body) {
+        options.body = JSON.stringify(body);
+    }
+    
+    const response = await fetch(url, options);
+    
+    if (!response.ok) {
+        const errorText = await response.text();
+        let errorMessage;
+        try {
+            const errorJson = JSON.parse(errorText);
+            errorMessage = errorJson.errorMessage || errorJson.error || errorText;
+        } catch (e) {
+            errorMessage = errorText;
+        }
+        throw new Error(errorMessage || `HTTP ${response.status}: ${response.statusText}`);
+    }
+    
+    // Handle empty responses (DELETE, PUT requests may return 204 No Content)
+    if (response.status === 204 || response.headers.get('content-length') === '0') {
+        return null;
+    }
+    
+    const responseText = await response.text();
+    if (!responseText) {
+        return null;
+    }
+    
+    return JSON.parse(responseText);
+}
+
+/**
+ * ***************************** - create - *******************************
+ * Create a new organization
+ * 
+ * @parameters:
+ * - organizationRepresentation: An object representing the organization
+ *   - name: [required] (string) - Organization name
+ *   - displayName: [optional] (string) - Display name
+ *   - url: [optional] (string) - Organization URL
+ *   - domains: [optional] (array) - List of domains
+ *   - attributes: [optional] (object) - Custom attributes
+ */
+exports.create = function(organizationRepresentation) {
+    return kcAdminClientHandler.organizations.create(organizationRepresentation);
+}
+
+/**
+ * ***************************** - find - *******************************
+ * Get all organizations in a realm
+ * 
+ * @parameters:
+ * - filter: [optional] parameter for filtering
+ *   - realm: (string, optional) - The realm name
+ *   - search: (string, optional) - Search string
+ *   - first: (number, optional) - First result index
+ *   - max: (number, optional) - Maximum results
+ */
+exports.find = function(filter) {
+    return kcAdminClientHandler.organizations.find(filter);
+}
+
+/**
+ * ***************************** - findOne - *******************************
+ * Get a specific organization by ID
+ * 
+ * @parameters:
+ * - filter: parameter with organization ID
+ *   - id: (string, required) - Organization ID
+ *   - realm: (string, optional) - The realm name
+ */
+exports.findOne = function(filter) {
+    return kcAdminClientHandler.organizations.findOne(filter);
+}
+
+/**
+ * ***************************** - update - *******************************
+ * Update an organization
+ * 
+ * @parameters:
+ * - filter: parameter with organization ID
+ *   - id: (string, required) - Organization ID
+ * - organizationRepresentation: Updated organization data
+ */
+exports.update = async function(filter, organizationRepresentation) {
+    const { id } = filter;
+    const current = await exports.findOne({ id });
+    const merged = {
+        ...current,
+        ...organizationRepresentation,
+        id,
+        name: organizationRepresentation?.name || current?.name
+    };
+
+    return await makeDirectApiCall('PUT', `/organizations/${id}`, merged);
+}
+
+/**
+ * ***************************** - del - *******************************
+ * Delete an organization
+ * 
+ * @parameters:
+ * - filter: parameter with organization ID
+ *   - id: (string, required) - Organization ID
+ */
+exports.del = async function(filter) {
+    return kcAdminClientHandler.organizations.delById(filter);
+}
+
+/**
+ * ***************************** - addMember - *******************************
+ * Add a user as member to an organization
+ * 
+ * @parameters:
+ * - filter: parameter with organization ID and user ID
+ *   - id: (string, required) - Organization ID
+ *   - userId: (string, required) - User ID
+ */
+exports.addMember = async function(filter) {
+    const { id, userId } = filter;
+    return kcAdminClientHandler.organizations.addMember({
+        orgId: id,
+        userId
+    });
+}
+
+/**
+ * ***************************** - listMembers - *******************************
+ * List all members of an organization
+ * 
+ * @parameters:
+ * - filter: parameter with organization ID
+ *   - id: (string, required) - Organization ID
+ *   - first: (number, optional) - First result
+ *   - max: (number, optional) - Max results
+ */
+exports.listMembers = async function(filter) {
+    const { id, ...rest } = filter;
+    return kcAdminClientHandler.organizations.listMembers({
+        orgId: id,
+        ...rest
+    });
+}
+
+/**
+ * ***************************** - delMember - *******************************
+ * Remove a member from an organization
+ * 
+ * @parameters:
+ * - filter: parameter with organization ID and user ID
+ *   - id: (string, required) - Organization ID
+ *   - userId: (string, required) - User ID
+ */
+exports.delMember = async function(filter) {
+    const { id, userId } = filter;
+    return kcAdminClientHandler.organizations.delMember({
+        orgId: id,
+        userId
+    });
+}
+
+/**
+ * ***************************** - addIdentityProvider - *******************************
+ * Link an identity provider to an organization
+ * 
+ * @parameters:
+ * - filter: parameter with organization ID and IDP alias
+ *   - id: (string, required) - Organization ID
+ *   - alias: (string, required) - Identity provider alias
+ */
+exports.addIdentityProvider = async function(filter) {
+    const { id, alias } = filter;
+    return kcAdminClientHandler.organizations.linkIdp({
+        orgId: id,
+        alias
+    });
+}
+
+/**
+ * ***************************** - listIdentityProviders - *******************************
+ * List identity providers linked to an organization
+ * 
+ * @parameters:
+ * - filter: parameter with organization ID
+ *   - id: (string, required) - Organization ID
+ */
+exports.listIdentityProviders = async function(filter) {
+    const { id } = filter;
+    return kcAdminClientHandler.organizations.listIdentityProviders({ orgId: id });
+}
+
+/**
+ * ***************************** - delIdentityProvider - *******************************
+ * Unlink an identity provider from an organization
+ * 
+ * @parameters:
+ * - filter: parameter with organization ID and IDP alias
+ *   - id: (string, required) - Organization ID
+ *   - alias: (string, required) - Identity provider alias
+ */
+exports.delIdentityProvider = async function(filter) {
+    const { id, alias } = filter;
+    return kcAdminClientHandler.organizations.unLinkIdp({
+        orgId: id,
+        alias
+    });
+}

package/Handlers/serverInfoHandler.js

@@ -0,0 +1,36 @@
+/**
+ * **************************************************************************************************
+ * **************************************************************************************************
+ * The Server Info entity provides information about the Keycloak server instance,
+ * including available providers, themes, system info, memory usage, and enabled features.
+ * This is useful for monitoring, diagnostics, and understanding server capabilities.
+ * **************************************************************************************************
+ * **************************************************************************************************
+ */
+let kcAdminClientHandler = null;
+
+exports.setKcAdminClient = function(kcAdminClient) {
+    kcAdminClientHandler = kcAdminClient;
+}
+
+/**
+ * ***************************** - getInfo - *******************************
+ * Get comprehensive server information
+ * 
+ * @returns: Object containing:
+ *   - systemInfo: System and environment information
+ *   - memoryInfo: Memory usage statistics
+ *   - profileInfo: Active profile information
+ *   - themes: Available themes
+ *   - providers: Available SPI providers
+ *   - protocolMapperTypes: Available protocol mapper types
+ *   - builtinProtocolMappers: Built-in protocol mappers
+ *   - clientInstallations: Available client installation formats
+ *   - componentTypes: Available component types
+ *   - passwordPolicies: Available password policy types
+ *   - enums: Various enum values used in Keycloak
+ *   - cryptoInfo: Cryptographic information
+ */
+exports.getInfo = function() {
+    return kcAdminClientHandler.serverInfo.find();
+}

package/Handlers/userProfileHandler.js

@@ -0,0 +1,121 @@
+/**
+ * **************************************************************************************************
+ * **************************************************************************************************
+ * The User Profile entity (Keycloak 15+) allows managing declarative user profile configuration.
+ * This modern approach replaces the legacy attribute-based user management with a more
+ * structured and type-safe configuration model.
+ * **************************************************************************************************
+ * **************************************************************************************************
+ */
+let kcAdminClientHandler = null;
+
+exports.setKcAdminClient = function(kcAdminClient) {
+    kcAdminClientHandler = kcAdminClient;
+}
+
+/**
+ * ***************************** - getConfiguration - *******************************
+ * Get the user profile configuration for a realm
+ * 
+ * @parameters:
+ * - filter: [optional] parameter
+ *   - realm: (string, optional) - The realm name
+ * @returns: User profile configuration object with attributes, groups, etc.
+ */
+exports.getConfiguration = async function(filter) {
+    // Direct API call for better compatibility
+    const realm = filter?.realm || kcAdminClientHandler.realmName;
+    const baseUrl = kcAdminClientHandler.baseUrl;
+    const token = kcAdminClientHandler.accessToken;
+    
+    const url = `${baseUrl}/admin/realms/${realm}/users/profile`;
+    
+    const response = await fetch(url, {
+        method: 'GET',
+        headers: {
+            'Authorization': `Bearer ${token}`
+        }
+    });
+    
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Failed to get user profile: ${error}`);
+    }
+    
+    return response.json();
+}
+
+/**
+ * ***************************** - updateConfiguration - *******************************
+ * Update the user profile configuration
+ * 
+ * @parameters:
+ * - filter: [optional] parameter
+ *   - realm: (string, optional) - The realm name
+ * - userProfileConfig: User profile configuration object
+ *   - attributes: (array) - List of attribute configurations
+ *     - name: (string) - Attribute name
+ *     - displayName: (string) - Display name
+ *     - validations: (object) - Validation rules
+ *     - permissions: (object) - View/edit permissions
+ *     - required: (object) - Required scopes
+ *   - groups: (array) - Attribute groups
+ *   - unmanagedAttributePolicy: (string) - Policy for unmanaged attributes
+ */
+exports.updateConfiguration = async function(filter, userProfileConfig) {
+    // Direct API call for better compatibility
+    const realm = filter?.realm || kcAdminClientHandler.realmName;
+    const baseUrl = kcAdminClientHandler.baseUrl;
+    const token = kcAdminClientHandler.accessToken;
+    
+    const url = `${baseUrl}/admin/realms/${realm}/users/profile`;
+    
+    const response = await fetch(url, {
+        method: 'PUT',
+        headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${token}`
+        },
+        body: JSON.stringify(userProfileConfig)
+    });
+    
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Failed to update user profile: ${error}`);
+    }
+    
+    return response.status === 204 ? undefined : response.json();
+}
+
+/**
+ * ***************************** - getMetadata - *******************************
+ * Get metadata about the user profile
+ * Returns information about available validators, attribute types, etc.
+ * 
+ * @parameters:
+ * - filter: [optional] parameter
+ *   - realm: (string, optional) - The realm name
+ * @returns: Metadata object with validators, attribute config, etc.
+ */
+exports.getMetadata = async function(filter) {
+    // Direct API call for better compatibility
+    const realm = filter?.realm || kcAdminClientHandler.realmName;
+    const baseUrl = kcAdminClientHandler.baseUrl;
+    const token = kcAdminClientHandler.accessToken;
+    
+    const url = `${baseUrl}/admin/realms/${realm}/users/profile/metadata`;
+    
+    const response = await fetch(url, {
+        method: 'GET',
+        headers: {
+            'Authorization': `Bearer ${token}`
+        }
+    });
+    
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Failed to get user profile metadata: ${error}`);
+    }
+    
+    return response.json();
+}