strapi-plugin-keycloak-realm-users 1.0.0

package/server/src/services/user.js

@@ -0,0 +1,613 @@
+/**
+ * @fileoverview User management service orchestrating Keycloak operations.
+ * Provides high-level user management with permission checking and audit logging.
+ *
+ * @module services/user
+ */
+
+import {
+  PLUGIN_ID,
+  SERVICES,
+  AUDIT_ACTIONS,
+  ERROR_MESSAGES,
+  PAGINATION,
+} from '../constants.js';
+import { createSanitizedError } from '../utils/errors.js';
+
+/**
+ * @typedef {import('./keycloak-client.js').KeycloakUser} KeycloakUser
+ * @typedef {import('./keycloak-client.js').KeycloakRole} KeycloakRole
+ * @typedef {import('./permission.js').StrapiUser} StrapiUser
+ * @typedef {import('./permission.js').RealmPermissions} RealmPermissions
+ */
+
+/**
+ * @typedef {Object} PaginatedUsersResult
+ * @property {KeycloakUser[]} users - Array of users
+ * @property {Object} pagination - Pagination metadata
+ * @property {number} pagination.page - Current page number
+ * @property {number} pagination.pageSize - Items per page
+ * @property {number} pagination.total - Total items
+ * @property {number} pagination.pageCount - Total pages
+ */
+
+/**
+ * @typedef {Object} BulkImportResult
+ * @property {Object[]} success - Successfully created users
+ * @property {string} success[].username - Username
+ * @property {string} success[].email - Email
+ * @property {string} success[].userId - Created user ID
+ * @property {Object[]} failed - Failed user creations
+ * @property {string} failed[].username - Username
+ * @property {string} failed[].email - Email
+ * @property {string} failed[].error - Error message
+ */
+
+/**
+ * Creates the user management service.
+ *
+ * @param {Object} params - Service parameters
+ * @param {Object} params.strapi - Strapi instance
+ * @returns {Object} User service methods
+ */
+const userService = ({ strapi }) => ({
+  /**
+   * Gets the realm service instance.
+   * @returns {Object} Realm service
+   * @private
+   */
+  get realmService() {
+    return strapi.plugin(PLUGIN_ID).service(SERVICES.REALM);
+  },
+
+  /**
+   * Gets the Keycloak client service instance.
+   * @returns {Object} Keycloak client service
+   * @private
+   */
+  get keycloakClient() {
+    return strapi.plugin(PLUGIN_ID).service(SERVICES.KEYCLOAK_CLIENT);
+  },
+
+  /**
+   * Gets the permission service instance.
+   * @returns {Object} Permission service
+   * @private
+   */
+  get permissionService() {
+    return strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+  },
+
+  /**
+   * Gets the audit log service instance.
+   * @returns {Object} Audit log service
+   * @private
+   */
+  get auditLogService() {
+    return strapi.plugin(PLUGIN_ID).service(SERVICES.AUDIT_LOG);
+  },
+
+  /**
+   * Validates user permission and returns realm config with credentials.
+   * This is the primary permission gate for all user operations.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {StrapiUser} user - Strapi user requesting access
+   * @param {keyof RealmPermissions} permission - Required permission
+   * @returns {Promise<Object>} Realm config with clientSecret for API calls
+   * @throws {Error} If realm disabled or user lacks permission
+   * @private
+   *
+   * @example
+   * const realm = await this.getRealmWithPermission(realmId, user, 'canCreate');
+   * // Now safe to call Keycloak APIs
+   */
+  async getRealmWithPermission(realmId, user, permission) {
+    // First check if realm exists and is enabled
+    const realmBasic = await this.realmService.findOne(realmId);
+
+    if (!realmBasic.enabled) {
+      throw createSanitizedError('Realm disabled', ERROR_MESSAGES.REALM_DISABLED);
+    }
+
+    // Check user permission
+    const hasPermission = await this.permissionService.canAccessRealm(user, realmId, permission);
+
+    if (!hasPermission) {
+      throw createSanitizedError(
+        `User ${user.id} lacks ${permission} for realm ${realmId}`,
+        ERROR_MESSAGES.REALM_ACCESS_DENIED
+      );
+    }
+
+    // Get realm with clientSecret for Keycloak API calls
+    return this.realmService.findOneWithSecret(realmId);
+  },
+
+  /**
+   * Lists users from a Keycloak realm with pagination.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {Object} [options={}] - Query options
+   * @param {string} [options.search=''] - Search query
+   * @param {number} [options.page=1] - Page number (1-indexed)
+   * @param {number} [options.pageSize=25] - Items per page
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<PaginatedUsersResult>} Paginated users
+   *
+   * @example
+   * const { users, pagination } = await userService.listUsers(
+   *   realmId,
+   *   { search: 'john', page: 1, pageSize: 10 },
+   *   ctx.state.user
+   * );
+   */
+  async listUsers(realmId, { search = '', page = 1, pageSize = PAGINATION.PAGE_SIZE } = {}, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canRead');
+
+    const first = (page - 1) * pageSize;
+    const [users, total] = await Promise.all([
+      this.keycloakClient.getUsers(realm, { search, first, max: pageSize }),
+      this.keycloakClient.countUsers(realm, { search }),
+    ]);
+
+    return {
+      users,
+      pagination: {
+        page,
+        pageSize,
+        total,
+        pageCount: Math.ceil(total / pageSize),
+      },
+    };
+  },
+
+  /**
+   * Retrieves a single user by Keycloak ID.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {string} keycloakUserId - Keycloak user ID
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<KeycloakUser>} User details
+   *
+   * @example
+   * const user = await userService.getUser(realmId, 'kc-user-123', ctx.state.user);
+   */
+  async getUser(realmId, keycloakUserId, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canRead');
+    return this.keycloakClient.getUserById(realm, keycloakUserId);
+  },
+
+  /**
+   * Creates a new user in Keycloak.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {Object} userData - User data
+   * @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
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<KeycloakUser>} Created user
+   *
+   * @example
+   * const user = await userService.createUser(
+   *   realmId,
+   *   { username: 'newuser', email: 'new@example.com' },
+   *   ctx.state.user
+   * );
+   */
+  async createUser(realmId, userData, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canCreate');
+
+    const result = await this.keycloakClient.createUser(realm, userData);
+
+    // Log the action
+    await this.auditLogService.log({
+      realmName: realm.name,
+      realmDisplayName: realm.displayName,
+      action: AUDIT_ACTIONS.CREATE_USER,
+      keycloakUserId: result.userId,
+      keycloakUsername: userData.username,
+      details: {
+        email: userData.email,
+        firstName: userData.firstName,
+        lastName: userData.lastName
+      },
+      user: strapiUser,
+    });
+
+    // Fetch and return the created user if we have the ID
+    if (result.userId) {
+      return this.keycloakClient.getUserById(realm, result.userId);
+    }
+
+    return result;
+  },
+
+  /**
+   * Updates an existing user's attributes.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {string} keycloakUserId - Keycloak user ID
+   * @param {Object} userData - Fields to update
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<KeycloakUser>} Updated user
+   *
+   * @example
+   * const user = await userService.updateUser(
+   *   realmId,
+   *   'kc-user-123',
+   *   { firstName: 'Updated', lastName: 'Name' },
+   *   ctx.state.user
+   * );
+   */
+  async updateUser(realmId, keycloakUserId, userData, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canUpdate');
+
+    // Get current user data for audit
+    const currentUser = await this.keycloakClient.getUserById(realm, keycloakUserId);
+
+    await this.keycloakClient.updateUser(realm, keycloakUserId, userData);
+
+    await this.auditLogService.log({
+      realmName: realm.name,
+      realmDisplayName: realm.displayName,
+      action: AUDIT_ACTIONS.UPDATE_USER,
+      keycloakUserId,
+      keycloakUsername: currentUser.username,
+      details: { changes: userData },
+      user: strapiUser,
+    });
+
+    return this.keycloakClient.getUserById(realm, keycloakUserId);
+  },
+
+  /**
+   * Permanently deletes a user from Keycloak.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {string} keycloakUserId - Keycloak user ID
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<{success: boolean}>} Success indicator
+   *
+   * @example
+   * await userService.deleteUser(realmId, 'kc-user-123', ctx.state.user);
+   */
+  async deleteUser(realmId, keycloakUserId, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canDelete');
+
+    // Get user data for audit before deletion
+    const user = await this.keycloakClient.getUserById(realm, keycloakUserId);
+
+    await this.keycloakClient.deleteUser(realm, keycloakUserId);
+
+    await this.auditLogService.log({
+      realmName: realm.name,
+      realmDisplayName: realm.displayName,
+      action: AUDIT_ACTIONS.DELETE_USER,
+      keycloakUserId,
+      keycloakUsername: user.username,
+      details: { email: user.email },
+      user: strapiUser,
+    });
+
+    return { success: true };
+  },
+
+  /**
+   * Resets a user's password.
+   * Requires canResetPassword permission (separate from canUpdate for compliance).
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {string} keycloakUserId - Keycloak user ID
+   * @param {string} password - New password
+   * @param {boolean} temporary - Whether password must be changed on next login
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<{success: boolean}>} Success indicator
+   *
+   * @example
+   * // Set temporary password
+   * await userService.resetPassword(realmId, userId, 'TempPass123!', true, user);
+   */
+  async resetPassword(realmId, keycloakUserId, password, temporary, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canResetPassword');
+
+    const user = await this.keycloakClient.getUserById(realm, keycloakUserId);
+    await this.keycloakClient.resetPassword(realm, keycloakUserId, password, temporary);
+
+    await this.auditLogService.log({
+      realmName: realm.name,
+      realmDisplayName: realm.displayName,
+      action: AUDIT_ACTIONS.RESET_PASSWORD,
+      keycloakUserId,
+      keycloakUsername: user.username,
+      details: { temporary },
+      user: strapiUser,
+    });
+
+    return { success: true };
+  },
+
+  /**
+   * Enables a user account.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {string} keycloakUserId - Keycloak user ID
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<{success: boolean}>} Success indicator
+   */
+  async enableUser(realmId, keycloakUserId, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canUpdate');
+
+    const user = await this.keycloakClient.getUserById(realm, keycloakUserId);
+    await this.keycloakClient.enableUser(realm, keycloakUserId);
+
+    await this.auditLogService.log({
+      realmName: realm.name,
+      realmDisplayName: realm.displayName,
+      action: AUDIT_ACTIONS.ENABLE_USER,
+      keycloakUserId,
+      keycloakUsername: user.username,
+      user: strapiUser,
+    });
+
+    return { success: true };
+  },
+
+  /**
+   * Disables a user account.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {string} keycloakUserId - Keycloak user ID
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<{success: boolean}>} Success indicator
+   */
+  async disableUser(realmId, keycloakUserId, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canUpdate');
+
+    const user = await this.keycloakClient.getUserById(realm, keycloakUserId);
+    await this.keycloakClient.disableUser(realm, keycloakUserId);
+
+    await this.auditLogService.log({
+      realmName: realm.name,
+      realmDisplayName: realm.displayName,
+      action: AUDIT_ACTIONS.DISABLE_USER,
+      keycloakUserId,
+      keycloakUsername: user.username,
+      user: strapiUser,
+    });
+
+    return { success: true };
+  },
+
+  /**
+   * Sends an email verification link to the user.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {string} keycloakUserId - Keycloak user ID
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<{success: boolean}>} Success indicator
+   */
+  async sendVerificationEmail(realmId, keycloakUserId, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canUpdate');
+
+    const user = await this.keycloakClient.getUserById(realm, keycloakUserId);
+    await this.keycloakClient.sendVerificationEmail(realm, keycloakUserId);
+
+    await this.auditLogService.log({
+      realmName: realm.name,
+      realmDisplayName: realm.displayName,
+      action: AUDIT_ACTIONS.SEND_VERIFY_EMAIL,
+      keycloakUserId,
+      keycloakUsername: user.username,
+      user: strapiUser,
+    });
+
+    return { success: true };
+  },
+
+  /**
+   * Sends a password reset email to the user.
+   * Requires canResetPassword permission.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {string} keycloakUserId - Keycloak user ID
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<{success: boolean}>} Success indicator
+   */
+  async sendResetPasswordEmail(realmId, keycloakUserId, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canResetPassword');
+
+    const user = await this.keycloakClient.getUserById(realm, keycloakUserId);
+    await this.keycloakClient.sendResetPasswordEmail(realm, keycloakUserId);
+
+    await this.auditLogService.log({
+      realmName: realm.name,
+      realmDisplayName: realm.displayName,
+      action: AUDIT_ACTIONS.SEND_RESET_PASSWORD_EMAIL,
+      keycloakUserId,
+      keycloakUsername: user.username,
+      user: strapiUser,
+    });
+
+    return { success: true };
+  },
+
+  /**
+   * Retrieves all realm roles.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<KeycloakRole[]>} Array of realm roles
+   */
+  async getRoles(realmId, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canRead');
+    return this.keycloakClient.getRealmRoles(realm);
+  },
+
+  /**
+   * Gets roles assigned to a user.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {string} keycloakUserId - Keycloak user ID
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<KeycloakRole[]>} User's assigned roles
+   */
+  async getUserRoles(realmId, keycloakUserId, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canRead');
+    return this.keycloakClient.getUserRoles(realm, keycloakUserId);
+  },
+
+  /**
+   * Assigns roles to a user.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {string} keycloakUserId - Keycloak user ID
+   * @param {KeycloakRole[]} roles - Roles to assign
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<{success: boolean}>} Success indicator
+   */
+  async assignRoles(realmId, keycloakUserId, roles, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canManageRoles');
+
+    const user = await this.keycloakClient.getUserById(realm, keycloakUserId);
+    await this.keycloakClient.assignRoles(realm, keycloakUserId, roles);
+
+    await this.auditLogService.log({
+      realmName: realm.name,
+      realmDisplayName: realm.displayName,
+      action: AUDIT_ACTIONS.ASSIGN_ROLE,
+      keycloakUserId,
+      keycloakUsername: user.username,
+      details: { roles: roles.map((r) => r.name) },
+      user: strapiUser,
+    });
+
+    return { success: true };
+  },
+
+  /**
+   * Removes roles from a user.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {string} keycloakUserId - Keycloak user ID
+   * @param {KeycloakRole[]} roles - Roles to remove
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<{success: boolean}>} Success indicator
+   */
+  async removeRoles(realmId, keycloakUserId, roles, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canManageRoles');
+
+    const user = await this.keycloakClient.getUserById(realm, keycloakUserId);
+    await this.keycloakClient.removeRoles(realm, keycloakUserId, roles);
+
+    await this.auditLogService.log({
+      realmName: realm.name,
+      realmDisplayName: realm.displayName,
+      action: AUDIT_ACTIONS.REMOVE_ROLE,
+      keycloakUserId,
+      keycloakUsername: user.username,
+      details: { roles: roles.map((r) => r.name) },
+      user: strapiUser,
+    });
+
+    return { success: true };
+  },
+
+  /**
+   * Bulk imports users from an array of user data.
+   * Processes users sequentially to handle errors gracefully.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {Object[]} users - Array of user data objects
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<BulkImportResult>} Import results with success/failed arrays
+   *
+   * @example
+   * const result = await userService.bulkImport(realmId, [
+   *   { username: 'user1', email: 'user1@example.com' },
+   *   { username: 'user2', email: 'user2@example.com' }
+   * ], ctx.state.user);
+   * console.log(`Created ${result.success.length}, Failed ${result.failed.length}`);
+   */
+  async bulkImport(realmId, users, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canCreate');
+
+    const results = {
+      success: [],
+      failed: [],
+    };
+
+    // Process users sequentially for better error handling
+    for (const userData of users) {
+      try {
+        const result = await this.keycloakClient.createUser(realm, userData);
+        results.success.push({
+          username: userData.username,
+          email: userData.email,
+          userId: result.userId,
+        });
+      } catch (err) {
+        results.failed.push({
+          username: userData.username,
+          email: userData.email,
+          error: err.sanitizedMessage || err.message,
+        });
+      }
+    }
+
+    await this.auditLogService.log({
+      realmName: realm.name,
+      realmDisplayName: realm.displayName,
+      action: AUDIT_ACTIONS.BULK_IMPORT,
+      details: {
+        totalAttempted: users.length,
+        successCount: results.success.length,
+        failedCount: results.failed.length,
+      },
+      user: strapiUser,
+    });
+
+    return results;
+  },
+
+  /**
+   * Exports all users from a realm.
+   * Fetches users in batches for performance.
+   *
+   * @param {string} realmId - Realm document ID
+   * @param {StrapiUser} strapiUser - User making the request
+   * @returns {Promise<KeycloakUser[]>} All users in the realm
+   *
+   * @example
+   * const users = await userService.exportUsers(realmId, ctx.state.user);
+   * // Convert to CSV or JSON for download
+   */
+  async exportUsers(realmId, strapiUser) {
+    const realm = await this.getRealmWithPermission(realmId, strapiUser, 'canRead');
+
+    const allUsers = [];
+    let first = 0;
+    const max = PAGINATION.EXPORT_BATCH_SIZE;
+    let hasMore = true;
+
+    // Fetch users in batches
+    while (hasMore) {
+      const users = await this.keycloakClient.getUsers(realm, {
+        first,
+        max,
+        briefRepresentation: false,
+      });
+
+      allUsers.push(...users);
+      first += max;
+      hasMore = users.length === max;
+    }
+
+    return allUsers;
+  },
+});
+
+export default userService;

