Ein Ablauf, vier Varianten

Worum es geht

Eine Person wird in CIAS immer über denselben Ablauf zum Benutzer. Es gibt mehrere Varianten, aber keine getrennten Programme. Die Varianten unterscheiden sich nur in ihrer Policy: wer den Vorgang auslösen darf, welche Felder Pflicht sind, woher der Mandant kommt, ob jemand freigeben muss und wie lange der Link gilt. Jede Policy steht in der Konfiguration der Installation.

Warum nur ein Ablauf? Vier Kopien von „prüfen, Konto anlegen, Mandant zuordnen, Rollen vergeben, benachrichtigen, protokollieren“ würden mit der Zeit auseinanderlaufen. Die Kopie, die ausschert, ist dann die, die die Mandantentrennung nicht mehr durchsetzt.

Die Varianten nebeneinander

Wer löst aus, woher kommt der Mandant?

	SELF_SERVICE	PLATFORM_ADMIN	TENANT_ADMIN	Einladung einlösen
Wer löst aus?	die Person selbst	Plattform-Administrator	Mandanten-Administratorin	die eingeladene Person
Endpunkt	`POST /cias/registration/self`	`POST /cias/admin/registrations`	`POST /cias/tenant/registrations`	`POST /cias/registration/invitations/accept`
Anmeldung nötig?	nein, öffentlich	ja, mit den Rollen aus der Policy	ja, ausgeliefert: Rolle `tenant-admin`	nein, der Link ist der Ausweis
Mandant kommt aus	Policy, ausgeliefert: neuer Mandant; ein Hook darf ändern	Policy, etwa dem Payload (nur hier erlaubt)	dem Token des Aufrufers, niemals dem Payload	der Einladung
typischer Fall	eine Firma meldet sich für die Anwendung an	Support legt einen Zugang von Hand an	Administratorin lädt eine Kollegin ein	die Kollegin nimmt die Einladung an

TENANT_ADMIN und das Einlösen gehören zusammen: Das eine verschickt die Einladung, das andere löst ihren Link ein. Welche Varianten eine Installation anbietet, steht in ihrer Konfiguration. cias-runtime bietet SELF_SERVICE und TENANT_ADMIN, der Hub nur SELF_SERVICE. PLATFORM_ADMIN muss eine Installation erst einschalten, siehe Anlage durch den Plattform-Administrator.

Der gemeinsame Ablauf

Alle Varianten durchlaufen dieselben Zustände. Nur der Einstieg und die Freigabe unterscheiden sich.

stateDiagram-v2
    direction LR
    [*] --> PENDING_VERIFICATION: Anfrage angenommen,<br/>Mail mit Link verschickt
    PENDING_VERIFICATION --> VERIFIED: Link geklickt<br/>(oder Admin bestätigt)
    VERIFIED --> PENDING_APPROVAL: Freigabe nötig
    VERIFIED --> PROVISIONING: keine Freigabe nötig
    PENDING_APPROVAL --> APPROVED: genehmigt
    PENDING_APPROVAL --> REJECTED: abgelehnt
    APPROVED --> PROVISIONING
    PROVISIONING --> COMPLETED: Mandant, Rollen,<br/>Willkommensmail
    PROVISIONING --> FAILED: Fehler
    FAILED --> PROVISIONING: retry
    PENDING_VERIFICATION --> EXPIRED: verfallen, ersetzt, verworfen
    PENDING_APPROVAL --> EXPIRED: verfallen, ersetzt, verworfen
    COMPLETED --> [*]

Alle Zustände und Übergänge erklärt Die Zustände einer Registrierung.

Was in jeder Variante gleich passiert

1

CIAS
prüft, ob die Variante eingeschaltet ist und der Aufrufer die nötigen Rollen hat, bei SELF_SERVICE zusätzlich die Drosselung
2

CIAS
bestimmt den Mandanten und prüft die Felder gegen die Feldbeschreibung der Variante

Fehlt ein Pflichtfeld oder lehnt ein Hook ab: 422
3

CIAS→Keycloak
legt bei neuer Adresse das Konto deaktiviert und unbestätigt an. Bei bekannter Adresse bleibt das Konto unberührt
4

