Strapi Keycloak Admin Auth

Keycloak authentication plugin for Strapi v5 admin panel with role mapping.

Features

• Replace POST /admin/login with Keycloak password grant login.
• Support Keycloak v17+ by default (KEYCLOAK_LEGACY_MODE=false).
• Optional legacy mode for older Keycloak (/auth prefix).
• Map Keycloak realm roles to Strapi admin roles.
• Auto-create/update Strapi admin users at login.

Installation

npm install @gpb/strapi-keycloak-admin-auth

Strapi Configuration

Add to config/plugins.ts:

import type { Core } from "@strapi/strapi";

const config = ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Plugin => ({
  "keycloak-admin-auth": {
    enabled: env.bool("KEYCLOAK_ENABLED", true),
    config: {
      KEYCLOAK_AUTH_URL: env("KEYCLOAK_AUTH_URL", "https://keycloak.example.com"),
      KEYCLOAK_REALM: env("KEYCLOAK_REALM", "master"),
      KEYCLOAK_CLIENT_ID: env("KEYCLOAK_CLIENT_ID", "strapi-admin"),
      KEYCLOAK_CLIENT_SECRET: env("KEYCLOAK_CLIENT_SECRET"),
      KEYCLOAK_LEGACY_MODE: env.bool("KEYCLOAK_LEGACY_MODE", false),
      roleConfigs: {
        defaultRoleId: env.int("KEYCLOAK_DEFAULT_ROLE_ID", 1),
        excludedRoles: ["uma_authorization", "offline_access", "default-roles-master"],
      },
    },
  },
});

export default config;

Required Environment Variables

KEYCLOAK_ENABLED=true
KEYCLOAK_AUTH_URL=https://keycloak.example.com
KEYCLOAK_REALM=master
KEYCLOAK_CLIENT_ID=strapi-admin
KEYCLOAK_CLIENT_SECRET=your-client-secret
KEYCLOAK_LEGACY_MODE=false
KEYCLOAK_DEFAULT_ROLE_ID=1

Keycloak Requirements

• Client must be openid-connect.
• Client must allow password grant (Direct Access Grants) for admin login flow.
• Service account should have realm-management read roles:
  • view-users
  • view-realm

Role Mapping Endpoints

All endpoints are prefixed with /keycloak-admin-auth.

• GET /keycloak-roles
• GET /get-keycloak-role-mappings
• POST /save-keycloak-role-mappings
• GET /test-connection

Save mapping payload example:

{
  "mappings": {
    "STRAPI_SUPER_ADMIN": 1,
    "STRAPI_EDITOR": 2
  }
}

License

MIT