strapi-plugin-keycloak-realm-users 1.0.0

package/admin/src/hooks/useAuditLogs.js

@@ -0,0 +1,142 @@
+/**
+ * @fileoverview React hook for fetching and managing audit logs.
+ * Provides filtering by realm, user, and action type.
+ * @module admin/hooks/useAuditLogs
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import { useFetchClient, useNotification } from '@strapi/strapi/admin';
+import { API_BASE_PATH } from '../constants';
+
+/**
+ * @typedef {Object} AuditLogEntry
+ * @property {string} documentId - Log entry document ID
+ * @property {string} realmName - Realm slug identifier
+ * @property {string} realmDisplayName - Realm display name
+ * @property {string} action - Action type (e.g., 'CREATE_USER', 'RESET_PASSWORD')
+ * @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 {string} createdAt - ISO timestamp
+ */
+
+/**
+ * @typedef {Object} UseAuditLogsOptions
+ * @property {string} [realmId] - Filter by realm document ID
+ * @property {string} [keycloakUserId] - Filter by Keycloak user ID
+ */
+
+/**
+ * @typedef {Object} FetchLogsParams
+ * @property {number} [limit=50] - Maximum entries to return
+ * @property {number} [offset=0] - Starting offset for pagination
+ * @property {string} [action] - Filter by action type
+ * @property {string} [realmName] - Filter by realm name
+ */
+
+/**
+ * @typedef {Object} UseAuditLogsReturn
+ * @property {AuditLogEntry[]} logs - Array of audit log entries
+ * @property {boolean} isLoading - Loading state
+ * @property {number} total - Total matching entries
+ * @property {Function} fetchLogs - Fetch logs with optional filters
+ */
+
+/**
+ * Hook for fetching audit logs with optional filtering.
+ * Supports filtering by realm, user, and action type.
+ *
+ * @param {UseAuditLogsOptions} [options={}] - Filter options
+ * @returns {UseAuditLogsReturn} Audit log data and fetch function
+ *
+ * @example
+ * // Fetch all logs
+ * function AuditLogPage() {
+ *   const { logs, isLoading, total, fetchLogs } = useAuditLogs();
+ *
+ *   return (
+ *     <LogTable
+ *       entries={logs}
+ *       total={total}
+ *       onPageChange={(offset) => fetchLogs({ offset })}
+ *     />
+ *   );
+ * }
+ *
+ * @example
+ * // Fetch logs for a specific realm
+ * function RealmAuditLogs({ realmId }) {
+ *   const { logs } = useAuditLogs({ realmId });
+ *   // logs are automatically filtered by realm
+ * }
+ *
+ * @example
+ * // Fetch logs for a specific user
+ * function UserActivityLog({ keycloakUserId }) {
+ *   const { logs } = useAuditLogs({ keycloakUserId });
+ *   // Shows all actions performed on this user
+ * }
+ */
+export const useAuditLogs = (options = {}) => {
+  const { realmId, keycloakUserId } = options;
+  const client = useFetchClient();
+  const { toggleNotification } = useNotification();
+
+  const [logs, setLogs] = useState([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [total, setTotal] = useState(0);
+
+  /**
+   * Fetches audit logs with optional pagination and filters.
+   * URL is determined by the hook options (realmId or keycloakUserId).
+   *
+   * @param {FetchLogsParams} [params={}] - Query parameters
+   * @returns {Promise<void>}
+   */
+  const fetchLogs = useCallback(
+    async ({ limit = 50, offset = 0, action, realmName } = {}) => {
+      setIsLoading(true);
+      try {
+        let url = `${API_BASE_PATH}/audit-logs`;
+        const params = { limit, offset };
+
+        if (realmId) {
+          url = `${API_BASE_PATH}/audit-logs/realm/${realmId}`;
+        } else if (keycloakUserId) {
+          url = `${API_BASE_PATH}/audit-logs/user/${keycloakUserId}`;
+        } else {
+          if (action) params.action = action;
+          if (realmName) params.realmName = realmName;
+        }
+
+        const { data } = await client.get(url, { params });
+        setLogs(data.data || []);
+        setTotal(data.meta?.total || data.data?.length || 0);
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to fetch audit logs',
+        });
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [client, toggleNotification, realmId, keycloakUserId]
+  );
+
+  // Fetch logs on mount and when options change
+  useEffect(() => {
+    fetchLogs();
+  }, [fetchLogs]);
+
+  return {
+    logs,
+    isLoading,
+    total,
+    fetchLogs,
+  };
+};
+
+export default useAuditLogs;

package/admin/src/hooks/useKeycloakRoles.js

@@ -0,0 +1,182 @@
+/**
+ * @fileoverview React hook for managing Keycloak realm roles.
+ * Provides role fetching and user role assignment functionality.
+ * @module admin/hooks/useKeycloakRoles
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import { useFetchClient, useNotification } from '@strapi/strapi/admin';
+import { API_BASE_PATH } from '../constants';
+
+/**
+ * @typedef {Object} KeycloakRole
+ * @property {string} id - Role unique identifier
+ * @property {string} name - Role name
+ * @property {string} [description] - Role description
+ * @property {boolean} [composite] - Whether role contains other roles
+ */
+
+/**
+ * @typedef {Object} UseKeycloakRolesReturn
+ * @property {KeycloakRole[]} roles - Array of available realm roles
+ * @property {boolean} isLoading - Loading state
+ * @property {Function} fetchRoles - Refetch all roles
+ * @property {Function} getUserRoles - Get roles assigned to a user
+ * @property {Function} assignRoles - Assign roles to a user
+ * @property {Function} removeRoles - Remove roles from a user
+ */
+
+/**
+ * Hook for managing Keycloak realm roles for a specific realm.
+ * Provides functionality to fetch roles and manage user role assignments.
+ *
+ * @param {string} realmId - Realm document ID
+ * @returns {UseKeycloakRolesReturn} Role management functions and state
+ *
+ * @example
+ * function UserRolesEditor({ realmId, userId }) {
+ *   const { roles, getUserRoles, assignRoles, removeRoles } = useKeycloakRoles(realmId);
+ *   const [userRoles, setUserRoles] = useState([]);
+ *
+ *   useEffect(() => {
+ *     getUserRoles(userId).then(setUserRoles);
+ *   }, [userId]);
+ *
+ *   return (
+ *     <RoleSelector
+ *       availableRoles={roles}
+ *       assignedRoles={userRoles}
+ *       onAssign={(role) => assignRoles(userId, [role])}
+ *       onRemove={(role) => removeRoles(userId, [role])}
+ *     />
+ *   );
+ * }
+ */
+export const useKeycloakRoles = (realmId) => {
+  const client = useFetchClient();
+  const { toggleNotification } = useNotification();
+
+  const [roles, setRoles] = useState([]);
+  const [isLoading, setIsLoading] = useState(false);
+
+  /**
+   * Fetches all available realm roles from Keycloak.
+   *
+   * @returns {Promise<void>}
+   */
+  const fetchRoles = useCallback(async () => {
+    if (!realmId) return;
+
+    setIsLoading(true);
+    try {
+      const { data } = await client.get(`${API_BASE_PATH}/realms/${realmId}/roles`);
+      setRoles(data.data || []);
+    } catch (err) {
+      toggleNotification({
+        type: 'danger',
+        message: err.response?.data?.error?.message || 'Failed to fetch roles',
+      });
+    } finally {
+      setIsLoading(false);
+    }
+  }, [realmId, client, toggleNotification]);
+
+  /**
+   * Fetches roles currently assigned to a specific user.
+   *
+   * @param {string} userId - Keycloak user ID
+   * @returns {Promise<KeycloakRole[]>} Array of assigned roles
+   * @throws {Error} If fetch fails
+   */
+  const getUserRoles = useCallback(
+    async (userId) => {
+      try {
+        const { data } = await client.get(`${API_BASE_PATH}/realms/${realmId}/users/${userId}/roles`);
+        return data.data || [];
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to fetch user roles',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification]
+  );
+
+  /**
+   * Assigns roles to a user.
+   *
+   * @param {string} userId - Keycloak user ID
+   * @param {KeycloakRole[]} rolesToAssign - Roles to assign (must include id and name)
+   * @returns {Promise<void>}
+   * @throws {Error} If assignment fails
+   */
+  const assignRoles = useCallback(
+    async (userId, rolesToAssign) => {
+      try {
+        await client.post(`${API_BASE_PATH}/realms/${realmId}/users/${userId}/roles`, {
+          data: { roles: rolesToAssign },
+        });
+        toggleNotification({
+          type: 'success',
+          message: 'Roles assigned successfully',
+        });
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to assign roles',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification]
+  );
+
+  /**
+   * Removes roles from a user.
+   *
+   * @param {string} userId - Keycloak user ID
+   * @param {KeycloakRole[]} rolesToRemove - Roles to remove (must include id and name)
+   * @returns {Promise<void>}
+   * @throws {Error} If removal fails
+   */
+  const removeRoles = useCallback(
+    async (userId, rolesToRemove) => {
+      try {
+        await client.del(`${API_BASE_PATH}/realms/${realmId}/users/${userId}/roles`, {
+          data: { roles: rolesToRemove },
+        });
+        toggleNotification({
+          type: 'success',
+          message: 'Roles removed successfully',
+        });
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to remove roles',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification]
+  );
+
+  // Fetch roles when realmId changes
+  useEffect(() => {
+    if (realmId) {
+      fetchRoles();
+    }
+  }, [realmId, fetchRoles]);
+
+  return {
+    roles,
+    isLoading,
+    fetchRoles,
+    getUserRoles,
+    assignRoles,
+    removeRoles,
+  };
+};
+
+export default useKeycloakRoles;