strapi-plugin-keycloak-realm-users 1.0.0

package/server/src/routes/admin.js

@@ -0,0 +1,253 @@
+export default [
+  // ==================== 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: [] },
+  },
+];

package/server/src/routes/index.js

@@ -0,0 +1,8 @@
+import admin from './admin.js';
+
+export default {
+  admin: {
+    type: 'admin',
+    routes: admin,
+  },
+};

package/server/src/services/audit-log.js

@@ -0,0 +1,196 @@
+/**
+ * @fileoverview Audit logging service for tracking user management actions.
+ * Records all significant operations for compliance and debugging purposes.
+ *
+ * @module services/audit-log
+ */
+
+import {
+  PLUGIN_ID,
+  CONTENT_TYPES,
+  PAGINATION,
+  UNKNOWN_USER_EMAIL,
+} from '../constants.js';
+
+/**
+ * @typedef {Object} AuditLogEntry
+ * @property {string} documentId - Entry document ID
+ * @property {string} realmName - Realm slug identifier
+ * @property {string} realmDisplayName - Realm display name
+ * @property {string} action - Action type (from AUDIT_ACTIONS constant)
+ * @property {string|null} keycloakUserId - Target Keycloak user ID
+ * @property {string|null} keycloakUsername - Target Keycloak username
+ * @property {Object|null} details - Action-specific metadata
+ * @property {number|null} performedById - Strapi admin user ID
+ * @property {string} performedByEmail - Strapi admin email
+ * @property {Date} createdAt - Entry creation timestamp
+ */
+
+/**
+ * @typedef {Object} AuditLogParams
+ * @property {string} realmName - Realm slug identifier
+ * @property {string} [realmDisplayName] - Realm display name (defaults to realmName)
+ * @property {string} action - Action type from AUDIT_ACTIONS
+ * @property {string} [keycloakUserId] - Target Keycloak user ID
+ * @property {string} [keycloakUsername] - Target Keycloak username
+ * @property {Object} [details] - Action-specific metadata
+ * @property {Object} [user] - Strapi user who performed the action
+ * @property {number} [user.id] - User ID
+ * @property {string} [user.email] - User email
+ */
+
+/**
+ * @typedef {Object} AuditLogQueryParams
+ * @property {string} [realmName] - Filter by realm
+ * @property {string} [action] - Filter by action type
+ * @property {string} [keycloakUserId] - Filter by Keycloak user
+ * @property {number} [limit=50] - Maximum entries to return
+ * @property {number} [offset=0] - Starting offset for pagination
+ */
+
+/**
+ * @typedef {Object} AuditLogQueryResult
+ * @property {AuditLogEntry[]} entries - Log entries
+ * @property {number} total - Total matching entries
+ */
+
+/**
+ * Creates the audit log service.
+ *
+ * @param {Object} params - Service parameters
+ * @param {Object} params.strapi - Strapi instance
+ * @returns {Object} Audit log service methods
+ */
+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) {
+      // Log error but don't throw - audit logging should not break main operations
+      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
+  } = {}) {
+    // Build filters object
+    const filters = {};
+
+    if (realmName) {
+      filters.realmName = realmName;
+    }
+    if (action) {
+      filters.action = action;
+    }
+    if (keycloakUserId) {
+      filters.keycloakUserId = keycloakUserId;
+    }
+
+    // Execute queries in parallel
+    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 });
+  },
+});
+
+export default auditLogService;

package/server/src/services/index.js

@@ -0,0 +1,13 @@
+import keycloakClient from './keycloak-client.js';
+import auditLog from './audit-log.js';
+import permission from './permission.js';
+import realm from './realm.js';
+import user from './user.js';
+
+export default {
+  'keycloak-client': keycloakClient,
+  'audit-log': auditLog,
+  permission,
+  realm,
+  user,
+};