strapi-plugin-keycloak-realm-users 1.0.0

package/server/src/services/keycloak-client.js

@@ -0,0 +1,758 @@
+/**
+ * @fileoverview Keycloak Admin REST API client service.
+ * Handles all direct communication with Keycloak servers including authentication,
+ * user management, role management, and email actions.
+ *
+ * @module services/keycloak-client
+ */
+
+import {
+  PLUGIN_ID,
+  ERROR_MESSAGES,
+  TOKEN_EXPIRY_BUFFER_MS,
+  EMAIL_ACTION_LIFESPAN_SECONDS,
+  HTTP_STATUS,
+  HTTP_HEADERS,
+  KEYCLOAK_EMAIL_ACTIONS,
+  PAGINATION,
+} from '../constants.js';
+import { createSanitizedError } from '../utils/errors.js';
+
+/**
+ * In-memory cache for Keycloak access tokens.
+ * Keys are formatted as `${serverUrl}:${realmName}:${clientId}`.
+ * @type {Map<string, {accessToken: string, expiresAt: number}>}
+ * @private
+ */
+const TOKEN_CACHE = new Map();
+
+/**
+ * Generates a cache key for token storage.
+ *
+ * @param {RealmConfig} realmConfig - The realm configuration
+ * @returns {string} Cache key in format "serverUrl:realmName:clientId"
+ * @private
+ */
+const getCacheKey = (realmConfig) =>
+  `${realmConfig.serverUrl}:${realmConfig.realmName}:${realmConfig.clientId}`;
+
+/**
+ * Builds the Keycloak token endpoint URL.
+ *
+ * @param {string} serverUrl - Keycloak server base URL
+ * @param {string} realmName - Target realm name
+ * @returns {string} Full token endpoint URL
+ * @private
+ */
+const buildTokenUrl = (serverUrl, realmName) =>
+  `${serverUrl}/realms/${realmName}/protocol/openid-connect/token`;
+
+/**
+ * Builds a Keycloak Admin API URL.
+ *
+ * @param {string} serverUrl - Keycloak server base URL
+ * @param {string} realmName - Target realm name
+ * @param {string} [path=''] - Additional path segments
+ * @returns {string} Full Admin API URL
+ * @private
+ */
+const buildAdminUrl = (serverUrl, realmName, path = '') =>
+  `${serverUrl}/admin/realms/${realmName}${path}`;
+
+/**
+ * @typedef {Object} RealmConfig
+ * @property {string} serverUrl - Keycloak server base URL (e.g., "https://keycloak.example.com")
+ * @property {string} realmName - Name of the Keycloak realm
+ * @property {string} clientId - OAuth client ID for service account
+ * @property {string} clientSecret - OAuth client secret
+ */
+
+/**
+ * @typedef {Object} KeycloakUser
+ * @property {string} id - Unique user identifier
+ * @property {string} username - User's username
+ * @property {string} [email] - User's email address
+ * @property {string} [firstName] - User's first name
+ * @property {string} [lastName] - User's last name
+ * @property {boolean} enabled - Whether the account is enabled
+ * @property {boolean} emailVerified - Whether email has been verified
+ * @property {number} createdTimestamp - Account creation timestamp
+ */
+
+/**
+ * @typedef {Object} KeycloakRole
+ * @property {string} id - Unique role identifier
+ * @property {string} name - Role name
+ * @property {string} [description] - Role description
+ * @property {boolean} [composite] - Whether this is a composite role
+ */
+
+/**
+ * @typedef {Object} ConnectionTestResult
+ * @property {boolean} success - Whether connection was successful
+ * @property {string} [message] - Error message if failed
+ * @property {string} [realmDisplayName] - Realm display name if successful
+ */
+
+/**
+ * Creates the Keycloak client service.
+ *
+ * @param {Object} params - Service parameters
+ * @param {Object} params.strapi - Strapi instance for logging
+ * @returns {Object} Keycloak client service methods
+ */
+const keycloakClientService = ({ strapi }) => ({
+  /**
+   * Retrieves or refreshes an access token for the specified realm.
+   * Tokens are cached and automatically refreshed before expiration.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @returns {Promise<string>} Valid access token
+   * @throws {Error} If authentication fails
+   *
+   * @example
+   * const token = await keycloakClient.getAccessToken(realmConfig);
+   * // Use token for API requests
+   */
+  async getAccessToken(realmConfig) {
+    const cacheKey = getCacheKey(realmConfig);
+    const cached = TOKEN_CACHE.get(cacheKey);
+
+    // Return cached token if still valid
+    if (cached && Date.now() < cached.expiresAt - TOKEN_EXPIRY_BUFFER_MS) {
+      return cached.accessToken;
+    }
+
+    try {
+      const tokenUrl = buildTokenUrl(realmConfig.serverUrl, realmConfig.realmName);
+
+      const response = await fetch(tokenUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': HTTP_HEADERS.CONTENT_TYPE_FORM,
+        },
+        body: new URLSearchParams({
+          grant_type: 'client_credentials',
+          client_id: realmConfig.clientId,
+          client_secret: realmConfig.clientSecret,
+        }),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        strapi.log.error(`[${PLUGIN_ID}] Token fetch failed: ${errorText}`);
+        throw createSanitizedError(
+          `Token fetch failed: ${errorText}`,
+          ERROR_MESSAGES.KEYCLOAK_AUTH_FAILED
+        );
+      }
+
+      const data = await response.json();
+
+      // Cache the token with expiration timestamp
+      TOKEN_CACHE.set(cacheKey, {
+        accessToken: data.access_token,
+        expiresAt: Date.now() + data.expires_in * 1000,
+      });
+
+      return data.access_token;
+    } catch (err) {
+      // Re-throw sanitized errors as-is
+      if (err.sanitizedMessage) throw err;
+      strapi.log.error(`[${PLUGIN_ID}] Token error:`, err);
+      throw createSanitizedError(err.message, ERROR_MESSAGES.KEYCLOAK_CONNECTION_FAILED);
+    }
+  },
+
+  /**
+   * Tests connection to a Keycloak realm by attempting authentication
+   * and fetching realm metadata.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @returns {Promise<ConnectionTestResult>} Test result with success status
+   *
+   * @example
+   * const result = await keycloakClient.testConnection(config);
+   * if (result.success) {
+   *   console.log(`Connected to ${result.realmDisplayName}`);
+   * }
+   */
+  async testConnection(realmConfig) {
+    try {
+      const token = await this.getAccessToken(realmConfig);
+      const url = buildAdminUrl(realmConfig.serverUrl, realmConfig.realmName);
+
+      const response = await fetch(url, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+
+      if (!response.ok) {
+        return { success: false, message: `HTTP ${response.status}: ${response.statusText}` };
+      }
+
+      const realm = await response.json();
+      return { success: true, realmDisplayName: realm.displayName || realm.realm };
+    } catch (err) {
+      return { success: false, message: err.sanitizedMessage || err.message };
+    }
+  },
+
+  /**
+   * Fetches a paginated list of users from Keycloak.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {Object} [options={}] - Query options
+   * @param {string} [options.search=''] - Search query (matches username, email, name)
+   * @param {number} [options.first=0] - Starting index for pagination
+   * @param {number} [options.max=25] - Maximum results to return
+   * @param {boolean} [options.briefRepresentation=true] - Return minimal user data
+   * @returns {Promise<KeycloakUser[]>} Array of user objects
+   * @throws {Error} If the request fails
+   *
+   * @example
+   * const users = await keycloakClient.getUsers(realm, {
+   *   search: 'john',
+   *   first: 0,
+   *   max: 10
+   * });
+   */
+  async getUsers(realmConfig, { search = '', first = 0, max = PAGINATION.PAGE_SIZE, briefRepresentation = true } = {}) {
+    const token = await this.getAccessToken(realmConfig);
+    const params = new URLSearchParams({
+      first: String(first),
+      max: String(max),
+      briefRepresentation: String(briefRepresentation),
+    });
+
+    if (search) {
+      params.set('search', search);
+    }
+
+    const url = `${buildAdminUrl(realmConfig.serverUrl, realmConfig.realmName, '/users')}?${params}`;
+
+    const response = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      strapi.log.error(`[${PLUGIN_ID}] Failed to fetch users: ${errorText}`);
+      throw createSanitizedError(errorText, ERROR_MESSAGES.KEYCLOAK_CONNECTION_FAILED);
+    }
+
+    return response.json();
+  },
+
+  /**
+   * Counts total users in a realm, optionally filtered by search query.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {Object} [options={}] - Query options
+   * @param {string} [options.search=''] - Search query to filter count
+   * @returns {Promise<number>} Total user count
+   *
+   * @example
+   * const total = await keycloakClient.countUsers(realm, { search: 'admin' });
+   */
+  async countUsers(realmConfig, { search = '' } = {}) {
+    const token = await this.getAccessToken(realmConfig);
+    const params = new URLSearchParams();
+    if (search) params.set('search', search);
+
+    const url = `${buildAdminUrl(realmConfig.serverUrl, realmConfig.realmName, '/users/count')}?${params}`;
+
+    const response = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (!response.ok) {
+      return 0;
+    }
+
+    return response.json();
+  },
+
+  /**
+   * Retrieves a single user by their Keycloak ID.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<KeycloakUser>} User object with full details
+   * @throws {Error} If user not found or request fails
+   *
+   * @example
+   * const user = await keycloakClient.getUserById(realm, 'abc-123');
+   */
+  async getUserById(realmConfig, userId) {
+    const token = await this.getAccessToken(realmConfig);
+    const url = buildAdminUrl(realmConfig.serverUrl, realmConfig.realmName, `/users/${userId}`);
+
+    const response = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (!response.ok) {
+      if (response.status === HTTP_STATUS.NOT_FOUND) {
+        throw createSanitizedError(`User ${userId} not found`, ERROR_MESSAGES.USER_NOT_FOUND);
+      }
+      const errorText = await response.text();
+      throw createSanitizedError(errorText, ERROR_MESSAGES.KEYCLOAK_CONNECTION_FAILED);
+    }
+
+    return response.json();
+  },
+
+  /**
+   * Creates a new user in Keycloak.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {Object} userData - User data to create
+   * @param {string} userData.username - Required username
+   * @param {string} [userData.email] - Email address
+   * @param {string} [userData.firstName] - First name
+   * @param {string} [userData.lastName] - Last name
+   * @param {boolean} [userData.enabled=true] - Account enabled status
+   * @param {boolean} [userData.emailVerified=false] - Email verification status
+   * @returns {Promise<{userId: string|null, location: string|null}>} Created user info
+   * @throws {Error} If user creation fails (e.g., duplicate username/email)
+   *
+   * @example
+   * const result = await keycloakClient.createUser(realm, {
+   *   username: 'newuser',
+   *   email: 'new@example.com',
+   *   enabled: true
+   * });
+   */
+  async createUser(realmConfig, userData) {
+    const token = await this.getAccessToken(realmConfig);
+    const url = buildAdminUrl(realmConfig.serverUrl, realmConfig.realmName, '/users');
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': HTTP_HEADERS.CONTENT_TYPE_JSON,
+      },
+      body: JSON.stringify(userData),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      strapi.log.error(`[${PLUGIN_ID}] Failed to create user: ${errorText}`);
+
+      if (response.status === HTTP_STATUS.CONFLICT) {
+        throw createSanitizedError(errorText, ERROR_MESSAGES.USER_ALREADY_EXISTS);
+      }
+      throw createSanitizedError(errorText, ERROR_MESSAGES.INVALID_USER_DATA);
+    }
+
+    // Extract user ID from Location header
+    const location = response.headers.get('Location');
+    const userId = location ? location.split('/').pop() : null;
+
+    return { userId, location };
+  },
+
+  /**
+   * Updates an existing user's attributes.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {string} userId - Keycloak user ID
+   * @param {Object} userData - Updated user attributes
+   * @returns {Promise<{success: boolean}>} Success indicator
+   * @throws {Error} If user not found or update fails
+   *
+   * @example
+   * await keycloakClient.updateUser(realm, userId, {
+   *   firstName: 'Updated',
+   *   enabled: false
+   * });
+   */
+  async updateUser(realmConfig, userId, userData) {
+    const token = await this.getAccessToken(realmConfig);
+    const url = buildAdminUrl(realmConfig.serverUrl, realmConfig.realmName, `/users/${userId}`);
+
+    const response = await fetch(url, {
+      method: 'PUT',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': HTTP_HEADERS.CONTENT_TYPE_JSON,
+      },
+      body: JSON.stringify(userData),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      strapi.log.error(`[${PLUGIN_ID}] Failed to update user: ${errorText}`);
+
+      if (response.status === HTTP_STATUS.NOT_FOUND) {
+        throw createSanitizedError(errorText, ERROR_MESSAGES.USER_NOT_FOUND);
+      }
+      throw createSanitizedError(errorText, ERROR_MESSAGES.INVALID_USER_DATA);
+    }
+
+    return { success: true };
+  },
+
+  /**
+   * Permanently deletes a user from Keycloak.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<{success: boolean}>} Success indicator
+   * @throws {Error} If user not found or deletion fails
+   *
+   * @example
+   * await keycloakClient.deleteUser(realm, 'user-id-123');
+   */
+  async deleteUser(realmConfig, userId) {
+    const token = await this.getAccessToken(realmConfig);
+    const url = buildAdminUrl(realmConfig.serverUrl, realmConfig.realmName, `/users/${userId}`);
+
+    const response = await fetch(url, {
+      method: 'DELETE',
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      if (response.status === HTTP_STATUS.NOT_FOUND) {
+        throw createSanitizedError(errorText, ERROR_MESSAGES.USER_NOT_FOUND);
+      }
+      throw createSanitizedError(errorText, ERROR_MESSAGES.KEYCLOAK_CONNECTION_FAILED);
+    }
+
+    return { success: true };
+  },
+
+  /**
+   * Sets a new password for a user.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {string} userId - Keycloak user ID
+   * @param {string} password - New password value
+   * @param {boolean} [temporary=true] - If true, user must change password on next login
+   * @returns {Promise<{success: boolean}>} Success indicator
+   * @throws {Error} If user not found or password reset fails
+   *
+   * @example
+   * // Set temporary password (user must change on login)
+   * await keycloakClient.resetPassword(realm, userId, 'TempPass123!', true);
+   *
+   * // Set permanent password
+   * await keycloakClient.resetPassword(realm, userId, 'NewPass123!', false);
+   */
+  async resetPassword(realmConfig, userId, password, temporary = true) {
+    const token = await this.getAccessToken(realmConfig);
+    const url = buildAdminUrl(realmConfig.serverUrl, realmConfig.realmName, `/users/${userId}/reset-password`);
+
+    const response = await fetch(url, {
+      method: 'PUT',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': HTTP_HEADERS.CONTENT_TYPE_JSON,
+      },
+      body: JSON.stringify({
+        type: 'password',
+        value: password,
+        temporary,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      if (response.status === HTTP_STATUS.NOT_FOUND) {
+        throw createSanitizedError(errorText, ERROR_MESSAGES.USER_NOT_FOUND);
+      }
+      throw createSanitizedError(errorText, ERROR_MESSAGES.PASSWORD_RESET_FAILED);
+    }
+
+    return { success: true };
+  },
+
+  /**
+   * Enables a user account.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<{success: boolean}>} Success indicator
+   */
+  async enableUser(realmConfig, userId) {
+    return this.updateUser(realmConfig, userId, { enabled: true });
+  },
+
+  /**
+   * Disables a user account.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<{success: boolean}>} Success indicator
+   */
+  async disableUser(realmConfig, userId) {
+    return this.updateUser(realmConfig, userId, { enabled: false });
+  },
+
+  /**
+   * Triggers email actions for a user (e.g., verify email, update password).
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {string} userId - Keycloak user ID
+   * @param {string[]} actions - Array of action types (e.g., ['VERIFY_EMAIL'])
+   * @param {number} [lifespan] - Link validity in seconds (default: 12 hours)
+   * @returns {Promise<{success: boolean}>} Success indicator
+   * @throws {Error} If user not found or email fails
+   *
+   * @example
+   * // Send verification email
+   * await keycloakClient.executeEmailActions(realm, userId, ['VERIFY_EMAIL']);
+   *
+   * // Send password reset with custom lifespan (1 hour)
+   * await keycloakClient.executeEmailActions(realm, userId, ['UPDATE_PASSWORD'], 3600);
+   */
+  async executeEmailActions(realmConfig, userId, actions, lifespan = EMAIL_ACTION_LIFESPAN_SECONDS) {
+    const token = await this.getAccessToken(realmConfig);
+    const params = new URLSearchParams({ lifespan: String(lifespan) });
+    const url = `${buildAdminUrl(realmConfig.serverUrl, realmConfig.realmName, `/users/${userId}/execute-actions-email`)}?${params}`;
+
+    const response = await fetch(url, {
+      method: 'PUT',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': HTTP_HEADERS.CONTENT_TYPE_JSON,
+      },
+      body: JSON.stringify(actions),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      if (response.status === HTTP_STATUS.NOT_FOUND) {
+        throw createSanitizedError(errorText, ERROR_MESSAGES.USER_NOT_FOUND);
+      }
+      throw createSanitizedError(errorText, ERROR_MESSAGES.EMAIL_SEND_FAILED);
+    }
+
+    return { success: true };
+  },
+
+  /**
+   * Sends an email verification link to the user.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<{success: boolean}>} Success indicator
+   */
+  async sendVerificationEmail(realmConfig, userId) {
+    return this.executeEmailActions(realmConfig, userId, [KEYCLOAK_EMAIL_ACTIONS.VERIFY_EMAIL]);
+  },
+
+  /**
+   * Sends a password reset email to the user.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<{success: boolean}>} Success indicator
+   */
+  async sendResetPasswordEmail(realmConfig, userId) {
+    return this.executeEmailActions(realmConfig, userId, [KEYCLOAK_EMAIL_ACTIONS.UPDATE_PASSWORD]);
+  },
+
+  /**
+   * Retrieves all realm-level roles.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @returns {Promise<KeycloakRole[]>} Array of realm roles
+   *
+   * @example
+   * const roles = await keycloakClient.getRealmRoles(realm);
+   * // [{ id: '...', name: 'admin', ... }, ...]
+   */
+  async getRealmRoles(realmConfig) {
+    const token = await this.getAccessToken(realmConfig);
+    const url = buildAdminUrl(realmConfig.serverUrl, realmConfig.realmName, '/roles');
+
+    const response = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw createSanitizedError(errorText, ERROR_MESSAGES.KEYCLOAK_CONNECTION_FAILED);
+    }
+
+    return response.json();
+  },
+
+  /**
+   * Gets realm roles assigned to a specific user.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<KeycloakRole[]>} Array of assigned roles
+   *
+   * @example
+   * const userRoles = await keycloakClient.getUserRoles(realm, userId);
+   */
+  async getUserRoles(realmConfig, userId) {
+    const token = await this.getAccessToken(realmConfig);
+    const url = buildAdminUrl(realmConfig.serverUrl, realmConfig.realmName, `/users/${userId}/role-mappings/realm`);
+
+    const response = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (!response.ok) {
+      if (response.status === HTTP_STATUS.NOT_FOUND) {
+        throw createSanitizedError(`User ${userId} not found`, ERROR_MESSAGES.USER_NOT_FOUND);
+      }
+      const errorText = await response.text();
+      throw createSanitizedError(errorText, ERROR_MESSAGES.KEYCLOAK_CONNECTION_FAILED);
+    }
+
+    return response.json();
+  },
+
+  /**
+   * Assigns realm roles to a user.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {string} userId - Keycloak user ID
+   * @param {KeycloakRole[]} roles - Array of role objects with id and name
+   * @returns {Promise<{success: boolean}>} Success indicator
+   *
+   * @example
+   * await keycloakClient.assignRoles(realm, userId, [
+   *   { id: 'role-id-1', name: 'admin' },
+   *   { id: 'role-id-2', name: 'editor' }
+   * ]);
+   */
+  async assignRoles(realmConfig, userId, roles) {
+    const token = await this.getAccessToken(realmConfig);
+    const url = buildAdminUrl(realmConfig.serverUrl, realmConfig.realmName, `/users/${userId}/role-mappings/realm`);
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': HTTP_HEADERS.CONTENT_TYPE_JSON,
+      },
+      body: JSON.stringify(roles),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw createSanitizedError(errorText, ERROR_MESSAGES.ROLE_ASSIGNMENT_FAILED);
+    }
+
+    return { success: true };
+  },
+
+  /**
+   * Removes realm roles from a user.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {string} userId - Keycloak user ID
+   * @param {KeycloakRole[]} roles - Array of role objects to remove
+   * @returns {Promise<{success: boolean}>} Success indicator
+   *
+   * @example
+   * await keycloakClient.removeRoles(realm, userId, [
+   *   { id: 'role-id-1', name: 'admin' }
+   * ]);
+   */
+  async removeRoles(realmConfig, userId, roles) {
+    const token = await this.getAccessToken(realmConfig);
+    const url = buildAdminUrl(realmConfig.serverUrl, realmConfig.realmName, `/users/${userId}/role-mappings/realm`);
+
+    const response = await fetch(url, {
+      method: 'DELETE',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': HTTP_HEADERS.CONTENT_TYPE_JSON,
+      },
+      body: JSON.stringify(roles),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw createSanitizedError(errorText, ERROR_MESSAGES.ROLE_REMOVAL_FAILED);
+    }
+
+    return { success: true };
+  },
+
+  /**
+   * Gets active sessions for a user.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<Object[]>} Array of session objects
+   *
+   * @example
+   * const sessions = await keycloakClient.getUserSessions(realm, userId);
+   */
+  async getUserSessions(realmConfig, userId) {
+    const token = await this.getAccessToken(realmConfig);
+    const url = buildAdminUrl(realmConfig.serverUrl, realmConfig.realmName, `/users/${userId}/sessions`);
+
+    const response = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (!response.ok) {
+      return [];
+    }
+
+    return response.json();
+  },
+
+  /**
+   * Terminates all active sessions for a user.
+   *
+   * @param {RealmConfig} realmConfig - Realm connection configuration
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<{success: boolean}>} Success indicator
+   *
+   * @example
+   * await keycloakClient.logoutUser(realm, userId);
+   */
+  async logoutUser(realmConfig, userId) {
+    const token = await this.getAccessToken(realmConfig);
+    const url = buildAdminUrl(realmConfig.serverUrl, realmConfig.realmName, `/users/${userId}/logout`);
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (!response.ok && response.status !== HTTP_STATUS.NO_CONTENT) {
+      const errorText = await response.text();
+      throw createSanitizedError(errorText, ERROR_MESSAGES.LOGOUT_FAILED);
+    }
+
+    return { success: true };
+  },
+
+  /**
+   * Clears cached access tokens.
+   * Call this when realm configuration changes to force re-authentication.
+   *
+   * @param {RealmConfig} [realmConfig] - Specific realm to clear, or all if omitted
+   *
+   * @example
+   * // Clear specific realm's token
+   * keycloakClient.clearTokenCache(realmConfig);
+   *
+   * // Clear all cached tokens
+   * keycloakClient.clearTokenCache();
+   */
+  clearTokenCache(realmConfig) {
+    if (realmConfig) {
+      const cacheKey = getCacheKey(realmConfig);
+      TOKEN_CACHE.delete(cacheKey);
+    } else {
+      TOKEN_CACHE.clear();
+    }
+  },
+});
+
+export default keycloakClientService;