package/server/src/utils/errors.js

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Error utilities for the Keycloak Realm Users plugin.
+ * Provides standardized error creation with sanitization support for secure API responses.
+ * @module utils/errors
+ */
+
+/**
+ * Creates an error with both internal and sanitized messages.
+ * The internal message is used for logging, while the sanitized message is safe to expose to clients.
+ *
+ * @param {string} internalMessage - Detailed error message for internal logging (may contain sensitive info)
+ * @param {string} sanitizedMessage - Safe error message to expose to API consumers
+ * @returns {Error} Error object with additional sanitizedMessage property
+ *
+ * @example
+ * // Create an error with sensitive details hidden from client
+ * throw createSanitizedError(
+ *   `Token fetch failed for client ${clientId}: ${response.status}`,
+ *   ERROR_MESSAGES.KEYCLOAK_AUTH_FAILED
+ * );
+ */
+export const createSanitizedError = (internalMessage, sanitizedMessage) => {
+  const err = new Error(internalMessage);
+  err.sanitizedMessage = sanitizedMessage;
+  return err;
+};
+
+/**
+ * Extracts the appropriate error message for API responses.
+ * Uses the sanitized message if available, otherwise falls back to the original message.
+ *
+ * @param {Error} error - The error object to extract message from
+ * @param {string} [fallbackMessage] - Optional fallback message if error has no message
+ * @returns {string} The safe error message to return to clients
+ *
+ * @example
+ * try {
+ *   await someOperation();
+ * } catch (err) {
+ *   return ctx.badRequest(getErrorMessage(err, 'Operation failed'));
+ * }
+ */
+export const getErrorMessage = (error, fallbackMessage = 'An unexpected error occurred') => {
+  if (error.sanitizedMessage) {
+    return error.sanitizedMessage;
+  }
+  return error.message || fallbackMessage;
+};
+
+/**
+ * Checks if an error is a sanitized error (created by createSanitizedError).
+ *
+ * @param {Error} error - The error to check
+ * @returns {boolean} True if the error has a sanitizedMessage property
+ *
+ * @example
+ * if (isSanitizedError(err)) {
+ *   // Safe to expose error.sanitizedMessage
+ * }
+ */
+export const isSanitizedError = (error) => {
+  return Boolean(error && typeof error.sanitizedMessage === 'string');
+};

package/server/src/utils/index.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Utility modules exports for the Keycloak Realm Users plugin.
+ * @module utils
+ */
+
+export { createSanitizedError, getErrorMessage, isSanitizedError } from './errors.js';