Strapi plugin logo for Strapi Keycloak Passport

Strapi Keycloak Passport

Seamlessly integrate Keycloak authentication with Strapi Admin Panel.

thumbnail for Strapi Keycloak Passport

🔑 Strapi Keycloak Passport Plugin

🚀 Seamlessly integrate Keycloak authentication with Strapi Admin Panel.
💼 Enterprise-grade security, role-based access control (RBAC), and streamlined authentication.

✨ Features

🔐 Single Sign-On (SSO) – Replace Strapi's default admin login with Keycloak authentication.
🛡️ Role Mapping – Dynamically map Keycloak roles to Strapi admin roles.
⚡ Auto-Assign Default Role – Ensure a default role (STRAPI_ADMIN → Super Admin) exists at first-time activation.
🔍 Strapi RBAC Integration – Leverage Strapi's native Roles & Permissions to enforce admin access.
💾 Persistent Admin Session – No redundant authentication; login once, persist across requests.
📜 Full Logging & Debugging – Logs every authentication & authorization event.


📦 Installation

yarn add strapi-keycloak-passport

or

npm install strapi-keycloak-passport

⚙️ Configuration

🔹 config/plugins.js

Add the following entry inside your config/plugins.js file:

1module.exports = ({ env }) => ({
2  'strapi-keycloak-passport': {
3    enabled: env('KEYCLOAK_PASSPORT_ACTIVE', true),
4    config: {
5      KEYCLOAK_AUTH_URL: env('KEYCLOAK_PASSPORT_AUTH_URL', 'https://keycloak.example.com/auth'),
6      KEYCLOAK_REALM: env('KEYCLOAK_PASSPORT_REALM', 'master'),
7      KEYCLOAK_CLIENT_ID: env('KEYCLOAK_PASSPORT_CLIENT_ID', 'strapi-admin'),
8      KEYCLOAK_CLIENT_SECRET: env('KEYCLOAK_PASSPORT_CLIENT_SECRET', 'your-secret'),
9      KEYCLOAK_TOKEN_URL: env('KEYCLOAK_PASSPORT_TOKEN_URL', '/token'),
10      KEYCLOAK_USERINFO_URL: env('KEYCLOAK_PASSPORT_USERINFO_URL', '/userinfo'),
11      roleConfigs: {
12        defaultRoleId: env('KEYCLOAK_PASSPORT_DEFAULT_ROLE_ID', 5),
13        excludedRoles: env('KEYCLOAK_PASSPORT_EXZIL_ROLES', [
14          'uma_authorization',
15          'default-roles-centralisedcms',
16          'offline_access',
17          'VIEWER',
18        ]),
19      },
20    },
21  },
22});

This configuration:

  • Enables or disables the plugin via KEYCLOAK_PASSPORT_ACTIVE.
  • Connects to Keycloak using client credentials (KEYCLOAK_CLIENT_ID, KEYCLOAK_CLIENT_SECRET).
  • Defines RBAC mappings, excluding irrelevant Keycloak roles from syncing.
  • Auto-assigns a default role (defaultRoleId) if no mapping exists.

🛠 Setup in Keycloak

1️⃣ Create a Client

  • Go to Keycloak Admin PanelClients
  • Create New Client:
    • Client ID: strapi-admin
    • Access Type: Confidential
    • Root URL: https://your-strapi-instance.com/admin
  • Save the client, then go to the Credentials tab and copy:

    • Client Secret
    • Client ID

2️⃣ Configure Admin Roles

  • Go to RolesCreate Role
    • Role: STRAPI_ADMIN (This will map to Strapi Super Admin by default)
  • Assign this role to Keycloak users who should have Strapi Super Admin access.

🔐 Role-Based Access Control (RBAC)

Strapi Keycloak Passport Plugin respects Strapi's native RBAC system.
It maps Keycloak roles to Strapi admin roles.

🛠 Managing Role Mappings

1️⃣ Go to: Admin Panel → Keycloak Plugin
2️⃣ Map Keycloak roles to Strapi admin roles.
3️⃣ Save the mapping.

🔄 Example Mapping:

Keycloak RoleStrapi Role
STRAPI_ADMINSuper Admin (1)
EDITOREditor (2)
VIEWERViewer (3)

📌 How Role Mapping Works

✅ If a Keycloak user logs in with STRAPI_ADMIN, they get Super Admin rights in Strapi.
✅ If no role mapping exists, they get assigned the default role (KEYCLOAK_PASSPORT_DEFAULT_ROLE_ID).


🔄 Authentication Flow

1sequenceDiagram
2  participant User
3  participant Strapi
4  participant Keycloak
5  User->>Strapi: Request login (email + password)
6  Strapi->>Keycloak: Authenticate via OAuth2
7  Keycloak->>Strapi: Return Access Token
8  Strapi->>Keycloak: Fetch User Info
9  Strapi->>Strapi: Find/Create Admin User
10  Strapi->>User: Return JWT Token

Admin logs in once → session persists, no re-authentication needed on every request.


📜 API Endpoints

MethodEndpointDescriptionAuth Required
POST/admin/loginAuthenticate admin via Keycloak❌ No
GET/keycloak-rolesFetch available Keycloak roles✅ Yes
GET/get-keycloak-role-mappingsGet saved role mappings✅ Yes
POST/save-keycloak-role-mappingsSave new role mappings✅ Yes

🚀 Next-Level Security

FeatureStatus
✅ OAuth2 Authentication✔ Enabled
✅ Session-Based Persistence✔ Secure
✅ Role-Based Access Control (RBAC)✔ Strapi Admin Integration
✅ Middleware Protection✔ Only Authorized Users Access APIs

🎯 Final Command to Rule Them All

yarn develop

🔥 Your Strapi is now fully Keycloak-powered! 🔥

Install now

npm install strapi-keycloak-passport

STATS

1 GitHub star65 weekly downloads

Last updated

17 days ago

Strapi Version

5.11.3 and above

Author

github profile image for LPIX-11
LPIX-11

Useful links

Create your own plugin

Check out the available plugin resources that will help you to develop your plugin or provider and get it listed on the marketplace.