Administration API
Benutzer, Rollen, Organisationseinheiten, Identitätsanbieter und Zugriffsrichtlinien über die mandantenbezogene Management-API verwalten.
Die Administration API ist Teil der authentifizierten Management-API (/api/…). Jede Anfrage ist mandantenbezogen: Der Mandant wird dem Bearer-Token entnommen, nie explizit übergeben, und ein Aufrufer sieht und ändert ausschließlich die Identitäten und Konfiguration des eigenen Mandanten. Siehe Authentifizierung, um zu erfahren, wie ein Token beschafft wird.
Jede Route wird durch die Administrationsberechtigungen gesteuert — Users.*, Roles.*, OrganizationUnits.*, IdentityProviders.* und AccessPolicies.*. Berechtigungen sind hierarchische Blätter in Punktnotation (zum Beispiel AccessPolicies.Create); die Vergabe eines übergeordneten Präfixes gewährt implizit jedes darunterliegende Blatt. Ein Aufrufer ohne die erforderliche Berechtigung erhält 403 Forbidden.
Alle Pfade sind relativ zu Ihrem Cockpit-Host, zum Beispiel https://cockpit.example.com. Klammern wie {id} bezeichnen einen UUID-Pfadparameter.
Benutzer
Benutzer sind die Identitäten, die sich bei einem Mandanten anmelden. Jeder trägt einen vollständigen Authentifizierungsstatus (Passwort, TOTP, Sperrzähler, Freigabestatus) und kann Rollen und Organisationseinheiten zugewiesen werden.
| Methode + Pfad | Zweck | Berechtigung |
|---|---|---|
GET /api/users | Benutzer auflisten | Users.Read |
POST /api/users | Einen Benutzer erstellen | Users.Create |
POST /api/users/{id}/approve | Einen ausstehenden Benutzer freigeben | Users.Approve |
POST /api/users/{id}/lock | Ein Benutzerkonto sperren | Users.Update |
POST /api/users/{id}/unlock | Ein Benutzerkonto entsperren | Users.Update |
POST /api/users/{id}/suspend | Ein Benutzerkonto suspendieren | Users.Update |
POST /api/users/{id}/reset-password | Ein Benutzerpasswort zurücksetzen | Users.Update |
PUT /api/users/{id}/roles | Einem Benutzer Rollen zuweisen | Users.Update |
Rollen und Berechtigungen
Die Autorisierung ist rollenbasiert. Eine Rolle ist ein benanntes Bündel von Berechtigungen; das Token, das ein Benutzer erhält, trägt die aus seinen Rollen aufgelöste, flache Berechtigungsmenge. Rollen können auf eine Organisationseinheit begrenzt werden, sodass eine Vergabe nur innerhalb dieses Zweigs gilt.
| Methode + Pfad | Zweck | Berechtigung |
|---|---|---|
GET /api/roles | Rollen auflisten | Roles.Read |
POST /api/roles | Eine Rolle erstellen | Roles.Create |
PUT /api/roles/{id} | Eine Rolle aktualisieren | Roles.Update |
DELETE /api/roles/{id} | Eine Rolle löschen | Roles.Delete |
PUT /api/roles/{id}/permissions | Die Berechtigungsmenge einer Rolle festlegen | Roles.Update |
GET /api/roles/permissions | Den hierarchischen Berechtigungskatalog auflisten | Roles.Read |
Organisationseinheiten
Organisationseinheiten (OUs) fügen innerhalb eines Mandanten eine zweite Abgrenzungsebene hinzu. Sie bilden einen Baum mit einem materialisierten Pfadcode (etwa 00001.00003.00007); Ressourcen wie Apps können auf eine OU begrenzt werden, und Rollen können auf OU-Ebene zugewiesen werden.
| Methode + Pfad | Zweck | Berechtigung |
|---|---|---|
GET /api/org-units | Organisationseinheiten auflisten | OrganizationUnits.Read |
POST /api/org-units | Eine Organisationseinheit erstellen | OrganizationUnits.Create |
GET /api/org-units/selectable | Für die Zuweisung auswählbare OUs auflisten | OrganizationUnits.Read |
/api/org-units/{id}/roles | OU-begrenzte Rollen zuweisen (delegierte Administration) | OrganizationUnits.Update |
Identitätsanbieter
Externe Identitätsanbieter ermöglichen Benutzern die Anmeldung mit Unternehmensanmeldedaten (Azure AD / Entra ID, Okta, Keycloak). Anbieter werden mit Client-Anmeldedaten, Authority-/Metadaten-URLs, Scopes und Claim-Zuordnungen konfiguriert und können Benutzer automatisch in Standardrollen bereitstellen.
| Methode + Pfad | Zweck | Berechtigung |
|---|---|---|
GET /api/identity-providers | Konfigurierte Identitätsanbieter auflisten | IdentityProviders.Read |
POST /api/identity-providers | Einen Identitätsanbieter erstellen | IdentityProviders.Create |
POST /api/identity-providers/discover | Anbieter-Endpunkte aus einer Metadaten-/Authority-URL ermitteln | IdentityProviders.Read |
POST /api/identity-providers/{id}/test-connection | Die Anbieterverbindung und Anmeldedaten testen | IdentityProviders.Update |
POST /api/identity-providers/{id}/toggle | Den Anbieter aktivieren oder deaktivieren | IdentityProviders.Update |
Single Sign-on wird zusätzlich durch die Identitätsanbieter-Feature-Flags der Edition des Mandanten gesteuert; ein Anbieter muss für die Edition aktiviert sein, bevor er verwendet werden kann.
Zugriffsrichtlinien
Über RBAC hinaus umfasst die Administration die Casbin-ABAC-Zugriffsrichtlinien-Engine, die Laufzeit-Kryptooperationen nach Benutzer, IP, Standort, Zeit und Gruppe steuert. Eine Richtlinie ist mandantenbezogen und wirkt erst, sobald sie über ihre access_policy_id an eine Ressource (einen DKE-Dienst, eine generische App oder einen AWS-XKS-Endpunkt) gebunden ist. Das vollständige Modell ist auf der Seite Zugriffsrichtlinien dokumentiert.
| Methode + Pfad | Zweck | Berechtigung |
|---|---|---|
GET /api/access-policies | Richtlinien auflisten | AccessPolicies.Read |
POST /api/access-policies | Eine Richtlinie erstellen | AccessPolicies.Create |
GET /api/access-policies/{id} | Eine Richtlinie abrufen | AccessPolicies.Read |
PUT /api/access-policies/{id} | Eine Richtlinie aktualisieren | AccessPolicies.Update |
DELETE /api/access-policies/{id} | Eine Richtlinie löschen | AccessPolicies.Delete |
POST /api/access-policies/validate | Eine Richtliniendefinition vor dem Speichern validieren | AccessPolicies.Read |
GET /api/access-policies/capabilities | Fähigkeitsmatrix pro App-Typ (welche der fünf Dimensionen jeder App-Typ berücksichtigt) | AccessPolicies.Read |
GET /api/access-policies/available-groups | Für Gruppenregeln verfügbare Gruppen | AccessPolicies.Read |
GET /api/access-policies/audit · GET /api/access-policies/{id}/audit | Audit-Trail der Durchsetzung | AccessPolicies.Read |
Impersonation
Impersonation ermöglicht es einem autorisierten Administrator, für Support und Fehlerbehebung als anderer Benutzer zu agieren. Der Start einer Sitzung stellt ein begrenztes Token im Kontext des Zielbenutzers aus; das Beenden setzt den Aufrufer auf seine eigene Identität zurück. Jede Impersonation wird in den Aktivitätsprotokollen erfasst.
| Methode + Pfad | Zweck | Berechtigung |
|---|---|---|
POST /api/impersonation/start | Impersonation eines Zielbenutzers starten | Users.Impersonate |
POST /api/impersonation/stop | Impersonation beenden und die Aufrufer-Identität wiederherstellen | Users.Impersonate |
Impersonation gewährt dem Aufrufer für die Dauer der Sitzung die effektiven Berechtigungen des Zielbenutzers. Beschränken Sie die Impersonation-Berechtigung auf vertrauenswürdige Administratoren und prüfen Sie den Audit-Trail regelmäßig.