strapi-plugin-keycloak-realm-users 1.0.0

package/dist/server/index.js

@@ -0,0 +1,3003 @@
+"use strict";
+const PLUGIN_ID = "strapi-plugin-keycloak-realm-users";
+const CONTENT_TYPES = {
+  REALM_CONFIG: `plugin::${PLUGIN_ID}.realm-config`,
+  REALM_ADMIN: `plugin::${PLUGIN_ID}.realm-admin`,
+  AUDIT_LOG: `plugin::${PLUGIN_ID}.audit-log`
+};
+const SERVICES = {
+  REALM: "realm",
+  KEYCLOAK_CLIENT: "keycloak-client",
+  USER: "user",
+  PERMISSION: "permission",
+  AUDIT_LOG: "audit-log"
+};
+const AUDIT_ACTIONS = {
+  /** User was created in Keycloak */
+  CREATE_USER: "CREATE_USER",
+  /** User details were modified */
+  UPDATE_USER: "UPDATE_USER",
+  /** User was permanently deleted */
+  DELETE_USER: "DELETE_USER",
+  /** User password was reset */
+  RESET_PASSWORD: "RESET_PASSWORD",
+  /** Realm role was assigned to user */
+  ASSIGN_ROLE: "ASSIGN_ROLE",
+  /** Realm role was removed from user */
+  REMOVE_ROLE: "REMOVE_ROLE",
+  /** User account was enabled */
+  ENABLE_USER: "ENABLE_USER",
+  /** User account was disabled */
+  DISABLE_USER: "DISABLE_USER",
+  /** Email verification was sent */
+  SEND_VERIFY_EMAIL: "SEND_VERIFY_EMAIL",
+  /** Password reset email was sent */
+  SEND_RESET_PASSWORD_EMAIL: "SEND_RESET_PASSWORD_EMAIL",
+  /** Bulk user import was performed */
+  BULK_IMPORT: "BULK_IMPORT"
+};
+const ERROR_MESSAGES = {
+  REALM_NOT_FOUND: "Realm configuration not found.",
+  REALM_DISABLED: "This realm is currently disabled.",
+  USER_NOT_FOUND: "Keycloak user not found.",
+  INSUFFICIENT_PERMISSIONS: "You do not have permission to perform this action.",
+  REALM_ACCESS_DENIED: "You do not have access to this realm.",
+  KEYCLOAK_CONNECTION_FAILED: "Failed to connect to Keycloak server.",
+  KEYCLOAK_AUTH_FAILED: "Failed to authenticate with Keycloak.",
+  INVALID_USER_DATA: "Invalid user data provided.",
+  MISSING_REQUIRED_FIELDS: "Missing required fields.",
+  UNKNOWN_ERROR: "An unexpected error occurred.",
+  USER_ALREADY_EXISTS: "A user with this username or email already exists.",
+  PASSWORD_RESET_FAILED: "Failed to reset password.",
+  EMAIL_SEND_FAILED: "Failed to send email.",
+  ROLE_ASSIGNMENT_FAILED: "Failed to assign roles.",
+  ROLE_REMOVAL_FAILED: "Failed to remove roles.",
+  LOGOUT_FAILED: "Failed to logout user.",
+  INVALID_NAME_FORMAT: "Name must contain only lowercase letters, numbers, and hyphens.",
+  REALM_NAME_EXISTS: "A realm with this name already exists."
+};
+const DEFAULT_REALM_PERMISSIONS = {
+  canRead: true,
+  canCreate: false,
+  canUpdate: false,
+  canDelete: false,
+  canManageRoles: false,
+  canResetPassword: false
+};
+const STRAPI_SUPER_ADMIN_ROLE = "strapi-super-admin";
+const TOKEN_EXPIRY_BUFFER_MS = 6e4;
+const EMAIL_ACTION_LIFESPAN_SECONDS = 43200;
+const DEFAULT_REALM_COLOR = "#4945ff";
+const PAGINATION = {
+  PAGE_SIZE: 25,
+  AUDIT_LOG_LIMIT: 50,
+  EXPORT_BATCH_SIZE: 100
+};
+const HTTP_STATUS = {
+  NO_CONTENT: 204,
+  NOT_FOUND: 404,
+  CONFLICT: 409
+};
+const HTTP_HEADERS = {
+  CONTENT_TYPE_JSON: "application/json",
+  CONTENT_TYPE_FORM: "application/x-www-form-urlencoded"
+};
+const KEYCLOAK_EMAIL_ACTIONS = {
+  VERIFY_EMAIL: "VERIFY_EMAIL",
+  UPDATE_PASSWORD: "UPDATE_PASSWORD"
+};
+const REALM_NAME_PATTERN = /^[a-z0-9-]+$/;
+const UNKNOWN_USER_EMAIL = "unknown";
+const bootstrap = async ({ strapi }) => {
+  try {
+    await strapi.admin.services.permission.actionProvider.registerMany([
+      {
+        uid: `plugin::${PLUGIN_ID}.realm.read`,
+        displayName: "Read Realms",
+        pluginName: PLUGIN_ID,
+        section: "settings",
+        category: "Keycloak User Management",
+        subCategory: "Realms"
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.realm.create`,
+        displayName: "Create Realms",
+        pluginName: PLUGIN_ID,
+        section: "settings",
+        category: "Keycloak User Management",
+        subCategory: "Realms"
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.realm.update`,
+        displayName: "Update Realms",
+        pluginName: PLUGIN_ID,
+        section: "settings",
+        category: "Keycloak User Management",
+        subCategory: "Realms"
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.realm.delete`,
+        displayName: "Delete Realms",
+        pluginName: PLUGIN_ID,
+        section: "settings",
+        category: "Keycloak User Management",
+        subCategory: "Realms"
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.user.read`,
+        displayName: "Read Keycloak Users",
+        pluginName: PLUGIN_ID,
+        section: "settings",
+        category: "Keycloak User Management",
+        subCategory: "Users"
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.user.create`,
+        displayName: "Create Keycloak Users",
+        pluginName: PLUGIN_ID,
+        section: "settings",
+        category: "Keycloak User Management",
+        subCategory: "Users"
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.user.update`,
+        displayName: "Update Keycloak Users",
+        pluginName: PLUGIN_ID,
+        section: "settings",
+        category: "Keycloak User Management",
+        subCategory: "Users"
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.user.delete`,
+        displayName: "Delete Keycloak Users",
+        pluginName: PLUGIN_ID,
+        section: "settings",
+        category: "Keycloak User Management",
+        subCategory: "Users"
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.audit.read`,
+        displayName: "Read Audit Logs",
+        pluginName: PLUGIN_ID,
+        section: "settings",
+        category: "Keycloak User Management",
+        subCategory: "Audit"
+      }
+    ]);
+    strapi.log.info(`[${PLUGIN_ID}] Plugin bootstrapped with permissions registered`);
+  } catch (err) {
+    strapi.log.error(`[${PLUGIN_ID}] Failed to register permissions:`, err);
+  }
+};
+const register = ({ strapi }) => {
+  strapi.log.info(`[${PLUGIN_ID}] Plugin registered successfully`);
+};
+const destroy = ({ strapi }) => {
+};
+const config = {
+  default: {},
+  validator(config2) {
+  }
+};
+const kind$2 = "collectionType";
+const collectionName$2 = "kru_realm_configs";
+const info$2 = {
+  singularName: "realm-config",
+  pluralName: "realm-configs",
+  displayName: "Keycloak Realm"
+};
+const options$2 = {
+  draftAndPublish: false
+};
+const pluginOptions$2 = {
+  "content-manager": {
+    visible: false
+  },
+  "content-type-builder": {
+    visible: false
+  }
+};
+const attributes$2 = {
+  name: {
+    type: "string",
+    required: true,
+    unique: true,
+    regex: "^[a-z0-9-]+$"
+  },
+  displayName: {
+    type: "string",
+    required: true
+  },
+  serverUrl: {
+    type: "string",
+    required: true
+  },
+  realmName: {
+    type: "string",
+    required: true
+  },
+  clientId: {
+    type: "string",
+    required: true
+  },
+  clientSecret: {
+    type: "string",
+    "private": true
+  },
+  enabled: {
+    type: "boolean",
+    "default": true
+  },
+  color: {
+    type: "string",
+    "default": "#4945ff"
+  }
+};
+const schema$2 = {
+  kind: kind$2,
+  collectionName: collectionName$2,
+  info: info$2,
+  options: options$2,
+  pluginOptions: pluginOptions$2,
+  attributes: attributes$2
+};
+const realmConfig = { schema: schema$2 };
+const kind$1 = "collectionType";
+const collectionName$1 = "kru_realm_admins";
+const info$1 = {
+  singularName: "realm-admin",
+  pluralName: "realm-admins",
+  displayName: "Realm Admin Assignment"
+};
+const options$1 = {
+  draftAndPublish: false
+};
+const pluginOptions$1 = {
+  "content-manager": {
+    visible: false
+  },
+  "content-type-builder": {
+    visible: false
+  }
+};
+const attributes$1 = {
+  strapiUserId: {
+    type: "integer",
+    required: true
+  },
+  strapiUserEmail: {
+    type: "string"
+  },
+  realmConfig: {
+    type: "relation",
+    relation: "manyToOne",
+    target: "plugin::strapi-plugin-keycloak-realm-users.realm-config"
+  },
+  permissions: {
+    type: "json",
+    "default": {
+      canRead: true,
+      canCreate: false,
+      canUpdate: false,
+      canDelete: false,
+      canManageRoles: false,
+      canResetPassword: false
+    }
+  }
+};
+const schema$1 = {
+  kind: kind$1,
+  collectionName: collectionName$1,
+  info: info$1,
+  options: options$1,
+  pluginOptions: pluginOptions$1,
+  attributes: attributes$1
+};
+const realmAdmin = { schema: schema$1 };
+const kind = "collectionType";
+const collectionName = "kru_audit_logs";
+const info = {
+  singularName: "audit-log",
+  pluralName: "audit-logs",
+  displayName: "Keycloak Audit Log"
+};
+const options = {
+  draftAndPublish: false
+};
+const pluginOptions = {
+  "content-manager": {
+    visible: true
+  },
+  "content-type-builder": {
+    visible: false
+  }
+};
+const attributes = {
+  realmName: {
+    type: "string",
+    required: true
+  },
+  realmDisplayName: {
+    type: "string"
+  },
+  action: {
+    type: "enumeration",
+    "enum": [
+      "CREATE_USER",
+      "UPDATE_USER",
+      "DELETE_USER",
+      "RESET_PASSWORD",
+      "ASSIGN_ROLE",
+      "REMOVE_ROLE",
+      "ENABLE_USER",
+      "DISABLE_USER",
+      "SEND_VERIFY_EMAIL",
+      "SEND_RESET_PASSWORD_EMAIL",
+      "BULK_IMPORT"
+    ],
+    required: true
+  },
+  keycloakUserId: {
+    type: "string"
+  },
+  keycloakUsername: {
+    type: "string"
+  },
+  details: {
+    type: "json"
+  },
+  performedById: {
+    type: "integer"
+  },
+  performedByEmail: {
+    type: "string"
+  }
+};
+const schema = {
+  kind,
+  collectionName,
+  info,
+  options,
+  pluginOptions,
+  attributes
+};
+const auditLog = { schema };
+const contentTypes = {
+  "realm-config": realmConfig,
+  "realm-admin": realmAdmin,
+  "audit-log": auditLog
+};
+const realmController = ({ strapi }) => ({
+  /**
+   * Get all realms (filtered by user access)
+   */
+  async find(ctx) {
+    const user = ctx.state.user;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const permissionService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+      const realms = await permissionService2.getAccessibleRealms(user);
+      ctx.body = { data: realms };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] realm.find error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Get a single realm by ID
+   */
+  async findOne(ctx) {
+    const user = ctx.state.user;
+    const { id } = ctx.params;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const permissionService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+      const realmService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.REALM);
+      const canAccess = await permissionService2.canAccessRealm(user, id, "canRead");
+      if (!canAccess) {
+        return ctx.forbidden(ERROR_MESSAGES.REALM_ACCESS_DENIED);
+      }
+      const realm = await realmService2.findOne(id);
+      const permissions = await permissionService2.getRealmPermissions(user, id);
+      ctx.body = { data: { ...realm, permissions } };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] realm.findOne error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Create a new realm (super admin only)
+   */
+  async create(ctx) {
+    const user = ctx.state.user;
+    const { data } = ctx.request.body;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const permissionService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+      if (!permissionService2.isSuperAdmin(user)) {
+        return ctx.forbidden("Only super admins can create realm configurations.");
+      }
+      const realmService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.REALM);
+      const realm = await realmService2.create(data);
+      ctx.body = { data: realm };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] realm.create error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Update a realm (super admin only)
+   */
+  async update(ctx) {
+    const user = ctx.state.user;
+    const { id } = ctx.params;
+    const { data } = ctx.request.body;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const permissionService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+      if (!permissionService2.isSuperAdmin(user)) {
+        return ctx.forbidden("Only super admins can update realm configurations.");
+      }
+      const realmService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.REALM);
+      const realm = await realmService2.update(id, data);
+      ctx.body = { data: realm };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] realm.update error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Delete a realm (super admin only)
+   */
+  async delete(ctx) {
+    const user = ctx.state.user;
+    const { id } = ctx.params;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const permissionService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+      if (!permissionService2.isSuperAdmin(user)) {
+        return ctx.forbidden("Only super admins can delete realm configurations.");
+      }
+      const realmService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.REALM);
+      await realmService2.delete(id);
+      ctx.body = { data: { success: true } };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] realm.delete error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Test realm connection
+   */
+  async testConnection(ctx) {
+    const user = ctx.state.user;
+    const { id } = ctx.params;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const permissionService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+      const realmService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.REALM);
+      const canAccess = await permissionService2.canAccessRealm(user, id, "canRead");
+      if (!canAccess) {
+        return ctx.forbidden(ERROR_MESSAGES.REALM_ACCESS_DENIED);
+      }
+      const result = await realmService2.testConnection(id);
+      ctx.body = { data: result };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] realm.testConnection error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Test connection before saving (with raw config)
+   */
+  async testConnectionRaw(ctx) {
+    const user = ctx.state.user;
+    const { data } = ctx.request.body;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const permissionService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+      if (!permissionService2.isSuperAdmin(user)) {
+        return ctx.forbidden("Only super admins can test realm configurations.");
+      }
+      const realmService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.REALM);
+      const result = await realmService2.testConnectionRaw(data);
+      ctx.body = { data: result };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] realm.testConnectionRaw error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Get admins assigned to a realm
+   */
+  async getAdmins(ctx) {
+    const user = ctx.state.user;
+    const { id } = ctx.params;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const permissionService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+      if (!permissionService2.isSuperAdmin(user)) {
+        return ctx.forbidden("Only super admins can view realm admin assignments.");
+      }
+      const admins = await permissionService2.getRealmAdmins(id);
+      ctx.body = { data: admins };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] realm.getAdmins error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Assign an admin to a realm
+   */
+  async addAdmin(ctx) {
+    const user = ctx.state.user;
+    const { id } = ctx.params;
+    const { data } = ctx.request.body;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const permissionService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+      if (!permissionService2.isSuperAdmin(user)) {
+        return ctx.forbidden("Only super admins can assign realm admins.");
+      }
+      const { strapiUserId, strapiUserEmail, permissions } = data;
+      if (!strapiUserId) {
+        return ctx.badRequest("strapiUserId is required.");
+      }
+      const assignment = await permissionService2.assignUserToRealm(
+        strapiUserId,
+        strapiUserEmail,
+        id,
+        permissions
+      );
+      ctx.body = { data: assignment };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] realm.addAdmin error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Update admin permissions for a realm
+   */
+  async updateAdmin(ctx) {
+    const user = ctx.state.user;
+    const { id, adminId } = ctx.params;
+    const { data } = ctx.request.body;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const permissionService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+      if (!permissionService2.isSuperAdmin(user)) {
+        return ctx.forbidden("Only super admins can update realm admin assignments.");
+      }
+      const { permissions } = data;
+      const assignment = await permissionService2.assignUserToRealm(
+        parseInt(adminId, 10),
+        null,
+        id,
+        permissions
+      );
+      ctx.body = { data: assignment };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] realm.updateAdmin error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Remove an admin from a realm
+   */
+  async removeAdmin(ctx) {
+    const user = ctx.state.user;
+    const { id, adminId } = ctx.params;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const permissionService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+      if (!permissionService2.isSuperAdmin(user)) {
+        return ctx.forbidden("Only super admins can remove realm admins.");
+      }
+      await permissionService2.removeUserFromRealm(parseInt(adminId, 10), id);
+      ctx.body = { data: { success: true } };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] realm.removeAdmin error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  }
+});
+const userController = ({ strapi }) => ({
+  /**
+   * List users in a realm
+   */
+  async find(ctx) {
+    const user = ctx.state.user;
+    const { realmId } = ctx.params;
+    const { search, page = 1, pageSize = 25 } = ctx.query;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      const result = await userService2.listUsers(
+        realmId,
+        { search, page: parseInt(page, 10), pageSize: parseInt(pageSize, 10) },
+        user
+      );
+      ctx.body = { data: result };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.find error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Get a single user
+   */
+  async findOne(ctx) {
+    const user = ctx.state.user;
+    const { realmId, id } = ctx.params;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      const keycloakUser = await userService2.getUser(realmId, id, user);
+      ctx.body = { data: keycloakUser };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.findOne error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Create a new user
+   */
+  async create(ctx) {
+    const user = ctx.state.user;
+    const { realmId } = ctx.params;
+    const { data } = ctx.request.body;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      const keycloakUser = await userService2.createUser(realmId, data, user);
+      ctx.body = { data: keycloakUser };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.create error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Update a user
+   */
+  async update(ctx) {
+    const user = ctx.state.user;
+    const { realmId, id } = ctx.params;
+    const { data } = ctx.request.body;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      const keycloakUser = await userService2.updateUser(realmId, id, data, user);
+      ctx.body = { data: keycloakUser };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.update error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Delete a user
+   */
+  async delete(ctx) {
+    const user = ctx.state.user;
+    const { realmId, id } = ctx.params;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      await userService2.deleteUser(realmId, id, user);
+      ctx.body = { data: { success: true } };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.delete error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Reset user password
+   */
+  async resetPassword(ctx) {
+    const user = ctx.state.user;
+    const { realmId, id } = ctx.params;
+    const { data } = ctx.request.body;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const { password, temporary = true } = data;
+      if (!password) {
+        return ctx.badRequest("Password is required.");
+      }
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      await userService2.resetPassword(realmId, id, password, temporary, user);
+      ctx.body = { data: { success: true } };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.resetPassword error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Enable a user
+   */
+  async enable(ctx) {
+    const user = ctx.state.user;
+    const { realmId, id } = ctx.params;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      await userService2.enableUser(realmId, id, user);
+      ctx.body = { data: { success: true } };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.enable error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Disable a user
+   */
+  async disable(ctx) {
+    const user = ctx.state.user;
+    const { realmId, id } = ctx.params;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      await userService2.disableUser(realmId, id, user);
+      ctx.body = { data: { success: true } };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.disable error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Send verification email
+   */
+  async sendVerifyEmail(ctx) {
+    const user = ctx.state.user;
+    const { realmId, id } = ctx.params;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      await userService2.sendVerificationEmail(realmId, id, user);
+      ctx.body = { data: { success: true } };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.sendVerifyEmail error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Send password reset email
+   */
+  async sendResetPasswordEmail(ctx) {
+    const user = ctx.state.user;
+    const { realmId, id } = ctx.params;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      await userService2.sendResetPasswordEmail(realmId, id, user);
+      ctx.body = { data: { success: true } };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.sendResetPasswordEmail error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Get realm roles
+   */
+  async getRoles(ctx) {
+    const user = ctx.state.user;
+    const { realmId } = ctx.params;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      const roles = await userService2.getRoles(realmId, user);
+      ctx.body = { data: roles };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.getRoles error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Get user's roles
+   */
+  async getUserRoles(ctx) {
+    const user = ctx.state.user;
+    const { realmId, id } = ctx.params;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      const roles = await userService2.getUserRoles(realmId, id, user);
+      ctx.body = { data: roles };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.getUserRoles error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Assign roles to user
+   */
+  async assignRoles(ctx) {
+    const user = ctx.state.user;
+    const { realmId, id } = ctx.params;
+    const { data } = ctx.request.body;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const { roles } = data;
+      if (!roles || !Array.isArray(roles)) {
+        return ctx.badRequest("Roles array is required.");
+      }
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      await userService2.assignRoles(realmId, id, roles, user);
+      ctx.body = { data: { success: true } };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.assignRoles error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Remove roles from user
+   */
+  async removeRoles(ctx) {
+    const user = ctx.state.user;
+    const { realmId, id } = ctx.params;
+    const { data } = ctx.request.body;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const { roles } = data;
+      if (!roles || !Array.isArray(roles)) {
+        return ctx.badRequest("Roles array is required.");
+      }
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      await userService2.removeRoles(realmId, id, roles, user);
+      ctx.body = { data: { success: true } };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.removeRoles error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Bulk import users
+   */
+  async bulkImport(ctx) {
+    const user = ctx.state.user;
+    const { realmId } = ctx.params;
+    const { data } = ctx.request.body;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const { users } = data;
+      if (!users || !Array.isArray(users)) {
+        return ctx.badRequest("Users array is required.");
+      }
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      const result = await userService2.bulkImport(realmId, users, user);
+      ctx.body = { data: result };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.bulkImport error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Export users
+   */
+  async exportUsers(ctx) {
+    const user = ctx.state.user;
+    const { realmId } = ctx.params;
+    const { format = "json" } = ctx.query;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const userService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.USER);
+      const users = await userService2.exportUsers(realmId, user);
+      if (format === "csv") {
+        const headers = ["id", "username", "email", "firstName", "lastName", "enabled", "emailVerified"];
+        const csvRows = [headers.join(",")];
+        for (const u of users) {
+          const row = headers.map((h) => {
+            const val = u[h];
+            if (val === void 0 || val === null) return "";
+            if (typeof val === "string" && val.includes(",")) return `"${val}"`;
+            return String(val);
+          });
+          csvRows.push(row.join(","));
+        }
+        ctx.set("Content-Type", "text/csv");
+        ctx.set("Content-Disposition", `attachment; filename="keycloak-users-${realmId}.csv"`);
+        ctx.body = csvRows.join("\n");
+      } else {
+        ctx.body = { data: users };
+      }
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] user.exportUsers error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  }
+});
+const auditController = ({ strapi }) => ({
+  /**
+   * Find audit logs with filters
+   */
+  async find(ctx) {
+    const user = ctx.state.user;
+    const { realmName, action, limit = 50, offset = 0 } = ctx.query;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const permissionService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+      if (!permissionService2.isSuperAdmin(user)) {
+        const accessibleRealms = await permissionService2.getAccessibleRealms(user);
+        const accessibleRealmNames = accessibleRealms.map((r) => r.name);
+        if (realmName && !accessibleRealmNames.includes(realmName)) {
+          return ctx.forbidden(ERROR_MESSAGES.REALM_ACCESS_DENIED);
+        }
+        const auditLogService3 = strapi.plugin(PLUGIN_ID).service(SERVICES.AUDIT_LOG);
+        if (!realmName) {
+          const allLogs = [];
+          for (const rn of accessibleRealmNames) {
+            const { entries } = await auditLogService3.find({
+              realmName: rn,
+              action,
+              limit: parseInt(limit, 10),
+              offset: parseInt(offset, 10)
+            });
+            allLogs.push(...entries);
+          }
+          allLogs.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
+          ctx.body = { data: allLogs.slice(0, parseInt(limit, 10)) };
+          return;
+        }
+      }
+      const auditLogService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.AUDIT_LOG);
+      const result = await auditLogService2.find({
+        realmName,
+        action,
+        limit: parseInt(limit, 10),
+        offset: parseInt(offset, 10)
+      });
+      ctx.body = { data: result.entries, meta: { total: result.total } };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] audit.find error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Find audit logs by realm
+   */
+  async findByRealm(ctx) {
+    const user = ctx.state.user;
+    const { realmId } = ctx.params;
+    const { limit = 50, offset = 0 } = ctx.query;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const permissionService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+      const realmService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.REALM);
+      const canAccess = await permissionService2.canAccessRealm(user, realmId, "canRead");
+      if (!canAccess) {
+        return ctx.forbidden(ERROR_MESSAGES.REALM_ACCESS_DENIED);
+      }
+      const realm = await realmService2.findOne(realmId);
+      const auditLogService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.AUDIT_LOG);
+      const result = await auditLogService2.findByRealm(realm.name, {
+        limit: parseInt(limit, 10),
+        offset: parseInt(offset, 10)
+      });
+      ctx.body = { data: result.entries, meta: { total: result.total } };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] audit.findByRealm error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  },
+  /**
+   * Find audit logs by Keycloak user
+   */
+  async findByUser(ctx) {
+    const user = ctx.state.user;
+    const { keycloakUserId } = ctx.params;
+    const { limit = 50, offset = 0 } = ctx.query;
+    if (!user) {
+      return ctx.unauthorized(ERROR_MESSAGES.INSUFFICIENT_PERMISSIONS);
+    }
+    try {
+      const auditLogService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.AUDIT_LOG);
+      const result = await auditLogService2.findByKeycloakUser(keycloakUserId, {
+        limit: parseInt(limit, 10),
+        offset: parseInt(offset, 10)
+      });
+      const permissionService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+      if (!permissionService2.isSuperAdmin(user)) {
+        const accessibleRealms = await permissionService2.getAccessibleRealms(user);
+        const accessibleRealmNames = accessibleRealms.map((r) => r.name);
+        const filteredEntries = result.entries.filter(
+          (e) => accessibleRealmNames.includes(e.realmName)
+        );
+        ctx.body = { data: filteredEntries, meta: { total: filteredEntries.length } };
+        return;
+      }
+      ctx.body = { data: result.entries, meta: { total: result.total } };
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] audit.findByUser error:`, err);
+      ctx.throw(400, err.sanitizedMessage || ERROR_MESSAGES.UNKNOWN_ERROR);
+    }
+  }
+});
+const controllers = {
+  realm: realmController,
+  user: userController,
+  audit: auditController
+};
+const createSanitizedError = (internalMessage, sanitizedMessage) => {
+  const err = new Error(internalMessage);
+  err.sanitizedMessage = sanitizedMessage;
+  return err;
+};
+const TOKEN_CACHE = /* @__PURE__ */ new Map();
+const getCacheKey = (realmConfig2) => `${realmConfig2.serverUrl}:${realmConfig2.realmName}:${realmConfig2.clientId}`;
+const buildTokenUrl = (serverUrl, realmName) => `${serverUrl}/realms/${realmName}/protocol/openid-connect/token`;
+const buildAdminUrl = (serverUrl, realmName, path = "") => `${serverUrl}/admin/realms/${realmName}${path}`;
+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(realmConfig2) {
+    const cacheKey = getCacheKey(realmConfig2);
+    const cached = TOKEN_CACHE.get(cacheKey);
+    if (cached && Date.now() < cached.expiresAt - TOKEN_EXPIRY_BUFFER_MS) {
+      return cached.accessToken;
+    }
+    try {
+      const tokenUrl = buildTokenUrl(realmConfig2.serverUrl, realmConfig2.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: realmConfig2.clientId,
+          client_secret: realmConfig2.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();
+      TOKEN_CACHE.set(cacheKey, {
+        accessToken: data.access_token,
+        expiresAt: Date.now() + data.expires_in * 1e3
+      });
+      return data.access_token;
+    } catch (err) {
+      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(realmConfig2) {
+    try {
+      const token = await this.getAccessToken(realmConfig2);
+      const url = buildAdminUrl(realmConfig2.serverUrl, realmConfig2.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(realmConfig2, { search = "", first = 0, max = PAGINATION.PAGE_SIZE, briefRepresentation = true } = {}) {
+    const token = await this.getAccessToken(realmConfig2);
+    const params = new URLSearchParams({
+      first: String(first),
+      max: String(max),
+      briefRepresentation: String(briefRepresentation)
+    });
+    if (search) {
+      params.set("search", search);
+    }
+    const url = `${buildAdminUrl(realmConfig2.serverUrl, realmConfig2.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(realmConfig2, { search = "" } = {}) {
+    const token = await this.getAccessToken(realmConfig2);
+    const params = new URLSearchParams();
+    if (search) params.set("search", search);
+    const url = `${buildAdminUrl(realmConfig2.serverUrl, realmConfig2.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(realmConfig2, userId) {
+    const token = await this.getAccessToken(realmConfig2);
+    const url = buildAdminUrl(realmConfig2.serverUrl, realmConfig2.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(realmConfig2, userData) {
+    const token = await this.getAccessToken(realmConfig2);
+    const url = buildAdminUrl(realmConfig2.serverUrl, realmConfig2.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);
+    }
+    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(realmConfig2, userId, userData) {
+    const token = await this.getAccessToken(realmConfig2);
+    const url = buildAdminUrl(realmConfig2.serverUrl, realmConfig2.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(realmConfig2, userId) {
+    const token = await this.getAccessToken(realmConfig2);
+    const url = buildAdminUrl(realmConfig2.serverUrl, realmConfig2.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(realmConfig2, userId, password, temporary = true) {
+    const token = await this.getAccessToken(realmConfig2);
+    const url = buildAdminUrl(realmConfig2.serverUrl, realmConfig2.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(realmConfig2, userId) {
+    return this.updateUser(realmConfig2, 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(realmConfig2, userId) {
+    return this.updateUser(realmConfig2, 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(realmConfig2, userId, actions, lifespan = EMAIL_ACTION_LIFESPAN_SECONDS) {
+    const token = await this.getAccessToken(realmConfig2);
+    const params = new URLSearchParams({ lifespan: String(lifespan) });
+    const url = `${buildAdminUrl(realmConfig2.serverUrl, realmConfig2.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(realmConfig2, userId) {
+    return this.executeEmailActions(realmConfig2, 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(realmConfig2, userId) {
+    return this.executeEmailActions(realmConfig2, 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(realmConfig2) {
+    const token = await this.getAccessToken(realmConfig2);
+    const url = buildAdminUrl(realmConfig2.serverUrl, realmConfig2.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(realmConfig2, userId) {
+    const token = await this.getAccessToken(realmConfig2);
+    const url = buildAdminUrl(realmConfig2.serverUrl, realmConfig2.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(realmConfig2, userId, roles) {
+    const token = await this.getAccessToken(realmConfig2);
+    const url = buildAdminUrl(realmConfig2.serverUrl, realmConfig2.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(realmConfig2, userId, roles) {
+    const token = await this.getAccessToken(realmConfig2);
+    const url = buildAdminUrl(realmConfig2.serverUrl, realmConfig2.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(realmConfig2, userId) {
+    const token = await this.getAccessToken(realmConfig2);
+    const url = buildAdminUrl(realmConfig2.serverUrl, realmConfig2.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(realmConfig2, userId) {
+    const token = await this.getAccessToken(realmConfig2);
+    const url = buildAdminUrl(realmConfig2.serverUrl, realmConfig2.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(realmConfig2) {
+    if (realmConfig2) {
+      const cacheKey = getCacheKey(realmConfig2);
+      TOKEN_CACHE.delete(cacheKey);
+    } else {
+      TOKEN_CACHE.clear();
+    }
+  }
+});
+const auditLogService = ({ strapi }) => ({
+  /**
+   * Creates an audit log entry.
+   * This method is designed to be non-blocking and fail-safe - audit logging
+   * errors are caught and logged but do not interrupt the main operation.
+   *
+   * @param {AuditLogParams} params - Log entry parameters
+   * @returns {Promise<AuditLogEntry|undefined>} Created entry or undefined on error
+   *
+   * @example
+   * await auditLogService.log({
+   *   realmName: 'production',
+   *   realmDisplayName: 'Production Users',
+   *   action: AUDIT_ACTIONS.CREATE_USER,
+   *   keycloakUserId: 'user-123',
+   *   keycloakUsername: 'john.doe',
+   *   details: { email: 'john@example.com' },
+   *   user: ctx.state.user
+   * });
+   */
+  async log({ realmName, realmDisplayName, action, keycloakUserId, keycloakUsername, details, user }) {
+    try {
+      return await strapi.documents(CONTENT_TYPES.AUDIT_LOG).create({
+        data: {
+          realmName,
+          realmDisplayName: realmDisplayName || realmName,
+          action,
+          keycloakUserId: keycloakUserId || null,
+          keycloakUsername: keycloakUsername || null,
+          details: details || null,
+          performedById: user?.id || null,
+          performedByEmail: user?.email || UNKNOWN_USER_EMAIL
+        }
+      });
+    } catch (err) {
+      strapi.log.error(`[${PLUGIN_ID}] Failed to create audit log entry:`, err);
+    }
+  },
+  /**
+   * Queries audit log entries with optional filters.
+   *
+   * @param {AuditLogQueryParams} [params={}] - Query parameters
+   * @returns {Promise<AuditLogQueryResult>} Paginated log entries with total count
+   *
+   * @example
+   * // Get all entries for a realm
+   * const { entries, total } = await auditLogService.find({
+   *   realmName: 'production',
+   *   limit: 25,
+   *   offset: 0
+   * });
+   *
+   * @example
+   * // Get all password reset actions
+   * const { entries } = await auditLogService.find({
+   *   action: AUDIT_ACTIONS.RESET_PASSWORD
+   * });
+   */
+  async find({
+    realmName,
+    action,
+    keycloakUserId,
+    limit = PAGINATION.AUDIT_LOG_LIMIT,
+    offset = 0
+  } = {}) {
+    const filters = {};
+    if (realmName) {
+      filters.realmName = realmName;
+    }
+    if (action) {
+      filters.action = action;
+    }
+    if (keycloakUserId) {
+      filters.keycloakUserId = keycloakUserId;
+    }
+    const [entries, count] = await Promise.all([
+      strapi.documents(CONTENT_TYPES.AUDIT_LOG).findMany({
+        filters,
+        sort: { createdAt: "desc" },
+        limit,
+        offset
+      }),
+      strapi.documents(CONTENT_TYPES.AUDIT_LOG).count({ filters })
+    ]);
+    return { entries, total: count };
+  },
+  /**
+   * Retrieves audit logs for a specific realm.
+   * Convenience method that wraps find() with realm filter.
+   *
+   * @param {string} realmName - Realm slug identifier
+   * @param {Object} [options={}] - Query options
+   * @param {number} [options.limit=50] - Maximum entries
+   * @param {number} [options.offset=0] - Starting offset
+   * @returns {Promise<AuditLogQueryResult>} Paginated log entries
+   *
+   * @example
+   * const { entries, total } = await auditLogService.findByRealm('production', {
+   *   limit: 100
+   * });
+   */
+  async findByRealm(realmName, { limit = PAGINATION.AUDIT_LOG_LIMIT, offset = 0 } = {}) {
+    return this.find({ realmName, limit, offset });
+  },
+  /**
+   * Retrieves audit logs for a specific Keycloak user.
+   * Useful for viewing all actions performed on a single user.
+   *
+   * @param {string} keycloakUserId - Keycloak user ID
+   * @param {Object} [options={}] - Query options
+   * @param {number} [options.limit=50] - Maximum entries
+   * @param {number} [options.offset=0] - Starting offset
+   * @returns {Promise<AuditLogQueryResult>} Paginated log entries
+   *
+   * @example
+   * const { entries } = await auditLogService.findByKeycloakUser('user-123');
+   * // Shows: created, updated, password reset, role changes, etc.
+   */
+  async findByKeycloakUser(keycloakUserId, { limit = PAGINATION.AUDIT_LOG_LIMIT, offset = 0 } = {}) {
+    return this.find({ keycloakUserId, limit, offset });
+  }
+});
+const SUPER_ADMIN_PERMISSIONS = {
+  canRead: true,
+  canCreate: true,
+  canUpdate: true,
+  canDelete: true,
+  canManageRoles: true,
+  canResetPassword: true
+};
+const permissionService = ({ strapi }) => ({
+  /**
+   * Checks if a user has the Strapi super admin role.
+   * Super admins have unrestricted access to all realms and operations.
+   *
+   * @param {StrapiUser} user - Strapi user object with roles
+   * @returns {boolean} True if user is a super admin
+   *
+   * @example
+   * if (permissionService.isSuperAdmin(ctx.state.user)) {
+   *   // Allow unrestricted access
+   * }
+   */
+  isSuperAdmin(user) {
+    if (!user || !user.roles) return false;
+    return user.roles.some((role) => role.code === STRAPI_SUPER_ADMIN_ROLE);
+  },
+  /**
+   * Retrieves the realm admin assignment for a specific user and realm.
+   *
+   * @param {number} strapiUserId - Strapi user ID
+   * @param {string} realmConfigId - Realm document ID
+   * @returns {Promise<RealmAdminAssignment|null>} Assignment or null if none exists
+   *
+   * @example
+   * const assignment = await permissionService.getRealmAdminAssignment(user.id, realmId);
+   * if (assignment?.permissions.canCreate) {
+   *   // User can create
+   * }
+   */
+  async getRealmAdminAssignment(strapiUserId, realmConfigId) {
+    const assignments = await strapi.documents(CONTENT_TYPES.REALM_ADMIN).findMany({
+      filters: {
+        strapiUserId,
+        realmConfig: { documentId: realmConfigId }
+      },
+      populate: ["realmConfig"]
+    });
+    return assignments[0] || null;
+  },
+  /**
+   * Checks if a user has a specific permission for a realm.
+   *
+   * @param {StrapiUser} user - Strapi user object
+   * @param {string} realmConfigId - Realm document ID
+   * @param {keyof RealmPermissions} [permission='canRead'] - Permission to check
+   * @returns {Promise<boolean>} True if user has the permission
+   *
+   * @example
+   * const canDelete = await permissionService.canAccessRealm(user, realmId, 'canDelete');
+   * if (!canDelete) {
+   *   throw new ForbiddenError();
+   * }
+   */
+  async canAccessRealm(user, realmConfigId, permission = "canRead") {
+    if (this.isSuperAdmin(user)) {
+      return true;
+    }
+    const assignment = await this.getRealmAdminAssignment(user.id, realmConfigId);
+    if (!assignment) {
+      return false;
+    }
+    const permissions = assignment.permissions || DEFAULT_REALM_PERMISSIONS;
+    return permissions[permission] === true;
+  },
+  /**
+   * Retrieves all realms accessible by a user with their permissions.
+   * Super admins see all enabled realms with full permissions.
+   * Regular users see only realms they're assigned to.
+   *
+   * @param {StrapiUser} user - Strapi user object
+   * @returns {Promise<Array<Object & {permissions: RealmPermissions}>>} Accessible realms with permissions
+   *
+   * @example
+   * const realms = await permissionService.getAccessibleRealms(ctx.state.user);
+   * // Returns realms with permissions attached
+   */
+  async getAccessibleRealms(user) {
+    if (this.isSuperAdmin(user)) {
+      const allRealms = await strapi.documents(CONTENT_TYPES.REALM_CONFIG).findMany({
+        filters: { enabled: true },
+        sort: { displayName: "asc" }
+      });
+      return allRealms.map((realm) => ({
+        ...realm,
+        permissions: SUPER_ADMIN_PERMISSIONS
+      }));
+    }
+    const assignments = await strapi.documents(CONTENT_TYPES.REALM_ADMIN).findMany({
+      filters: {
+        strapiUserId: user.id,
+        realmConfig: { enabled: true }
+      },
+      populate: ["realmConfig"]
+    });
+    return assignments.filter((assignment) => assignment.realmConfig).map((assignment) => ({
+      ...assignment.realmConfig,
+      permissions: assignment.permissions || DEFAULT_REALM_PERMISSIONS
+    }));
+  },
+  /**
+   * Gets a user's specific permissions for a realm.
+   *
+   * @param {StrapiUser} user - Strapi user object
+   * @param {string} realmConfigId - Realm document ID
+   * @returns {Promise<RealmPermissions|null>} User's permissions or null if no access
+   *
+   * @example
+   * const permissions = await permissionService.getRealmPermissions(user, realmId);
+   * if (permissions?.canUpdate) {
+   *   // Show edit button
+   * }
+   */
+  async getRealmPermissions(user, realmConfigId) {
+    if (this.isSuperAdmin(user)) {
+      return SUPER_ADMIN_PERMISSIONS;
+    }
+    const assignment = await this.getRealmAdminAssignment(user.id, realmConfigId);
+    return assignment?.permissions || null;
+  },
+  /**
+   * Assigns a Strapi user to a realm with specified permissions.
+   * If an assignment already exists, it updates the permissions.
+   *
+   * @param {number} strapiUserId - Strapi user ID to assign
+   * @param {string} strapiUserEmail - User's email for reference
+   * @param {string} realmConfigId - Realm document ID
+   * @param {Partial<RealmPermissions>} [permissions={}] - Permissions to grant
+   * @returns {Promise<RealmAdminAssignment>} Created or updated assignment
+   *
+   * @example
+   * await permissionService.assignUserToRealm(
+   *   userId,
+   *   'admin@example.com',
+   *   realmId,
+   *   { canRead: true, canCreate: true, canUpdate: true }
+   * );
+   */
+  async assignUserToRealm(strapiUserId, strapiUserEmail, realmConfigId, permissions = {}) {
+    const existing = await this.getRealmAdminAssignment(strapiUserId, realmConfigId);
+    const mergedPermissions = { ...DEFAULT_REALM_PERMISSIONS, ...permissions };
+    if (existing) {
+      return strapi.documents(CONTENT_TYPES.REALM_ADMIN).update({
+        documentId: existing.documentId,
+        data: {
+          permissions: mergedPermissions
+        }
+      });
+    }
+    return strapi.documents(CONTENT_TYPES.REALM_ADMIN).create({
+      data: {
+        strapiUserId,
+        strapiUserEmail,
+        realmConfig: realmConfigId,
+        permissions: mergedPermissions
+      }
+    });
+  },
+  /**
+   * Removes a user's access to a realm.
+   *
+   * @param {number} strapiUserId - Strapi user ID
+   * @param {string} realmConfigId - Realm document ID
+   * @returns {Promise<boolean>} True if assignment was removed, false if none existed
+   *
+   * @example
+   * const removed = await permissionService.removeUserFromRealm(userId, realmId);
+   */
+  async removeUserFromRealm(strapiUserId, realmConfigId) {
+    const assignment = await this.getRealmAdminAssignment(strapiUserId, realmConfigId);
+    if (assignment) {
+      await strapi.documents(CONTENT_TYPES.REALM_ADMIN).delete({
+        documentId: assignment.documentId
+      });
+      return true;
+    }
+    return false;
+  },
+  /**
+   * Retrieves all admin assignments for a specific realm.
+   *
+   * @param {string} realmConfigId - Realm document ID
+   * @returns {Promise<RealmAdminAssignment[]>} Array of admin assignments
+   *
+   * @example
+   * const admins = await permissionService.getRealmAdmins(realmId);
+   * // Display list of users who can manage this realm
+   */
+  async getRealmAdmins(realmConfigId) {
+    const assignments = await strapi.documents(CONTENT_TYPES.REALM_ADMIN).findMany({
+      filters: {
+        realmConfig: { documentId: realmConfigId }
+      }
+    });
+    return assignments;
+  }
+});
+const realmService = ({ strapi }) => ({
+  /**
+   * Gets the Keycloak client service instance.
+   *
+   * @returns {Object} Keycloak client service
+   * @private
+   */
+  get keycloakClient() {
+    return strapi.plugin(PLUGIN_ID).service(SERVICES.KEYCLOAK_CLIENT);
+  },
+  /**
+   * Retrieves all realm configurations.
+   * Note: clientSecret is not included in results (private field).
+   *
+   * @returns {Promise<RealmConfig[]>} Array of realm configurations sorted by displayName
+   *
+   * @example
+   * const realms = await realmService.findAll();
+   */
+  async findAll() {
+    return strapi.documents(CONTENT_TYPES.REALM_CONFIG).findMany({
+      sort: { displayName: "asc" }
+    });
+  },
+  /**
+   * Retrieves a single realm by document ID.
+   * Note: clientSecret is not included (private field).
+   *
+   * @param {string} documentId - Strapi document ID
+   * @returns {Promise<RealmConfig>} Realm configuration
+   * @throws {Error} If realm not found
+   *
+   * @example
+   * const realm = await realmService.findOne('abc123');
+   */
+  async findOne(documentId) {
+    const realm = await strapi.documents(CONTENT_TYPES.REALM_CONFIG).findOne({
+      documentId
+    });
+    if (!realm) {
+      throw createSanitizedError(
+        `Realm ${documentId} not found`,
+        ERROR_MESSAGES.REALM_NOT_FOUND
+      );
+    }
+    return realm;
+  },
+  /**
+   * Retrieves a realm with its clientSecret for internal Keycloak API calls.
+   * Uses db.query to bypass Strapi's private field sanitization.
+   *
+   * SECURITY: Only use this method when the clientSecret is actually needed
+   * for Keycloak authentication. Never expose the result to API responses.
+   *
+   * @param {string} documentId - Strapi document ID
+   * @returns {Promise<RealmConfig & {clientSecret: string}>} Full realm config with secret
+   * @throws {Error} If realm not found
+   *
+   * @example
+   * // Internal use only - for Keycloak API calls
+   * const realm = await realmService.findOneWithSecret(documentId);
+   * const token = await keycloakClient.getAccessToken(realm);
+   */
+  async findOneWithSecret(documentId) {
+    const realm = await strapi.db.query(CONTENT_TYPES.REALM_CONFIG).findOne({
+      where: { documentId }
+    });
+    if (!realm) {
+      throw createSanitizedError(
+        `Realm ${documentId} not found`,
+        ERROR_MESSAGES.REALM_NOT_FOUND
+      );
+    }
+    return realm;
+  },
+  /**
+   * Finds a realm by its unique slug name.
+   *
+   * @param {string} name - Realm slug name
+   * @returns {Promise<RealmConfig|null>} Realm configuration or null if not found
+   *
+   * @example
+   * const realm = await realmService.findByName('production-users');
+   */
+  async findByName(name) {
+    const realms = await strapi.documents(CONTENT_TYPES.REALM_CONFIG).findMany({
+      filters: { name }
+    });
+    return realms[0] || null;
+  },
+  /**
+   * Validates realm name format.
+   *
+   * @param {string} name - Name to validate
+   * @returns {boolean} True if valid
+   * @private
+   */
+  isValidName(name) {
+    return REALM_NAME_PATTERN.test(name);
+  },
+  /**
+   * Normalizes a server URL by removing trailing slashes.
+   *
+   * @param {string} url - URL to normalize
+   * @returns {string} Normalized URL
+   * @private
+   */
+  normalizeServerUrl(url) {
+    return url.replace(/\/$/, "");
+  },
+  /**
+   * Creates a new realm configuration.
+   *
+   * @param {RealmConfigData} data - Realm configuration data
+   * @returns {Promise<RealmConfig>} Created realm configuration
+   * @throws {Error} If validation fails or name already exists
+   *
+   * @example
+   * const realm = await realmService.create({
+   *   name: 'production-users',
+   *   displayName: 'Production Users',
+   *   serverUrl: 'https://keycloak.example.com',
+   *   realmName: 'production',
+   *   clientId: 'strapi-admin',
+   *   clientSecret: 'secret-value'
+   * });
+   */
+  async create(data) {
+    const { name, displayName, serverUrl, realmName, clientId, clientSecret } = data;
+    if (!name || !displayName || !serverUrl || !realmName || !clientId) {
+      throw createSanitizedError(
+        "Missing required fields",
+        ERROR_MESSAGES.MISSING_REQUIRED_FIELDS
+      );
+    }
+    if (!this.isValidName(name)) {
+      throw createSanitizedError(
+        `Invalid name format: ${name}`,
+        ERROR_MESSAGES.INVALID_NAME_FORMAT
+      );
+    }
+    const existing = await this.findByName(name);
+    if (existing) {
+      throw createSanitizedError(
+        `Realm with name ${name} already exists`,
+        ERROR_MESSAGES.REALM_NAME_EXISTS
+      );
+    }
+    return strapi.documents(CONTENT_TYPES.REALM_CONFIG).create({
+      data: {
+        name,
+        displayName,
+        serverUrl: this.normalizeServerUrl(serverUrl),
+        realmName,
+        clientId,
+        clientSecret: clientSecret || null,
+        enabled: data.enabled !== false,
+        color: data.color || DEFAULT_REALM_COLOR
+      }
+    });
+  },
+  /**
+   * Updates an existing realm configuration.
+   *
+   * @param {string} documentId - Strapi document ID
+   * @param {Partial<RealmConfigData>} data - Fields to update
+   * @returns {Promise<RealmConfig>} Updated realm configuration
+   * @throws {Error} If validation fails or realm not found
+   *
+   * @example
+   * const updated = await realmService.update(documentId, {
+   *   displayName: 'New Display Name',
+   *   enabled: false
+   * });
+   */
+  async update(documentId, data) {
+    const existing = await this.findOne(documentId);
+    if (data.name && data.name !== existing.name) {
+      if (!this.isValidName(data.name)) {
+        throw createSanitizedError(
+          `Invalid name format: ${data.name}`,
+          ERROR_MESSAGES.INVALID_NAME_FORMAT
+        );
+      }
+      const duplicate = await this.findByName(data.name);
+      if (duplicate && duplicate.documentId !== documentId) {
+        throw createSanitizedError(
+          `Realm with name ${data.name} already exists`,
+          ERROR_MESSAGES.REALM_NAME_EXISTS
+        );
+      }
+    }
+    const updateData = { ...data };
+    if (updateData.serverUrl) {
+      updateData.serverUrl = this.normalizeServerUrl(updateData.serverUrl);
+    }
+    const connectionFieldsChanged = updateData.serverUrl || updateData.realmName || updateData.clientId || updateData.clientSecret;
+    if (connectionFieldsChanged) {
+      this.keycloakClient.clearTokenCache(existing);
+    }
+    return strapi.documents(CONTENT_TYPES.REALM_CONFIG).update({
+      documentId,
+      data: updateData
+    });
+  },
+  /**
+   * Deletes a realm configuration and all associated admin assignments.
+   *
+   * @param {string} documentId - Strapi document ID
+   * @returns {Promise<{success: boolean}>} Success indicator
+   * @throws {Error} If realm not found
+   *
+   * @example
+   * await realmService.delete(documentId);
+   */
+  async delete(documentId) {
+    const realm = await this.findOne(documentId);
+    this.keycloakClient.clearTokenCache(realm);
+    const assignments = await strapi.documents(CONTENT_TYPES.REALM_ADMIN).findMany({
+      filters: {
+        realmConfig: { documentId }
+      }
+    });
+    for (const assignment of assignments) {
+      await strapi.documents(CONTENT_TYPES.REALM_ADMIN).delete({
+        documentId: assignment.documentId
+      });
+    }
+    await strapi.documents(CONTENT_TYPES.REALM_CONFIG).delete({
+      documentId
+    });
+    return { success: true };
+  },
+  /**
+   * Tests connection to a saved realm configuration.
+   *
+   * @param {string} documentId - Strapi document ID
+   * @returns {Promise<{success: boolean, message?: string, realmDisplayName?: string}>} Test result
+   *
+   * @example
+   * const result = await realmService.testConnection(documentId);
+   * if (result.success) {
+   *   console.log(`Connected to ${result.realmDisplayName}`);
+   * } else {
+   *   console.error(result.message);
+   * }
+   */
+  async testConnection(documentId) {
+    const realmBasic = await this.findOne(documentId);
+    if (!realmBasic.enabled) {
+      return { success: false, message: ERROR_MESSAGES.REALM_DISABLED };
+    }
+    const realm = await this.findOneWithSecret(documentId);
+    return this.keycloakClient.testConnection(realm);
+  },
+  /**
+   * Tests connection with raw configuration data (before saving).
+   * Useful for validating credentials during realm creation/editing.
+   *
+   * @param {RealmConfigData} config - Raw realm configuration
+   * @returns {Promise<{success: boolean, message?: string, realmDisplayName?: string}>} Test result
+   *
+   * @example
+   * const result = await realmService.testConnectionRaw({
+   *   serverUrl: 'https://keycloak.example.com',
+   *   realmName: 'my-realm',
+   *   clientId: 'strapi-admin',
+   *   clientSecret: 'secret'
+   * });
+   */
+  async testConnectionRaw(config2) {
+    return this.keycloakClient.testConnection(config2);
+  }
+});
+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) {
+    const realmBasic = await this.realmService.findOne(realmId);
+    if (!realmBasic.enabled) {
+      throw createSanitizedError("Realm disabled", ERROR_MESSAGES.REALM_DISABLED);
+    }
+    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
+      );
+    }
+    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);
+    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
+    });
+    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");
+    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");
+    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: []
+    };
+    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;
+    while (hasMore) {
+      const users = await this.keycloakClient.getUsers(realm, {
+        first,
+        max,
+        briefRepresentation: false
+      });
+      allUsers.push(...users);
+      first += max;
+      hasMore = users.length === max;
+    }
+    return allUsers;
+  }
+});
+const services = {
+  "keycloak-client": keycloakClientService,
+  "audit-log": auditLogService,
+  permission: permissionService,
+  realm: realmService,
+  user: userService
+};
+const isAuthenticated = (policyContext) => {
+  return Boolean(policyContext.state.user);
+};
+const canAccessRealm = async (policyContext, config2, { strapi }) => {
+  const { realmId, id } = policyContext.params;
+  const user = policyContext.state.user;
+  const targetRealmId = realmId || id;
+  if (!user || !targetRealmId) {
+    return false;
+  }
+  const permissionService2 = strapi.plugin(PLUGIN_ID).service(SERVICES.PERMISSION);
+  if (permissionService2.isSuperAdmin(user)) {
+    return true;
+  }
+  const permission = config2?.permission || "canRead";
+  return permissionService2.canAccessRealm(user, targetRealmId, permission);
+};
+const policies = {
+  "is-authenticated": isAuthenticated,
+  "can-access-realm": canAccessRealm
+};
+const admin = [
+  // ==================== REALM MANAGEMENT ====================
+  // Get all realms (filtered by user access)
+  {
+    method: "GET",
+    path: "/realms",
+    handler: "realm.find",
+    config: { policies: [] }
+  },
+  // Test connection with raw config (before saving)
+  {
+    method: "POST",
+    path: "/realms/test-connection",
+    handler: "realm.testConnectionRaw",
+    config: { policies: [] }
+  },
+  // Get a single realm
+  {
+    method: "GET",
+    path: "/realms/:id",
+    handler: "realm.findOne",
+    config: { policies: [] }
+  },
+  // Create a new realm
+  {
+    method: "POST",
+    path: "/realms",
+    handler: "realm.create",
+    config: { policies: [] }
+  },
+  // Update a realm
+  {
+    method: "PUT",
+    path: "/realms/:id",
+    handler: "realm.update",
+    config: { policies: [] }
+  },
+  // Delete a realm
+  {
+    method: "DELETE",
+    path: "/realms/:id",
+    handler: "realm.delete",
+    config: { policies: [] }
+  },
+  // Test realm connection
+  {
+    method: "POST",
+    path: "/realms/:id/test",
+    handler: "realm.testConnection",
+    config: { policies: [] }
+  },
+  // ==================== REALM ADMIN ASSIGNMENTS ====================
+  // Get admins for a realm
+  {
+    method: "GET",
+    path: "/realms/:id/admins",
+    handler: "realm.getAdmins",
+    config: { policies: [] }
+  },
+  // Add admin to a realm
+  {
+    method: "POST",
+    path: "/realms/:id/admins",
+    handler: "realm.addAdmin",
+    config: { policies: [] }
+  },
+  // Update admin permissions
+  {
+    method: "PUT",
+    path: "/realms/:id/admins/:adminId",
+    handler: "realm.updateAdmin",
+    config: { policies: [] }
+  },
+  // Remove admin from realm
+  {
+    method: "DELETE",
+    path: "/realms/:id/admins/:adminId",
+    handler: "realm.removeAdmin",
+    config: { policies: [] }
+  },
+  // ==================== KEYCLOAK USERS ====================
+  // List users in a realm
+  {
+    method: "GET",
+    path: "/realms/:realmId/users",
+    handler: "user.find",
+    config: { policies: [] }
+  },
+  // Export users
+  {
+    method: "GET",
+    path: "/realms/:realmId/users/export",
+    handler: "user.exportUsers",
+    config: { policies: [] }
+  },
+  // Bulk import users
+  {
+    method: "POST",
+    path: "/realms/:realmId/users/import",
+    handler: "user.bulkImport",
+    config: { policies: [] }
+  },
+  // Get a single user
+  {
+    method: "GET",
+    path: "/realms/:realmId/users/:id",
+    handler: "user.findOne",
+    config: { policies: [] }
+  },
+  // Create a user
+  {
+    method: "POST",
+    path: "/realms/:realmId/users",
+    handler: "user.create",
+    config: { policies: [] }
+  },
+  // Update a user
+  {
+    method: "PUT",
+    path: "/realms/:realmId/users/:id",
+    handler: "user.update",
+    config: { policies: [] }
+  },
+  // Delete a user
+  {
+    method: "DELETE",
+    path: "/realms/:realmId/users/:id",
+    handler: "user.delete",
+    config: { policies: [] }
+  },
+  // ==================== USER ACTIONS ====================
+  // Reset password
+  {
+    method: "POST",
+    path: "/realms/:realmId/users/:id/reset-password",
+    handler: "user.resetPassword",
+    config: { policies: [] }
+  },
+  // Enable user
+  {
+    method: "POST",
+    path: "/realms/:realmId/users/:id/enable",
+    handler: "user.enable",
+    config: { policies: [] }
+  },
+  // Disable user
+  {
+    method: "POST",
+    path: "/realms/:realmId/users/:id/disable",
+    handler: "user.disable",
+    config: { policies: [] }
+  },
+  // Send verification email
+  {
+    method: "POST",
+    path: "/realms/:realmId/users/:id/send-verify-email",
+    handler: "user.sendVerifyEmail",
+    config: { policies: [] }
+  },
+  // Send password reset email
+  {
+    method: "POST",
+    path: "/realms/:realmId/users/:id/send-reset-password-email",
+    handler: "user.sendResetPasswordEmail",
+    config: { policies: [] }
+  },
+  // ==================== ROLES ====================
+  // Get realm roles
+  {
+    method: "GET",
+    path: "/realms/:realmId/roles",
+    handler: "user.getRoles",
+    config: { policies: [] }
+  },
+  // Get user's roles
+  {
+    method: "GET",
+    path: "/realms/:realmId/users/:id/roles",
+    handler: "user.getUserRoles",
+    config: { policies: [] }
+  },
+  // Assign roles to user
+  {
+    method: "POST",
+    path: "/realms/:realmId/users/:id/roles",
+    handler: "user.assignRoles",
+    config: { policies: [] }
+  },
+  // Remove roles from user
+  {
+    method: "DELETE",
+    path: "/realms/:realmId/users/:id/roles",
+    handler: "user.removeRoles",
+    config: { policies: [] }
+  },
+  // ==================== AUDIT LOGS ====================
+  // Get all audit logs
+  {
+    method: "GET",
+    path: "/audit-logs",
+    handler: "audit.find",
+    config: { policies: [] }
+  },
+  // Get audit logs by realm
+  {
+    method: "GET",
+    path: "/audit-logs/realm/:realmId",
+    handler: "audit.findByRealm",
+    config: { policies: [] }
+  },
+  // Get audit logs by Keycloak user
+  {
+    method: "GET",
+    path: "/audit-logs/user/:keycloakUserId",
+    handler: "audit.findByUser",
+    config: { policies: [] }
+  }
+];
+const routes = {
+  admin: {
+    type: "admin",
+    routes: admin
+  }
+};
+const index = {
+  bootstrap,
+  register,
+  destroy,
+  config,
+  contentTypes,
+  controllers,
+  services,
+  policies,
+  routes
+};
+module.exports = index;