strapi-plugin-keycloak-realm-users 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sonatel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,485 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/strapi/strapi/main/packages/core/admin/admin/src/assets/images/logo-strapi-2022.svg" width="200" alt="Strapi Logo" />
+  <span style="font-size: 48px; margin: 0 20px;">+</span>
+  <img src="https://www.keycloak.org/resources/images/logo.svg" width="200" alt="Keycloak Logo" />
+</p>
+
+<h1 align="center">Strapi Plugin: Keycloak Realm Users</h1>
+
+<p align="center">
+  <strong>Seamlessly manage Keycloak users across multiple realms directly from your Strapi admin panel</strong>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#configuration">Configuration</a> •
+  <a href="#usage">Usage</a> •
+  <a href="#api-reference">API</a> •
+  <a href="#permissions">Permissions</a> •
+  <a href="#contributing">Contributing</a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/strapi-plugin-keycloak-realm-users?style=flat-square&color=4945ff" alt="npm version" />
+  <img src="https://img.shields.io/npm/l/strapi-plugin-keycloak-realm-users?style=flat-square" alt="license" />
+  <img src="https://img.shields.io/badge/strapi-v5-blue?style=flat-square" alt="Strapi v5" />
+  <img src="https://img.shields.io/badge/keycloak-17%2B-orange?style=flat-square" alt="Keycloak 17+" />
+</p>
+
+---
+
+## Why This Plugin?
+
+Managing users across multiple Keycloak realms typically requires:
+- Switching between different Keycloak admin consoles
+- Granting full Keycloak admin access to team members
+- No centralized audit trail of user management actions
+
+**This plugin solves all of that** by bringing Keycloak user management into Strapi with fine-grained permissions, multi-realm support, and comprehensive audit logging.
+
+---
+
+## Features
+
+<table>
+<tr>
+<td width="50%">
+
+### 🏰 Multi-Realm Management
+Connect and manage users across unlimited Keycloak realms from a single interface. Each realm is configured independently with its own credentials.
+
+### 🔐 Fine-Grained Permissions
+Assign Strapi admins to specific realms with granular permissions:
+- **Read** - View users
+- **Create** - Add new users
+- **Update** - Modify user details, enable/disable accounts
+- **Delete** - Remove users
+- **Reset Password** - Change passwords (separate from Update for compliance)
+- **Manage Roles** - Assign/remove Keycloak roles
+
+</td>
+<td width="50%">
+
+### 📋 Comprehensive Audit Log
+Every action is logged with:
+- Who performed the action
+- What was changed
+- When it happened
+- Which realm was affected
+
+### 🚀 Full User Lifecycle
+- Create, update, delete users
+- Enable/disable accounts
+- Reset passwords (temporary or permanent)
+- Send verification emails
+- Send password reset emails
+- Bulk import from JSON/CSV
+- Export users
+
+</td>
+</tr>
+</table>
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      Strapi Admin Panel                          │
+├─────────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
+│  │   Realms    │  │    Users    │  │  Audit Log  │              │
+│  │   Config    │  │  Management │  │   Viewer    │              │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
+│         │                │                │                      │
+│         └────────────────┼────────────────┘                      │
+│                          │                                       │
+│  ┌───────────────────────▼───────────────────────┐              │
+│  │         Plugin Permission Layer               │              │
+│  │    (Realm-based access control)               │              │
+│  └───────────────────────┬───────────────────────┘              │
+└──────────────────────────┼──────────────────────────────────────┘
+                           │
+           ┌───────────────┼───────────────┐
+           │               │               │
+           ▼               ▼               ▼
+    ┌────────────┐  ┌────────────┐  ┌────────────┐
+    │  Keycloak  │  │  Keycloak  │  │  Keycloak  │
+    │  Realm A   │  │  Realm B   │  │  Realm C   │
+    └────────────┘  └────────────┘  └────────────┘
+```
+
+---
+
+## Installation
+
+```bash
+# Using npm
+npm install strapi-plugin-keycloak-realm-users
+
+# Using yarn
+yarn add strapi-plugin-keycloak-realm-users
+```
+
+---
+
+## Configuration
+
+### 1. Enable the Plugin
+
+```javascript
+// config/plugins.js
+module.exports = {
+  'strapi-plugin-keycloak-realm-users': {
+    enabled: true,
+  },
+};
+```
+
+### 2. Configure Keycloak Client
+
+For each Keycloak realm you want to manage, you'll need a **service account client** with the following configuration:
+
+<details>
+<summary><strong>Keycloak Client Setup (Click to expand)</strong></summary>
+
+1. **Create a new client** in your Keycloak realm:
+   - Client ID: `strapi-admin` (or your preferred name)
+   - Client Protocol: `openid-connect`
+
+2. **Configure client settings**:
+   | Setting | Value |
+   |---------|-------|
+   | Client authentication | ON |
+   | Service accounts roles | Enabled |
+   | Valid redirect URIs | (not required for service accounts) |
+
+3. **Assign Service Account Roles**:
+   - Go to the client's **Service Account Roles** tab
+   - Click **Assign role**
+   - Filter by **realm-management** client
+   - Assign the following roles:
+
+   | Role | Required For |
+   |------|--------------|
+   | `view-users` | Listing and viewing users |
+   | `manage-users` | Creating, updating, deleting users |
+   | `view-realm` | Testing connection |
+   | `query-users` | Searching users |
+
+   > **Tip**: For full admin access, you can assign `realm-admin` instead.
+
+4. **Get the client secret**:
+   - Go to the **Credentials** tab
+   - Copy the **Client secret**
+
+</details>
+
+---
+
+## Usage
+
+### Adding a Realm
+
+1. Navigate to **Settings** → **Keycloak Realm Users**
+2. Click **Create Realm**
+3. Fill in the connection details:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| Name | Unique identifier (lowercase, hyphens) | `production-users` |
+| Display Name | Human-readable name | `Production Users` |
+| Server URL | Keycloak base URL | `https://keycloak.example.com` |
+| Realm Name | The Keycloak realm name | `my-realm` |
+| Client ID | Service account client ID | `strapi-admin` |
+| Client Secret | Client credentials secret | `xxxxx-xxxxx-xxxxx` |
+| Color | UI accent color | `#4945ff` |
+
+4. Click **Test Connection** to verify
+5. Click **Save**
+
+### Managing Users
+
+Once a realm is configured, you can:
+
+- **View Users**: Click "Manage Users" on any realm card
+- **Search**: Use the search bar to filter by username, email, or name
+- **Create**: Click "Create User" and fill in the details
+- **Edit**: Click the edit icon to modify user details
+- **Actions**:
+  - 🔑 Reset password
+  - ✅ Enable/disable account
+  - 📧 Send verification email
+  - 🗑️ Delete user
+
+### Assigning Realm Admins
+
+Super admins can assign other Strapi users to manage specific realms:
+
+1. Open a realm's settings
+2. Go to the **Admins** tab
+3. Click **Add Admin**
+4. Select a Strapi user
+5. Configure their permissions:
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│  Admin: john@example.com                                      │
+├───────────────────────────────────────────────────────────────┤
+│  ☑ Can Read           ☑ Can Create        ☐ Can Delete       │
+│  ☑ Can Update         ☐ Can Reset Password                   │
+│  ☐ Can Manage Roles                                          │
+└───────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## API Reference
+
+The plugin exposes a REST API for programmatic access.
+
+### Realms
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/keycloak-realm-users/realms` | List all accessible realms |
+| `GET` | `/api/keycloak-realm-users/realms/:id` | Get realm details |
+| `POST` | `/api/keycloak-realm-users/realms` | Create realm (super admin) |
+| `PUT` | `/api/keycloak-realm-users/realms/:id` | Update realm (super admin) |
+| `DELETE` | `/api/keycloak-realm-users/realms/:id` | Delete realm (super admin) |
+| `POST` | `/api/keycloak-realm-users/realms/:id/test` | Test realm connection |
+
+### Users
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/keycloak-realm-users/realms/:id/users` | List users (paginated) |
+| `GET` | `/api/keycloak-realm-users/realms/:id/users/:userId` | Get user details |
+| `POST` | `/api/keycloak-realm-users/realms/:id/users` | Create user |
+| `PUT` | `/api/keycloak-realm-users/realms/:id/users/:userId` | Update user |
+| `DELETE` | `/api/keycloak-realm-users/realms/:id/users/:userId` | Delete user |
+
+### User Actions
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/.../users/:userId/reset-password` | Reset user password |
+| `POST` | `/api/.../users/:userId/enable` | Enable user |
+| `POST` | `/api/.../users/:userId/disable` | Disable user |
+| `POST` | `/api/.../users/:userId/send-verify-email` | Send verification email |
+| `POST` | `/api/.../users/:userId/send-reset-password-email` | Send password reset email |
+
+### Roles
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/.../realms/:id/roles` | List realm roles |
+| `GET` | `/api/.../users/:userId/roles` | Get user's roles |
+| `POST` | `/api/.../users/:userId/roles` | Assign roles |
+| `DELETE` | `/api/.../users/:userId/roles` | Remove roles |
+
+### Bulk Operations
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/.../realms/:id/users/import` | Bulk import users |
+| `GET` | `/api/.../realms/:id/users/export` | Export all users |
+
+### Audit Log
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/keycloak-realm-users/audit` | Query audit logs |
+
+---
+
+## Permissions
+
+### Permission Hierarchy
+
+```
+Super Admin (Strapi)
+    │
+    ├── Can manage all realms
+    ├── Can create/edit/delete realm configurations
+    └── Can assign realm admins
+         │
+         └── Realm Admin (Assigned per realm)
+              │
+              ├── canRead          → View users
+              ├── canCreate        → Create users
+              ├── canUpdate        → Update user details, enable/disable
+              ├── canDelete        → Delete users
+              ├── canResetPassword → Reset passwords, send password reset emails
+              └── canManageRoles   → Assign/remove Keycloak roles
+```
+
+### RBAC Integration
+
+The plugin integrates with Strapi's Role-Based Access Control system. You can configure permissions under **Settings** → **Roles** → **[Role Name]** → **Keycloak Realm Users**.
+
+---
+
+## Data Model
+
+### Realm Configuration
+
+```typescript
+interface RealmConfig {
+  name: string;           // Unique slug identifier
+  displayName: string;    // Human-readable name
+  serverUrl: string;      // Keycloak server URL
+  realmName: string;      // Keycloak realm name
+  clientId: string;       // Service account client ID
+  clientSecret: string;   // Client secret (stored securely)
+  enabled: boolean;       // Whether realm is active
+  color: string;          // UI accent color
+}
+```
+
+### Audit Log Entry
+
+```typescript
+interface AuditLog {
+  action: 'CREATE_USER' | 'UPDATE_USER' | 'DELETE_USER' |
+          'RESET_PASSWORD' | 'ENABLE_USER' | 'DISABLE_USER' |
+          'ASSIGN_ROLE' | 'REMOVE_ROLE' | 'BULK_IMPORT' | ...;
+  realmName: string;
+  realmDisplayName: string;
+  keycloakUserId: string;
+  keycloakUsername: string;
+  performedBy: number;      // Strapi admin user ID
+  performedByEmail: string;
+  details: object;          // Action-specific metadata
+  createdAt: Date;
+}
+```
+
+---
+
+## Security Considerations
+
+| Aspect | Implementation |
+|--------|----------------|
+| **Client Secrets** | Stored with `private: true` attribute, never exposed in API responses |
+| **Token Caching** | Access tokens cached in memory with automatic refresh before expiry |
+| **Permission Checks** | Every API call validates user permissions before execution |
+| **Audit Trail** | All user management actions logged with performer identity |
+| **Input Validation** | Server-side validation on all inputs |
+| **Error Sanitization** | Internal errors sanitized before sending to client |
+
+---
+
+## Troubleshooting
+
+<details>
+<summary><strong>403 Forbidden when testing connection</strong></summary>
+
+This usually means the Keycloak client doesn't have the required roles.
+
+**Solution**: Go to your Keycloak client → Service Account Roles → Assign roles from `realm-management`:
+- `view-realm`
+- `view-users`
+- `manage-users`
+- `query-users`
+
+</details>
+
+<details>
+<summary><strong>Invalid client secret error</strong></summary>
+
+The client secret may have changed or been entered incorrectly.
+
+**Solution**:
+1. Go to Keycloak → Your Client → Credentials tab
+2. Regenerate or copy the current secret
+3. Update the realm configuration in Strapi
+
+</details>
+
+<details>
+<summary><strong>Connection works but users fail to load</strong></summary>
+
+Test connection only verifies basic realm access. User operations require additional permissions.
+
+**Solution**: Ensure your client has `view-users` and `query-users` roles from `realm-management`.
+
+</details>
+
+---
+
+## Compatibility
+
+| Strapi Version | Plugin Version | Keycloak Version |
+|----------------|----------------|------------------|
+| 5.x | 1.x | 17+ (recommended: 22+) |
+
+> **Note**: Keycloak versions below 17 use a different URL structure (`/auth/...`). This plugin is designed for Keycloak 17+ which removed the `/auth` prefix.
+
+---
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/strapi-plugin-keycloak-realm-users
+
+# Install dependencies
+npm install
+```
+
+### Testing
+
+The plugin includes a comprehensive test suite with ~95% code coverage on services and utilities.
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage report
+npm run test:coverage
+```
+
+**Coverage thresholds:**
+- Branches: 75%
+- Functions: 95%
+- Lines: 90%
+- Statements: 90%
+
+### Code Standards
+
+- **Pure ES6+** - Modern JavaScript throughout
+- **JSDoc Documentation** - All public functions, hooks, and types are fully documented
+- **Error Handling** - Sanitized errors prevent internal details from leaking to clients
+- **Centralized Constants** - No magic values; all constants defined in dedicated modules
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting a PR.
+
+**Before submitting:**
+1. Ensure all tests pass: `npm test`
+2. Maintain or improve code coverage: `npm run test:coverage`
+3. Add JSDoc documentation for any new public APIs
+4. Follow the existing code style and patterns
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  <sub>Built with ❤️ for the Strapi Community</sub>
+</p>