strapi-plugin-keycloak-realm-users 1.0.0

package/admin/src/hooks/useRealmAdmins.js

@@ -0,0 +1,249 @@
+/**
+ * @fileoverview React hook for managing realm admin assignments.
+ * Provides functionality to assign Strapi users as realm administrators with granular permissions.
+ * @module admin/hooks/useRealmAdmins
+ */
+
+import { useState, useCallback } from 'react';
+import { useFetchClient, useNotification } from '@strapi/strapi/admin';
+import { API_BASE_PATH } from '../constants';
+
+/**
+ * @typedef {Object} RealmPermissions
+ * @property {boolean} canRead - Can view users in the realm
+ * @property {boolean} canCreate - Can create new users
+ * @property {boolean} canUpdate - Can modify users (includes enable/disable)
+ * @property {boolean} canDelete - Can permanently delete users
+ * @property {boolean} canManageRoles - Can assign/remove realm roles
+ * @property {boolean} canResetPassword - Can reset passwords and send password reset emails
+ */
+
+/**
+ * @typedef {Object} RealmAdminAssignment
+ * @property {string} documentId - Assignment document ID
+ * @property {number} strapiUserId - Strapi admin user ID
+ * @property {string} strapiUserEmail - Strapi admin email
+ * @property {RealmPermissions} permissions - Granted permissions
+ */
+
+/**
+ * @typedef {Object} StrapiUser
+ * @property {number} id - User ID
+ * @property {string} email - User email
+ * @property {string} [firstname] - First name
+ * @property {string} [lastname] - Last name
+ */
+
+/**
+ * @typedef {Object} UseRealmAdminsReturn
+ * @property {RealmAdminAssignment[]} admins - Array of admin assignments
+ * @property {StrapiUser[]} strapiUsers - Array of available Strapi users
+ * @property {boolean} isLoading - Loading state
+ * @property {Function} fetchAdmins - Refetch admin assignments
+ * @property {Function} fetchStrapiUsers - Fetch available Strapi users
+ * @property {Function} addAdmin - Add new admin assignment
+ * @property {Function} updateAdmin - Update admin permissions
+ * @property {Function} removeAdmin - Remove admin assignment
+ */
+
+/**
+ * Hook for managing realm admin assignments.
+ * Allows assigning Strapi users as administrators of a specific realm
+ * with granular permission control.
+ *
+ * @param {string} realmId - Realm document ID
+ * @returns {UseRealmAdminsReturn} Admin management functions and state
+ *
+ * @example
+ * function RealmAdminManager({ realmId }) {
+ *   const {
+ *     admins,
+ *     strapiUsers,
+ *     fetchStrapiUsers,
+ *     addAdmin,
+ *     updateAdmin,
+ *     removeAdmin,
+ *   } = useRealmAdmins(realmId);
+ *
+ *   useEffect(() => {
+ *     fetchStrapiUsers();
+ *   }, []);
+ *
+ *   const handleAddAdmin = async (userId, email) => {
+ *     await addAdmin(userId, email, {
+ *       canRead: true,
+ *       canCreate: true,
+ *       canUpdate: false,
+ *       canDelete: false,
+ *       canManageRoles: false,
+ *       canResetPassword: false,
+ *     });
+ *   };
+ *
+ *   return (
+ *     <AdminList
+ *       admins={admins}
+ *       availableUsers={strapiUsers}
+ *       onAdd={handleAddAdmin}
+ *       onRemove={removeAdmin}
+ *     />
+ *   );
+ * }
+ */
+export const useRealmAdmins = (realmId) => {
+  const client = useFetchClient();
+  const { toggleNotification } = useNotification();
+
+  const [admins, setAdmins] = useState([]);
+  const [strapiUsers, setStrapiUsers] = useState([]);
+  const [isLoading, setIsLoading] = useState(false);
+
+  /**
+   * Fetches all admin assignments for the realm.
+   *
+   * @returns {Promise<void>}
+   */
+  const fetchAdmins = useCallback(async () => {
+    if (!realmId) return;
+
+    setIsLoading(true);
+    try {
+      const { data } = await client.get(`${API_BASE_PATH}/realms/${realmId}/admins`);
+      setAdmins(data.data || []);
+    } catch (err) {
+      toggleNotification({
+        type: 'danger',
+        message: err.response?.data?.error?.message || 'Failed to fetch realm admins',
+      });
+    } finally {
+      setIsLoading(false);
+    }
+  }, [realmId, client, toggleNotification]);
+
+  /**
+   * Fetches all Strapi admin users available for assignment.
+   *
+   * @returns {Promise<void>}
+   */
+  const fetchStrapiUsers = useCallback(async () => {
+    try {
+      const { data } = await client.get('/admin/users');
+      setStrapiUsers(data.data?.results || data.data || []);
+    } catch (err) {
+      toggleNotification({
+        type: 'danger',
+        message: 'Failed to fetch Strapi users',
+      });
+    }
+  }, [client, toggleNotification]);
+
+  /**
+   * Adds a Strapi user as a realm admin with specified permissions.
+   * Automatically refreshes the admin list on success.
+   *
+   * @param {number} strapiUserId - Strapi user ID
+   * @param {string} strapiUserEmail - Strapi user email
+   * @param {RealmPermissions} permissions - Permissions to grant
+   * @returns {Promise<RealmAdminAssignment>} Created assignment
+   * @throws {Error} If creation fails
+   */
+  const addAdmin = useCallback(
+    async (strapiUserId, strapiUserEmail, permissions) => {
+      try {
+        const { data } = await client.post(`${API_BASE_PATH}/realms/${realmId}/admins`, {
+          data: {
+            strapiUserId,
+            strapiUserEmail,
+            permissions,
+          },
+        });
+        toggleNotification({
+          type: 'success',
+          message: 'Admin added successfully',
+        });
+        await fetchAdmins();
+        return data.data;
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to add admin',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification, fetchAdmins]
+  );
+
+  /**
+   * Updates an existing admin assignment's permissions.
+   * Automatically refreshes the admin list on success.
+   *
+   * @param {string} adminId - Admin assignment document ID
+   * @param {RealmPermissions} permissions - New permissions
+   * @returns {Promise<RealmAdminAssignment>} Updated assignment
+   * @throws {Error} If update fails
+   */
+  const updateAdmin = useCallback(
+    async (adminId, permissions) => {
+      try {
+        const { data } = await client.put(`${API_BASE_PATH}/realms/${realmId}/admins/${adminId}`, {
+          data: { permissions },
+        });
+        toggleNotification({
+          type: 'success',
+          message: 'Admin permissions updated',
+        });
+        await fetchAdmins();
+        return data.data;
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to update admin',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification, fetchAdmins]
+  );
+
+  /**
+   * Removes a realm admin assignment.
+   * Automatically refreshes the admin list on success.
+   *
+   * @param {string} adminId - Admin assignment document ID
+   * @returns {Promise<void>}
+   * @throws {Error} If removal fails
+   */
+  const removeAdmin = useCallback(
+    async (adminId) => {
+      try {
+        await client.del(`${API_BASE_PATH}/realms/${realmId}/admins/${adminId}`);
+        toggleNotification({
+          type: 'success',
+          message: 'Admin removed successfully',
+        });
+        await fetchAdmins();
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to remove admin',
+        });
+        throw err;
+      }
+    },
+    [realmId, client, toggleNotification, fetchAdmins]
+  );
+
+  return {
+    admins,
+    strapiUsers,
+    isLoading,
+    fetchAdmins,
+    fetchStrapiUsers,
+    addAdmin,
+    updateAdmin,
+    removeAdmin,
+  };
+};
+
+export default useRealmAdmins;

package/admin/src/hooks/useRealms.js

@@ -0,0 +1,269 @@
+/**
+ * @fileoverview React hook for managing Keycloak realm configurations.
+ * Provides CRUD operations, connection testing, and state management for realms.
+ * @module admin/hooks/useRealms
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import { useFetchClient, useNotification } from '@strapi/strapi/admin';
+import { API_BASE_PATH } from '../constants';
+
+/**
+ * @typedef {Object} RealmConfig
+ * @property {string} documentId - Strapi document ID
+ * @property {string} name - Unique slug identifier
+ * @property {string} displayName - Human-readable name
+ * @property {string} serverUrl - Keycloak server URL
+ * @property {string} realmName - Keycloak realm name
+ * @property {string} clientId - OAuth client ID
+ * @property {boolean} enabled - Active status
+ * @property {string} color - UI accent color (hex)
+ */
+
+/**
+ * @typedef {Object} ConnectionTestResult
+ * @property {boolean} success - Whether connection succeeded
+ * @property {string} [message] - Error message if failed
+ * @property {string} [realmDisplayName] - Realm name from Keycloak if successful
+ */
+
+/**
+ * @typedef {Object} UseRealmsReturn
+ * @property {RealmConfig[]} realms - Array of realm configurations
+ * @property {boolean} isLoading - Loading state for initial fetch
+ * @property {Function} fetchAll - Refetch all realms
+ * @property {Function} fetchOne - Fetch single realm by ID
+ * @property {Function} create - Create new realm
+ * @property {Function} update - Update existing realm
+ * @property {Function} remove - Delete realm
+ * @property {Function} testConnection - Test saved realm connection
+ * @property {Function} testConnectionRaw - Test connection with raw config
+ */
+
+/**
+ * Hook for managing Keycloak realm configurations.
+ * Provides complete CRUD operations and connection testing functionality.
+ *
+ * @returns {UseRealmsReturn} Realm management functions and state
+ *
+ * @example
+ * function RealmsPage() {
+ *   const { realms, isLoading, create, update, remove, testConnection } = useRealms();
+ *
+ *   if (isLoading) return <Loader />;
+ *
+ *   return (
+ *     <ul>
+ *       {realms.map(realm => (
+ *         <li key={realm.documentId}>{realm.displayName}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ */
+export const useRealms = () => {
+  const client = useFetchClient();
+  const { toggleNotification } = useNotification();
+
+  const [realms, setRealms] = useState([]);
+  const [isLoading, setIsLoading] = useState(true);
+
+  /**
+   * Fetches all realm configurations from the API.
+   * Updates the realms state and handles errors with notifications.
+   *
+   * @returns {Promise<void>}
+   */
+  const fetchAll = useCallback(async () => {
+    setIsLoading(true);
+    try {
+      const { data } = await client.get(`${API_BASE_PATH}/realms`);
+      setRealms(data.data || []);
+    } catch (err) {
+      toggleNotification({
+        type: 'danger',
+        message: err.response?.data?.error?.message || 'Failed to fetch realms',
+      });
+    } finally {
+      setIsLoading(false);
+    }
+  }, [client, toggleNotification]);
+
+  /**
+   * Fetches a single realm by its document ID.
+   *
+   * @param {string} id - Realm document ID
+   * @returns {Promise<RealmConfig>} The realm configuration
+   * @throws {Error} If fetch fails
+   */
+  const fetchOne = useCallback(
+    async (id) => {
+      try {
+        const { data } = await client.get(`${API_BASE_PATH}/realms/${id}`);
+        return data.data;
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to fetch realm',
+        });
+        throw err;
+      }
+    },
+    [client, toggleNotification]
+  );
+
+  /**
+   * Creates a new realm configuration.
+   * Automatically refreshes the realms list on success.
+   *
+   * @param {Object} realmData - Realm configuration data
+   * @param {string} realmData.name - Unique slug identifier
+   * @param {string} realmData.displayName - Human-readable name
+   * @param {string} realmData.serverUrl - Keycloak server URL
+   * @param {string} realmData.realmName - Keycloak realm name
+   * @param {string} realmData.clientId - OAuth client ID
+   * @param {string} [realmData.clientSecret] - OAuth client secret
+   * @param {boolean} [realmData.enabled=true] - Active status
+   * @param {string} [realmData.color] - UI accent color
+   * @returns {Promise<RealmConfig>} The created realm
+   * @throws {Error} If creation fails
+   */
+  const create = useCallback(
+    async (realmData) => {
+      try {
+        const { data } = await client.post(`${API_BASE_PATH}/realms`, { data: realmData });
+        toggleNotification({
+          type: 'success',
+          message: 'Realm created successfully',
+        });
+        await fetchAll();
+        return data.data;
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to create realm',
+        });
+        throw err;
+      }
+    },
+    [client, toggleNotification, fetchAll]
+  );
+
+  /**
+   * Updates an existing realm configuration.
+   * Automatically refreshes the realms list on success.
+   *
+   * @param {string} id - Realm document ID
+   * @param {Partial<RealmConfig>} realmData - Fields to update
+   * @returns {Promise<RealmConfig>} The updated realm
+   * @throws {Error} If update fails
+   */
+  const update = useCallback(
+    async (id, realmData) => {
+      try {
+        const { data } = await client.put(`${API_BASE_PATH}/realms/${id}`, { data: realmData });
+        toggleNotification({
+          type: 'success',
+          message: 'Realm updated successfully',
+        });
+        await fetchAll();
+        return data.data;
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to update realm',
+        });
+        throw err;
+      }
+    },
+    [client, toggleNotification, fetchAll]
+  );
+
+  /**
+   * Deletes a realm configuration and all associated admin assignments.
+   * Automatically refreshes the realms list on success.
+   *
+   * @param {string} id - Realm document ID
+   * @returns {Promise<void>}
+   * @throws {Error} If deletion fails
+   */
+  const remove = useCallback(
+    async (id) => {
+      try {
+        await client.del(`${API_BASE_PATH}/realms/${id}`);
+        toggleNotification({
+          type: 'success',
+          message: 'Realm deleted successfully',
+        });
+        await fetchAll();
+      } catch (err) {
+        toggleNotification({
+          type: 'danger',
+          message: err.response?.data?.error?.message || 'Failed to delete realm',
+        });
+        throw err;
+      }
+    },
+    [client, toggleNotification, fetchAll]
+  );
+
+  /**
+   * Tests the Keycloak connection for a saved realm.
+   *
+   * @param {string} id - Realm document ID
+   * @returns {Promise<ConnectionTestResult>} Test result with success status
+   */
+  const testConnection = useCallback(
+    async (id) => {
+      try {
+        const { data } = await client.post(`${API_BASE_PATH}/realms/${id}/test`);
+        return data.data;
+      } catch (err) {
+        return { success: false, message: err.response?.data?.error?.message || 'Connection failed' };
+      }
+    },
+    [client]
+  );
+
+  /**
+   * Tests a Keycloak connection with raw configuration data.
+   * Useful for validating credentials before saving a realm.
+   *
+   * @param {Object} config - Raw connection configuration
+   * @param {string} config.serverUrl - Keycloak server URL
+   * @param {string} config.realmName - Keycloak realm name
+   * @param {string} config.clientId - OAuth client ID
+   * @param {string} config.clientSecret - OAuth client secret
+   * @returns {Promise<ConnectionTestResult>} Test result with success status
+   */
+  const testConnectionRaw = useCallback(
+    async (config) => {
+      try {
+        const { data } = await client.post(`${API_BASE_PATH}/realms/test-connection`, { data: config });
+        return data.data;
+      } catch (err) {
+        return { success: false, message: err.response?.data?.error?.message || 'Connection failed' };
+      }
+    },
+    [client]
+  );
+
+  // Fetch realms on mount
+  useEffect(() => {
+    fetchAll();
+  }, [fetchAll]);
+
+  return {
+    realms,
+    isLoading,
+    fetchAll,
+    fetchOne,
+    create,
+    update,
+    remove,
+    testConnection,
+    testConnectionRaw,
+  };
+};
+
+export default useRealms;

