Keycloak SSO

Über

Dieses Plugin integriert Keycloak Single Sign-On in Payload CMS 3. Es registriert eine `keycloak`-Auth-Strategie, die Access Tokens offline gegen JWKS und den Issuer verifiziert, `/userinfo` abruft (gecacht pro Token) und einen Permissions-Claim an `req.user` anhängt. Die lokale Auth-Strategie von Payload wird deaktiviert, sodass es keine lokalen Nutzer oder Passwörter gibt. Nutzer werden beim ersten Login anhand ihres Keycloak-`sub` angelegt. Die Felder `email`, `name` und `keycloakSub` werden der Auth-Collection bei Bedarf hinzugefügt. Eine Race Condition beim gleichzeitigen ersten Login (Unique-Index auf `keycloakSub`) wird als Lookup wiederholt, sodass parallele Erstzugriffe nicht fehlschlagen. Der Admin-Login nutzt den Authorization Code Flow mit PKCE (S256) gegen einen öffentlichen Keycloak-Client. Die Standardansicht `/admin/login` leitet über eine `beforeLogin`-Serverkomponente direkt zu Keycloak weiter. Der Callback unter `/api/auth/callback` setzt die Session-Cookies und kehrt zu `/admin` zurück. Ein abgelaufenes Access Token im Cookie wird per Refresh-Token-Cookie still erneuert, sodass die Inactivity-Timer von Payload der Keycloak-SSO-Session folgen. Der Endpoint `/api/users/me` gibt die `exp` des Refresh Tokens zurück, und `/api/users/refresh-token` sowie `/api/users/logout` sind angebunden. Beim Logout werden die Cookies gelöscht und an den Keycloak-End-Session-Endpoint mit `id_token_hint` übergeben. Permissions werden als verschachtelte Booleans aus einem Userinfo-Claim gelesen (Standard: `permissions`), etwa `{ posts: { edit: true } }`. Die Helfer `authenticated`, `can('posts.edit')`, `withKeycloakAccess`, `withKeycloakGlobalAccess`, `withAuth` und `permissionsOf` ergänzen diese Regeln auf den bestehenden Access der jeweiligen Collection, ohne ihn zu ersetzen. Konfiguration erfordert `url`, `realm`, `clientId` und `serverURL`. Weitere Optionen sind `basePath`, `usersSlug`, `scope`, `allowedOrigins`, `permissionsClaim`, `userInfoTtl`, `internalHosts`, `messages` und `enabled`. Die einzige Runtime-Abhängigkeit ist `jose`. Grenzen: `aud` wird nicht validiert, der Zugriff wird stattdessen über Permissions abgesichert. Der Userinfo-Cache und das Refresh-Coalescing liegen im Prozessspeicher, was für eine einzelne Replica geeignet ist. Keycloaks Option "Revoke Refresh Token" muss deaktiviert sein, da Admin-Seiten serverseitig gerendert werden ohne `canSetHeaders` und rotierte Cookies nicht zurückschreiben können. Das Access Token ist ein Realm-Credential von Keycloak. Das Plugin erzwingt daher `auth.removeTokenFromResponses` und hält das Token im httpOnly-Cookie, nie im JSON-Body von `me` oder `refresh-token`.

Paketinformationen

Paketname

payload-keycloak

Neueste Version

1.0.1

Entpackte Größe

118 kB

Lizenz

MIT

Wöchentliche Downloads

11

Zuletzt veröffentlicht

16. Sep. 2026