Keycloak SSO

Описание

Плагин добавляет.single sign-on через Keycloak в Payload CMS 3. Регистрируется OIDC-стратегия `keycloak`, которая проверяет access-токены Keycloak офлайн через JWKS и issuer, запрашивает `/userinfo` (с кэшированием по токену) и добавляет permissions-клейм в `req.user`. Локальная стратегия Payload отключена: нет локальных пользователей и паролей. При первом входе пользователь создаётся по Keycloak `sub`; поля `email`, `name` и `keycloakSub` добавляются в коллекцию автоматически, если их не было. Если при первом входе возникает гонка на уникальном индексе `keycloakSub`, плагин повторяет запрос как lookup, и параллельные запросы не падают молча. Вход в админку использует Authorization Code flow с PKCE (S256) против публичного клиента Keycloak. Стандартный экран `/admin/login` редиректит в Keycloak через серверный компонент `beforeLogin`. Колбэк `/api/auth/callback` выставляет session cookies и возвращает пользователя в `/admin`. Истёкший access-токен тихо обновляется через refresh-token cookie, поэтому таймеры неактивности Payload следуют за сессией Keycloak SSO. Эндпоинт `/api/users/me` отдаёт `exp` refresh-токена. При выходе плагин очищает cookies и передаёт управление в Keycloak end-session с параметром `id_token_hint`. Permissions читаются из клейма в userinfo (по умолчанию `permissions`) как вложенные булевы значения, например `{ posts: { edit: true } }`. Хелперы `authenticated`, `can('posts.edit')`, `withKeycloakAccess`, `withKeycloakGlobalAccess`, `withAuth` и `permissionsOf` композируют правила поверх существующих access-функций коллекций, а не заменяют их. Обязательные параметры конфигурации: `url`, `realm`, `clientId`, `serverURL`. Дополнительные: `basePath`, `usersSlug`, `scope`, `allowedOrigins`, `permissionsClaim`, `userInfoTtl`, `internalHosts`, `messages`, `getKey`, `enabled`. Единственная runtime-зависимость: `jose`. Peer-зависимости: `payload` ^3.84.1, `@payloadcms/ui` ^3.84.1, `next` ^15||^16, `react` ^19. Ограничения. Плагин не проверяет `aud`, поэтому доступ регулируется через permissions. Кэш userinfo и коалесцирование refresh-токенов хранятся в памяти процесса, что подходит для одного реплики. Опция Keycloak "Revoke Refresh Token" должна быть выключена: страницы админки рендерятся на сервере без `canSetHeaders` и не могут записать ротированные cookies обратно. Access-токен является учётными данными realm Keycloak, поэтому плагин принудительно вызывает `auth.removeTokenFromResponses` и хранит токен в httpOnly cookie, а не в JSON-теле ответа `me` или `refresh-token`. Bearer-запросы не обновляются.

О пакете

Имя пакета

payload-keycloak

Последняя версия

1.0.1

Размер

118 кБ

Лицензия

MIT

Загрузок в неделю

11

Последняя публикация

16 сент. 2026 г.