package/admin/src/index.js

@@ -0,0 +1,46 @@
+import { PLUGIN_ID } from './pluginId';
+import Initializer from './components/Initializer';
+import { getTrad } from './constants';
+
+export default {
+  register(app) {
+    app.registerPlugin({
+      id: PLUGIN_ID,
+      initializer: Initializer,
+      isReady: false,
+      name: PLUGIN_ID,
+    });
+  },
+
+  bootstrap(app) {
+    // Add settings link
+    app.addSettingsLink('global', {
+      id: PLUGIN_ID,
+      to: PLUGIN_ID,
+      intlLabel: {
+        id: getTrad('settings.title'),
+        defaultMessage: 'Keycloak Users',
+      },
+      Component: () => import('./pages/App'),
+      permissions: [],
+    });
+  },
+
+  async registerTrads({ locales }) {
+    const importedTrads = await Promise.all(
+      locales.map((locale) => {
+        return import(`./translations/${locale}.json`)
+          .then(({ default: data }) => ({
+            data,
+            locale,
+          }))
+          .catch(() => ({
+            data: {},
+            locale,
+          }));
+      })
+    );
+
+    return importedTrads;
+  },
+};

package/admin/src/pages/App.jsx

@@ -0,0 +1,21 @@
+import { Routes, Route } from 'react-router-dom';
+
+import RealmsPage from './RealmsPage';
+import UsersPage from './UsersPage';
+import AuditPage from './AuditPage';
+
+const App = () => {
+  return (
+    <Routes>
+      <Route index element={<RealmsPage.List />} />
+      <Route path="realms/create" element={<RealmsPage.Edit />} />
+      <Route path="realms/:id" element={<RealmsPage.Edit />} />
+      <Route path="realms/:realmId/users" element={<UsersPage.List />} />
+      <Route path="realms/:realmId/users/create" element={<UsersPage.Edit />} />
+      <Route path="realms/:realmId/users/:userId" element={<UsersPage.Edit />} />
+      <Route path="audit" element={<AuditPage />} />
+    </Routes>
+  );
+};
+
+export default App;