Gruppen und Mitglieder verwalten

Worum es geht

Gruppen verwaltest du über die Verwaltungs-API unter /cias/admin/groups. Die Oberflächen dafür rufen genau diese Aufrufe auf, siehe Die Verwaltungsoberfläche.

Die Aufrufe

Listen kommen immer in Seiten: items, page, size, total, hasMore. Ohne Angabe sind es 50 Zeilen, höchstens 500. Wer mehr verlangt, bekommt 400 statt still weniger Zeilen.

Die Prüfungen

Die 403 sieht genauso aus wie jede andere Ablehnung der Rechteprüfung. Den genauen Grund schreibt CIAS ins Log.

Eine Gruppe anlegen

POST /cias/admin/groups
Authorization: Bearer <Token eines Plattform-Administrators>
{
  "key": "support",
  "name": "Support 1st Level",
  "description": "Alle im telefonischen Support",
  "roles": [
    { "client": null, "key": "user" },
    { "client": "cdms-backend", "key": "customer-read" },
    { "client": "crms-backend", "key": "ticket-edit" }
  ],
  "defaultGroup": false
}

HTTP 200
{
  "key": "support",
  "name": "Support 1st Level",
  "description": "Alle im telefonischen Support",
  "roles": [
    { "client": null, "key": "user", "displayName": "Benutzer",
      "scope": "PLATFORM", "effectiveInEveryTenant": true },
    { "client": "cdms-backend", "key": "customer-read", "displayName": "Kunden lesen",
      "scope": "PLATFORM", "effectiveInEveryTenant": false },
    { "client": "crms-backend", "key": "ticket-edit", "displayName": "Tickets bearbeiten",
      "scope": "TENANT", "effectiveInEveryTenant": false }
  ],
  "memberCount": 0,
  "defaultGroup": false,
  "syncState": "SYNCHRONIZED"
}

Eine frisch angelegte Gruppe hat noch keine Mitglieder. Sie gibt also noch niemandem etwas.

Die sechs Ausprägungen

Rollen ändern heißt: die ganze Liste schicken

Es gibt kein „Rolle hinzufügen“ und kein „Rolle entfernen“. Du schickst beim PUT immer die vollständige Liste. Eine Rolle entfernst du, indem du die Liste ohne sie schickst. Was du weglässt, fällt weg, auch in Keycloak, auch wenn es die letzte Rolle eines Moduls war.

Der Schlüssel lässt sich nicht ändern. Soll eine Gruppe anders heißen, änderst du name.

Mitglieder sind Benutzerdatensätze

userIds sind die IDs der Benutzerdatensätze in CIAS, nicht die Keycloak-sub. Wie du sie findest, steht unter Der Benutzerdatensatz. Die Liste darf nicht leer sein, sonst 400. Du kannst mehrere Personen auf einmal aufnehmen oder entfernen, wie beim Ankreuzen in einer Oberfläche.

Bestehende Keycloak-Gruppen übernehmen

Ein Realm, den es schon vor CIAS gab, enthält oft Gruppen, die jemand in der Keycloak-Konsole angelegt hat. Sie tragen keine Marke cias-managed, also fasst CIAS sie nicht an. Mit dem Import übernimmt CIAS sie.

POST /cias/admin/groups/import

HTTP 200
{
  "found": 4,
  "adopted": 2,
  "alreadyKnown": 1,
  "skipped": [
    { "group": "buchhaltung",
      "reason": "it carries 1 role(s) the CIAS catalogue does not know (erp:invoice-approve) — their module has to declare them first, or the next reconciliation would take them off the group" }
  ]
}

Eine Gruppe wird ganz oder gar nicht übernommen. Warum so streng? Was CIAS führt, schreibt der Abgleich später nach Keycloak zurück. Würde CIAS eine unbekannte Rolle einfach weglassen, nähme der nächste Abgleich sie der Gruppe weg. Würde CIAS ein unbekanntes Mitglied weglassen, flöge die Person aus der Gruppe. Deshalb: erst fehlende Rollen vom Modul anmelden lassen und fehlende Konten übernehmen, dann den Import wiederholen.

Der Import lässt sich gefahrlos wiederholen. Übernommene Gruppen tragen die Marke und tauchen beim nächsten Lauf nicht mehr auf. Ein unterbrochener Lauf wird beim nächsten Mal zu Ende gebracht. Unter alreadyKnown zählen Keycloak-Gruppen ohne Marke, deren Namen CIAS schon für eine eigene Gruppe führt. Sie bleiben unangetastet. Untergruppen übernimmt der Import nicht, nur die oberste Ebene.

Fehler auf einen Blick

Fallen

Weiter

• Die Standardgruppe
• Abgleich mit Keycloak
• Was eine Gruppe ist