CIAS
erzeugt einen Einmal-Link. Gespeichert wird nur sein Hash
5

CIAS→E-Mail
verschickt eine eigene Mail. Welche, hängt davon ab, ob die Adresse neu ist
6

Benutzer→CIAS
klickt den Link
7

CIAS
Freigabe nötig? Dann wartet der Vorgang in PENDING_APPROVAL
8

CIAS→Keycloak
schaltet ein neues Konto frei, ordnet den Mandanten zu, vergibt die Startrollen
9

CIAS→E-Mail
schickt die Willkommensmail, bei neuem Konto möglichst mit Link zum Passwort-Setzen

Ergebnis: Registrierung COMPLETED, die Person kann sich anmelden

Jede Variante im Ablauf

Die Varianten Schritt für Schritt

SELF_SERVICEPLATFORM_ADMINTENANT_ADMINEinladung einlösen

Wann: Jemand registriert sich ohne Anmeldung über das öffentliche Formular.

1

Benutzer→CIAS
füllt das Formular aus: E-Mail, Name, Firma. Kein Passwort
2

CIAS
prüft die Drosselung (höchstens einige Versuche je Adresse)
3

CIAS→Benutzer
antwortet 202 { "status": "accepted" }, egal ob die Adresse neu oder bekannt ist
4

CIAS→E-Mail
neue Adresse: Bestätigungsmail. Bekannte Adresse: eine Mail, die das bestehende Konto verwendet
5

Benutzer→CIAS
klickt den Link
6

CIAS
wartet auf die Freigabe durch einen Plattform-Administrator, wenn die Policy das verlangt
7

CIAS
legt einen neuen Mandanten an, Schlüssel aus dem Firmennamen. Die Person bekommt die Gründerrollen

Ergebnis: Neuer Mandant, erste Person darin mit den Rollen der Situation TENANT_FOUNDER. Siehe Selbstregistrierung.

Wann: Ein Plattform-Administrator legt einen Zugang von Hand an.

1

Admin→CIAS
POST /cias/admin/registrations mit E-Mail, Feldern und optional tenantKey
2

CIAS
prüft die Rollen aus required-caller-roles, etwa platform-admin
3

CIAS
bestimmt den Mandanten nach der Policy, bei FROM_PAYLOAD aus dem Payload. Nur diese Variante darf das
4

CIAS→E-Mail
Mail mit Link an die Person
5

Benutzer→CIAS
klickt den Link, danach Bereitstellung wie immer

Ergebnis: Siehe Anlage durch den Plattform-Administrator.

Wann: Eine Mandanten-Administratorin lädt jemanden in ihren eigenen Mandanten ein.

1

Admin→CIAS
POST /cias/tenant/registrations mit E-Mail und Namen
2

CIAS
prüft die Rolle (ausgeliefert: tenant-admin)
3

CIAS
nimmt den Mandanten aus ihrem Token. Ein tenantKey im Payload wird ignoriert, nicht einmal geprüft
4

CIAS→E-Mail
Mail mit Link. In cias-runtime gilt er 14 Tage

Ergebnis: Einladung verschickt, Vorgang wartet in PENDING_VERIFICATION. Siehe Einladung durch den Mandanten-Administrator.

Wann: Die eingeladene Person nimmt die Einladung an.

1

Benutzer→CIAS
öffnet den Link. GET /invitations/{token}/form liefert die Felder, die die Einladende offen gelassen hat
2

Benutzer→CIAS
POST /invitations/accept mit dem Link-Token
3

CIAS
Link unbekannt oder abgelaufen? 404. Schon eingelöst? Dieselbe Antwort wie beim ersten Mal
4

CIAS
tritt dem Mandanten aus der Einladung bei, vergibt die Mitgliedsrollen

Ergebnis: Person ist Mitglied im Mandanten der Einladenden. Siehe Eine Einladung einlösen.

Neue oder bekannte Adresse

In CIAS ist die E-Mail-Adresse das Konto. Es gibt ein Konto pro Adresse und beliebig viele Mandanten-Mitgliedschaften. Deshalb gabelt sich jede Variante an derselben Stelle:

