Zum Inhalt

User Management, RBAC & Keycloak

Überblick

Die Polycrate API ist seit 0.15.0 ein vollwertiges User-basiertes System mit integrierter Keycloak-Anbindung und einem generischen, rollenbasierten Berechtigungssystem (RBAC). Frühere Versionen nutzten noch das Contact-Modell als primäre Identität – seit 0.15.0 ist User die einzige authentifizierte Identität, Contact existiert ausschließlich als CRM-Objekt.

Baustein Zweck
User Authentifizierte Identität, Login, OIDC-Subject
Contact CRM-Datensatz (Ansprechpartner, Rechnungskontakt) – kein Login
Organization Membership Ordnet einen User einer Organisation mit einer Rolle zu
Roles & Permissions Definieren, was ein User in der UI und API darf
Keycloak Zentraler IdP für Login, OIDC-Flow und SSO

Rollen & Berechtigungen (RBAC)

Polycrate unterscheidet zwei grundlegende Rollen auf System-Ebene:

Admin (is_superuser=True)

  • Vollzugriff auf alle Objekte aller Organisationen
  • Sieht administrative Bereiche (Domain Registrar, System Config, Rollout Dashboard, Feature Flags, Default Data Import)
  • Darf User anderer Organisationen verwalten
  • Darf Workspaces und Organisationen erstellen und löschen

Kunden-User (is_superuser=False)

  • Zugriff ausschließlich auf Objekte der Organisationen, in denen er Mitglied ist
  • Keine administrativen Bereiche
  • Filterung und Sichtbarkeit sind automatisch org-scoped (ManagedObject.get_queryset_for_user())
  • Rechte pro Modell (Create/Edit/Delete/Archive) werden konsistent in UI und API geprüft

Zentralisierte Permission-Logik

Buttons "Create", "Edit", "Delete", "Archive" in der UI werden aus denselben Permission-Checks abgeleitet wie die API-Endpoints. Ein User, der z. B. keine delete_s3bucket-Permission hat, sieht den Button nicht und bekommt bei direktem API-Aufruf 403 Forbidden.

admin_only statt staff_only

Felder und Views, die ausschließlich Administratoren zur Verfügung stehen, werden konsequent mit admin_only=True (statt dem alten staff_only) markiert. Beispiele: System Config, Default Data Import, Domain Registrar.

Organization Membership

Ein User kann Mitglied in beliebig vielen Organisationen sein. Jede Mitgliedschaft hat eine Rolle, die den Zugriff auf Objekte dieser Organisation steuert. Admins sehen alle Organisationen; Kunden-User sehen nur Organisationen, in denen sie Mitglied sind.

Verwaltung: Administration → Users → User öffnen → Memberships

Keycloak-Integration

Login-Flow

  1. User öffnet Polycrate
  2. Weiterleitung auf Keycloak (Realm der Organisation)
  3. Login über Keycloak (Passwort, MFA, Social-IdP – abhängig von Realm-Konfiguration)
  4. Keycloak leitet zurück mit OIDC-Token
  5. Polycrate legt bei Erstlogin automatisch ein SocialAccount an und verknüpft User ↔ Keycloak-Subject

Automatisches Keycloak-User-Provisioning

Wird in Polycrate ein neuer User angelegt (über Admin-UI, API oder automatisch als Teil der Contact→User-Migration), wird automatisch ein entsprechender Keycloak-Account erzeugt:

  • Username = Polycrate-Email
  • Attribute werden synchronisiert (first_name, last_name, email)
  • Initialpasswort: entweder "Forgot-Password-Flow" oder explizit gesetzt, abhängig von System Config
  • Der Keycloak-Subject wird direkt als SocialAccount(provider='keycloak') am Polycrate-User persistiert

Voraussetzung

System Config → Integration → Keycloak muss mit Endpoint, Admin-Credentials, Realm und Client-ID konfiguriert sein, damit das Provisioning funktioniert. Fehlt die Konfiguration, wird der User nur in Polycrate angelegt – der Login schlägt dann fehl, bis Keycloak manuell nachgepflegt wird.

Keycloak-Felder pro Organisation

In den Organisations-Einstellungen lassen sich Realm-Parameter pro Organisation überschreiben (z. B. eigener Keycloak-Realm pro Mandant). Standardmäßig greift die im System Config hinterlegte Default-Konfiguration.

User-Administration

Die Administration → Users Ansicht stellt eine vollwertige User-Verwaltung außerhalb des Django-Admins bereit:

  • Liste aller User (filterbar nach Organisation, Rolle, aktiv/inaktiv)
  • Detail mit Memberships, Login-Historie, zugeordneten Contacts und Keycloak-Link
  • Create / Edit / Archive / Delete – die Rechte für diese Aktionen werden durch das RBAC-System gesteuert
  • API-Endpoints (/api/v1/admin/users/) mit erweitertem Serializer für Admin-Use-Cases

Best Practices

Empfehlung Grund
Genau eine Identity pro Person Vermeidet doppelte Keycloak-Accounts und Audit-Probleme
Service-Accounts separat als Agent-Tokens, nicht als User Saubere Trennung zwischen menschlichen Usern und M2M
Rollen über Memberships, nicht über Admin-Flag Kunden-User sollten nie Superuser sein
Organisations-Zuordnung sauber pflegen Filterung basiert ausschließlich auf aktiven Memberships
Keycloak als alleinige Quelle für Credentials MFA, Password-Policy, Session-Management zentral

Migration 0.14.x → 0.15.0

Wenn Sie von einem älteren Polycrate-Release kommen:

  • Contact war früher die Haupt-Identity – Login lief über Contact-Email. Das wird durch das Release 0.15.0 durch die Migration automatisch zu User umgezogen (Contact bleibt als CRM-Objekt bestehen)
  • Bestehende Keycloak-Accounts werden über Email mit dem neuen User verknüpft; fehlende Keycloak-Accounts werden automatisch angelegt, sofern die Keycloak-Integration konfiguriert ist
  • Details zur Migration: Release 0.15.0

Siehe auch