strapi-plugin-keycloak-realm-users 1.0.0 → 1.0.2

package/README.md

@@ -1,81 +1,111 @@
 <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" />
+  <img src="https://raw.githubusercontent.com/strapi/strapi/main/packages/core/admin/admin/src/assets/images/logo-strapi-2022.svg" width="160" alt="Strapi Logo" />
+  <img src="https://user-images.githubusercontent.com/4129325/166460470-2e9d9f5c-3b8c-4fee-9754-1b1c90119e60.png" width="60" alt="handshake" />
+  <img src="https://www.keycloak.org/resources/images/logo.svg" width="160" alt="Keycloak Logo" />
 </p>
 
-<h1 align="center">Strapi Plugin: Keycloak Realm Users</h1>
+<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>
+  <em>Manage Keycloak users across <strong>all your realms</strong> — without ever leaving Strapi.</em>
 </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>
+  <a href="https://www.npmjs.com/package/strapi-plugin-keycloak-realm-users"><img src="https://img.shields.io/npm/v/strapi-plugin-keycloak-realm-users?style=for-the-badge&logo=npm&logoColor=white&color=CB3837" alt="npm version" /></a>
+  <img src="https://img.shields.io/badge/Strapi-v5-4945FF?style=for-the-badge&logo=strapi&logoColor=white" alt="Strapi v5" />
+  <img src="https://img.shields.io/badge/Keycloak-17%2B-4D8AB5?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyTDIgN3Y1YzAgNS41NSAzLjg0IDEwLjc0IDEwIDEyIDYuMTYtMS4yNiAxMC02LjQ1IDEwLTEyVjdsLTEwLTV6Ii8+PC9zdmc+" alt="Keycloak 17+" />
+  <img src="https://img.shields.io/npm/l/strapi-plugin-keycloak-realm-users?style=for-the-badge&color=22C55E" alt="MIT License" />
 </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+" />
+  <a href="#-quick-start">Quick Start</a> &nbsp;&bull;&nbsp;
+  <a href="#-what-can-it-do">Features</a> &nbsp;&bull;&nbsp;
+  <a href="#%EF%B8%8F-configuration">Configuration</a> &nbsp;&bull;&nbsp;
+  <a href="#-api-reference">API</a> &nbsp;&bull;&nbsp;
+  <a href="#-troubleshooting">Troubleshooting</a>
 </p>
 
 ---
 
-## Why This Plugin?
+## 💡 The Problem
 
-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
+You have **multiple Keycloak realms** — dev, staging, production, client tenants — and managing users means:
 
-**This plugin solves all of that** by bringing Keycloak user management into Strapi with fine-grained permissions, multi-realm support, and comprehensive audit logging.
+- 🔀 Juggling between different Keycloak admin consoles
+- 🔓 Giving **full Keycloak admin access** to people who just need to reset a password
+- 🕵️ No centralized log of who did what, where, and when
+
+## ✅ The Solution
+
+Install this plugin. Now your **Strapi admin panel** is the single pane of glass for Keycloak user management — with **per-realm permissions**, **audit logging**, and **zero Keycloak console access required** for your team.
 
 ---
 
-## Features
+## 🚀 Quick Start
+
+**1. Install**
+
+```bash
+npm install strapi-plugin-keycloak-realm-users
+# or
+yarn add strapi-plugin-keycloak-realm-users
+```
+
+**2. Enable**
+
+```javascript
+// config/plugins.js
+module.exports = {
+  'strapi-plugin-keycloak-realm-users': {
+    enabled: true,
+  },
+};
+```
+
+**3. Connect a realm** — go to **Settings → Keycloak Realm Users → Create Realm**, fill in your Keycloak URL, client ID & secret, hit **Test Connection**, and you're live. 🎉
+
+---
+
+## 🎯 What Can It Do?
 
 <table>
 <tr>
-<td width="50%">
+<td width="50%" valign="top">
 
 ### 🏰 Multi-Realm Management
-Connect and manage users across unlimited Keycloak realms from a single interface. Each realm is configured independently with its own credentials.
+Connect **unlimited Keycloak realms** from a single Strapi interface. Each realm gets its own credentials, color tag, and admin team.
+
+### 🔐 Granular Permissions
+Assign Strapi admins to specific realms with fine-grained control:
 
