💡 The Problem

You have multiple Keycloak realms — dev, staging, production, client tenants — and managing users means:

• 🔀 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.

🚀 Quick Start

1. Install

npm install strapi-plugin-keycloak-realm-users
# or
yarn add strapi-plugin-keycloak-realm-users

2. Enable

// 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?

🏰 Multi-Realm Management

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:

| 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 |

📋 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

🏗️ How It Works

┌──────────────────────────────────────────────────────────┐
│                  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.

⚙️ Configuration

Keycloak Client Setup

For each realm you want to manage, create a service account client in Keycloak:

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 |

3. Assign service account roles:

Go to Service Account Roles → Assign role → Filter by realm-management → Add:

| 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.

4. Copy the client secret from the Credentials tab.

Adding a Realm in Strapi

| 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 |

Hit Test Connection → Save → Done! ✅

👥 Managing Users

Once a realm is connected:

| 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 |

Assigning Realm Admins

Super admins can delegate realm management to other Strapi users:

┌─────────────────────────────────────────────────────────┐
│  Admin: [email protected]                                │
├─────────────────────────────────────────────────────────┤
│  ☑ 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

All endpoints live under /api/keycloak-realm-users.

Realms

| Method | Endpoint | Description | |:------:|----------|-------------| | 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 | /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 | /.../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 | /.../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 & Audit

| Method | Endpoint | Description | |:------:|----------|-------------| | POST | /.../realms/:id/users/import | Bulk import users | | GET | /.../realms/:id/users/export | Export all users | | GET | /audit | Query audit logs |

🛡️ Security

| 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 |

🔧 Troubleshooting

The Keycloak client is missing required roles.

Fix: Keycloak → Your Client → Service Account Roles → Assign from realm-management:

• view-realm
• view-users
• manage-users
• query-users

The secret may have changed or was entered incorrectly.

Fix: Keycloak → Your Client → Credentials tab → Copy the current secret → Update in Strapi.

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.

📦 Compatibility

| | Version | |---|---------| | Strapi | v5.x | | Keycloak | 17+ (recommended: 22+) | | Node.js | 18+ |

⚠️ Keycloak versions below 17 use the legacy /auth/... URL prefix, which this plugin does not support.

🧪 Development

# Install dependencies
npm install

# Run tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Coverage thresholds: Branches 75% · Functions 95% · Lines 90% · Statements 90%

🤝 Contributing

Contributions welcome! Before submitting a PR:

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

MIT — use it, fork it, ship it.