Welche Mail bekommt die Person?

Konto zur Adresse?	Gibt es einen Mandanten zum Beitreten?	Mail und Folge
nein	–	`VERIFY_EMAIL` – neues Konto
ja	ja	`MEMBERSHIP_INVITATION` – Beitritt zu einem weiteren Mandanten. Passwort und Konto bleiben unberührt
ja	nein	`ALREADY_REGISTERED` – „Sie haben bereits ein Konto“, mit Anmeldelink

Wie lange der Link in der Mail gilt, legt die Policy der Variante fest (token-ttl): in cias-runtime 24 Stunden für die Selbstregistrierung, 14 Tage für die Einladung.

Von außen sehen alle drei Fälle gleich aus: gleicher Status, gleiche Antwort. Nur die Mail unterscheidet sich. So lässt sich über die API nicht herausfinden, ob zu einer Adresse ein Konto existiert. Mehr dazu unter Die E-Mail ist das Konto.

Woher der Mandant kommt

Der Mandant wird in zwei Stufen bestimmt:

Wer entscheidet über den Mandanten?

CIAS

Policy der Variante

z. B. SELF_SERVICE → neuer Mandant, TENANT_ADMIN → aus dem Token
Hook

Hook des Projekts

darf die Policy überschreiben, außer wenn der Mandant aus dem Token kommt (FROM_CALLER)
Mandant steht fest. Ob es ihn gibt, prüft die Bereitstellung

Alle sechs Arten der Zuordnung (NONE, CREATE_NEW, JOIN_EXISTING, FROM_CALLER, FROM_PAYLOAD, FROM_INVITATION) erklärt Woher der Mandant kommt.

Welche Rollen die Person bekommt

Das entscheidet ein Regelwerk je Situation:

Situation	tritt ein bei	Rollen in der Grundeinstellung
`TENANT_FOUNDER`	erste Person eines neuen Mandanten	`tenant-owner`, `tenant-admin`, `tenant-user` (Client-Rollen)
`TENANT_MEMBER`	Beitritt zu einem bestehenden Mandanten	`tenant-user` (Client-Rolle)
`TENANTLESS`	Registrierung ohne Mandant	`user` (Realm-Rolle)

Die Grundeinstellung ist eine Bean im Code der Anwendung. Plattform- und Mandanten-Administration können sie durch eigene Regeln ersetzen. Wie das geht und wer das darf, steht unter Startrollen als Regelwerk.

Was die Antwort verrät (und was nicht)

Öffentliche und administrative Endpunkte antworten verschieden

öffentlich

/self, /verify, /invitations/…

angenommen: immer 202 mit accepted
zweiter Klick: wieder 202
unbekannter oder abgelaufener Link: 404
kein Zustand, keine ID
Drosselung: 429 ohne Wartezeit-Angabe

administrativ

/cias/admin/…, /cias/tenant/…

Aufrufer ist bekannt
Zustand und ID sichtbar
Liste aller Registrierungen mit Filter nach Zustand
403 bei fehlender Rolle

Details unter Schutz der öffentlichen Endpunkte.

Die Endpunkte auf einen Blick

Methode und Pfad	Variante	Zweck
`GET /cias/registration/flows/{flow}/form`	alle	Feldbeschreibung für das Formular
`POST /cias/registration/self`	SELF_SERVICE	registrieren
`POST /cias/registration/verify`	alle	Link einlösen
`GET /cias/registration/invitations/{token}/form`	Einladung	offene Felder der Einladung
`POST /cias/registration/invitations/accept`	Einladung	Einladung annehmen (Link einlösen)
`POST /cias/admin/registrations`	PLATFORM_ADMIN	Person anlegen
`POST /cias/tenant/registrations`	TENANT_ADMIN	Person einladen
`GET /cias/admin/registrations`	alle	Liste, Filter nach Zustand
`POST /cias/admin/registrations/{id}/approve` · `reject` · `retry` · `activate` · `discard`	alle	Freigabe und Pflege, nur Plattform-Administrator
`GET` · `PUT` · `DELETE /cias/admin/registration-rules/…`	alle	Regeln für die Startrollen