-### 🔐 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
+| Permission | What it unlocks |
+|:---:|---|
+| 👁️ **Read** | View users |
+| ➕ **Create** | Add new users |
+| ✏️ **Update** | Edit details, enable/disable |
+| 🗑️ **Delete** | Remove users |
+| 🔑 **Reset Password** | Change passwords (separate 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 width="50%" valign="top">
+
+### 📋 Full Audit Trail
+Every action is logged:
+- **Who** performed it
+- **What** changed
+- **When** it happened
+- **Which realm** was affected
+
+Never wonder "who deleted that user?" again.
+
+### 🧰 Full User Lifecycle
+- ➕ Create, ✏️ update, 🗑️ delete users
+- ✅ Enable / disable accounts
+- 🔑 Reset passwords (temporary or permanent)
+- 📧 Send verification & password reset emails
+- 📦 Bulk import from JSON/CSV
+- 📤 Export users
 
 </td>
 </tr>
@@ -83,403 +113,276 @@ Every action is logged with:
 
 ---
 
-## Architecture
+## 🏗️ How It Works
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                      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   │
-    └────────────┘  └────────────┘  └────────────┘
+┌──────────────────────────────────────────────────────────┐
+│                  Strapi Admin Panel                       │
+│                                                          │
+│   ┌──────────┐   ┌──────────┐   ┌──────────┐            │
+│   │  Realms   │   │  Users   │   │  Audit   │            │
+│   │  Config   │   │ Manager  │   │   Log    │            │
+│   └────┬─────┘   └────┬─────┘   └────┬─────┘            │
+│        └───────────────┼──────────────┘                   │
+│                        ▼                                  │
+│        ┌───────────────────────────────┐                  │
+│        │   Permission Layer            │                  │
+│        │   (per-realm access control)  │                  │
+│        └───────────────┬───────────────┘                  │
+└────────────────────────┼─────────────────────────────────┘
+                         │
+          ┌──────────────┼──────────────┐
+          ▼              ▼              ▼
+   ┌────────────┐ ┌────────────┐ ┌────────────┐
+   │  Keycloak  │ │  Keycloak  │ │  Keycloak  │
+   │  Realm A   │ │  Realm B   │ │  Realm C   │
+   └────────────┘ └────────────┘ └────────────┘
 ```
 
+Your Strapi admins **never touch Keycloak directly**. They get exactly the permissions they need, and every action is logged.
+
 ---
 
-## Installation
+## ⚙️ Configuration
 
-```bash
-# Using npm
-npm install strapi-plugin-keycloak-realm-users
+### Keycloak Client Setup
 
-# Using yarn
-yarn add strapi-plugin-keycloak-realm-users
-```
+For each realm you want to manage, create a **service account client** in Keycloak:
 
----
+<details>
+<summary>📖 <strong>Step-by-step Keycloak setup</strong> (click to expand)</summary>
 
-## Configuration
+<br />
 
-### 1. Enable the Plugin
+**1. Create a new client** in your Keycloak realm:
+- Client ID: `strapi-admin` (or your preferred name)
+- Client Protocol: `openid-connect`
 
-```javascript
-// config/plugins.js
-module.exports = {
-  'strapi-plugin-keycloak-realm-users': {
-    enabled: true,
-  },
-};
-```
+**2. Configure client settings:**
 
-### 2. Configure Keycloak Client
+| Setting | Value |
+|---------|-------|
+| Client authentication | **ON** |
+| Service accounts roles | **Enabled** |
 
-For each Keycloak realm you want to manage, you'll need a **service account client** with the following configuration:
+**3. Assign service account roles:**
 
-<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**
+Go to **Service Account Roles** → **Assign role** → Filter by **realm-management** → Add:
 
-</details>
+| Role | Why |
+|:---:|---|
+| `view-users` | List & view users |
+| `manage-users` | Create, update, delete users |
+| `view-realm` | Test connection |
+| `query-users` | Search users |
 
----
+> 💡 **Shortcut**: Assign `realm-admin` for full access.
 
-## Usage
+**4. Copy the client secret** from the **Credentials** tab.
 
-### Adding a Realm
+</details>
 
-1. Navigate to **Settings** → **Keycloak Realm Users**
-2. Click **Create Realm**
-3. Fill in the connection details:
+### Adding a Realm in Strapi
 
-| 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` |
+| Field | What it is | Example |
+|-------|-----------|---------|
+| **Name** | Unique slug (lowercase, hyphens) | `production-users` |
+| **Display Name** | Human-readable label | `Production Users` |
+| **Server URL** | Keycloak base URL | `https://keycloak.example.com` |
+| **Realm Name** | Keycloak realm | `my-realm` |
+| **Client ID** | Service account client | `strapi-admin` |
+| **Client Secret** | From credentials tab | `xxxxx-xxxxx-xxxxx` |
+| **Color** | UI accent color | `#4945ff` |
 
-4. Click **Test Connection** to verify
-5. Click **Save**
+Hit **Test Connection** → **Save** → Done! ✅
 
-### Managing Users
+---
 
-Once a realm is configured, you can:
+## 👥 Managing Users
 
-- **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
+Once a realm is connected:
 
-### Assigning Realm Admins
+| Action | How |
+|--------|-----|
+| **Browse users** | Click "Manage Users" on any realm card |
+| **Search** | Filter by username, email, or name |
+| **Create user** | Click "Create User" → fill in details |
+| **Edit user** | Click the edit icon on any row |
+| **Reset password** | 🔑 Set temporary or permanent password |
+| **Toggle account** | ✅ Enable or disable with one click |
+| **Verification email** | 📧 Send from the user actions menu |
+| **Delete user** | 🗑️ With confirmation dialog |
+| **Bulk import** | 📦 Upload JSON or CSV |
+| **Export** | 📤 Download all realm users |
 
-Super admins can assign other Strapi users to manage specific realms:
+### Assigning Realm Admins
 
-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:
+Super admins can delegate realm management to other Strapi users:
 
 ```
-┌───────────────────────────────────────────────────────────────┐
-│  Admin: john@example.com                                      │
-├───────────────────────────────────────────────────────────────┤
-│  ☑ Can Read           ☑ Can Create        ☐ Can Delete       │
-│  ☑ Can Update         ☐ Can Reset Password                   │
-│  ☐ Can Manage Roles                                          │
-└───────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────┐
+│  Admin: john@example.com                                │
+├─────────────────────────────────────────────────────────┤
+│  ☑ Can Read        ☑ Can Create       ☐ Can Delete     │
+│  ☑ Can Update      ☐ Can Reset Password                │
+│  ☐ Can Manage Roles                                    │
+└─────────────────────────────────────────────────────────┘
 ```
 
+Each admin sees **only the realms they're assigned to** with **only the actions they're permitted**.
+
 ---
 
-## API Reference
+## 📡 API Reference
 
-The plugin exposes a REST API for programmatic access.
+All endpoints live under `/api/keycloak-realm-users`.
 
 ### 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 |
+|:------:|----------|-------------|
+| `GET` | `/realms` | List all accessible realms |
+| `GET` | `/realms/:id` | Get realm details |
+| `POST` | `/realms` | Create realm *(super admin)* |
+| `PUT` | `/realms/:id` | Update realm *(super admin)* |
+| `DELETE` | `/realms/:id` | Delete realm *(super admin)* |
+| `POST` | `/realms/:id/test` | Test 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 |
+|:------:|----------|-------------|
+| `GET` | `/realms/:id/users` | List users (paginated) |
+| `GET` | `/realms/:id/users/:userId` | Get user details |
+| `POST` | `/realms/:id/users` | Create user |
+| `PUT` | `/realms/:id/users/:userId` | Update user |
+| `DELETE` | `/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 |
+|:------:|----------|-------------|
+| `POST` | `/.../users/:userId/reset-password` | Reset password |
+| `POST` | `/.../users/:userId/enable` | Enable user |
+| `POST` | `/.../users/:userId/disable` | Disable user |
+| `POST` | `/.../users/:userId/send-verify-email` | Send verification email |
+| `POST` | `/.../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 |
+|:------:|----------|-------------|
+| `GET` | `/.../realms/:id/roles` | List realm roles |
+| `GET` | `/.../users/:userId/roles` | Get user's roles |
+| `POST` | `/.../users/:userId/roles` | Assign roles |
+| `DELETE` | `/.../users/:userId/roles` | Remove roles |
 
-### Bulk Operations
+### Bulk Operations & Audit
 
 | 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 |
+|:------:|----------|-------------|
+| `POST` | `/.../realms/:id/users/import` | Bulk import users |
+| `GET` | `/.../realms/:id/users/export` | Export all users |
+| `GET` | `/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
+## 🛡️ Security
 
-The plugin integrates with Strapi's Role-Based Access Control system. You can configure permissions under **Settings** → **Roles** → **[Role Name]** → **Keycloak Realm Users**.
+| Aspect | How we handle it |
+|--------|-----------------|
+| 🔒 **Client Secrets** | Stored with `private: true` — never exposed in API responses |
+| ⚡ **Token Caching** | Access tokens cached in memory, auto-refreshed before expiry |
+| 🚪 **Permission Checks** | Every API call validated before execution |
+| 📋 **Audit Trail** | All actions logged with performer identity |
+| ✅ **Input Validation** | Server-side validation on all inputs |
+| 🧹 **Error Sanitization** | Internal details never leak to clients |
 
 ---
 
-## 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
+## 🔧 Troubleshooting
 
 <details>
-<summary><strong>403 Forbidden when testing connection</strong></summary>
+<summary>🔴 <strong>403 Forbidden when testing connection</strong></summary>
 
-This usually means the Keycloak client doesn't have the required roles.
+The Keycloak client is missing required roles.
 
-**Solution**: Go to your Keycloak client → Service Account Roles → Assign roles from `realm-management`:
+**Fix**: Keycloak → Your Client → Service Account Roles → Assign 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.
+<summary>🔴 <strong>Invalid client secret</strong></summary>
 
-**Solution**:
-1. Go to Keycloak → Your Client → Credentials tab
-2. Regenerate or copy the current secret
-3. Update the realm configuration in Strapi
+The secret may have changed or was entered incorrectly.
 
+**Fix**: Keycloak → Your Client → Credentials tab → Copy the current secret → Update in Strapi.
 </details>
 
 <details>
-<summary><strong>Connection works but users fail to load</strong></summary>
+<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`.
+Test connection only checks basic realm access. User operations need extra permissions.
 
+**Fix**: Ensure your client has `view-users` and `query-users` roles from `realm-management`.
 </details>
 
 ---
 
-## Compatibility
+## 📦 Compatibility
 
-| Strapi Version | Plugin Version | Keycloak Version |
-|----------------|----------------|------------------|
-| 5.x | 1.x | 17+ (recommended: 22+) |
+| | Version |
+|---|---------|
+| **Strapi** | v5.x |
+| **Keycloak** | 17+ *(recommended: 22+)* |
+| **Node.js** | 18+ |
 
-> **Note**: Keycloak versions below 17 use a different URL structure (`/auth/...`). This plugin is designed for Keycloak 17+ which removed the `/auth` prefix.
+> ⚠️ Keycloak versions below 17 use the legacy `/auth/...` URL prefix, which this plugin does not support.
 
 ---
 
-## Development
-
-### Setup
+## 🧪 Development
 
 ```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
+# Run tests
 npm test
 
-# Run tests in watch mode
+# Watch mode
 npm run test:watch
 
-# Run tests with coverage report
+# 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
+**Coverage thresholds**: Branches 75% · Functions 95% · Lines 90% · Statements 90%
 
 ---
 
-## Contributing
+## 🤝 Contributing
 
-Contributions are welcome! Please read our contributing guidelines before submitting a PR.
+Contributions welcome! 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
+1. ✅ All tests pass: `npm test`
+2. 📊 Coverage maintained: `npm run test:coverage`
+3. 📝 JSDoc added for new public APIs
+4. 🎨 Follows existing code style
 
 ---
 
-## License
+## 📄 License
 
-MIT License - see [LICENSE](LICENSE) for details.
+[MIT](LICENSE) — use it, fork it, ship it.
 
 ---
 
 <p align="center">
-  <sub>Built with ❤️ for the Strapi Community</sub>
+  <sub>Built with ❤️ for the Strapi community</sub>
+  <br />
+  <sub>If this plugin saved you time, give it a ⭐ on GitHub!</sub>
 </p>