Ports und Adapter

Worum es geht

CIAS schreibt vieles in den Identity Provider (kurz IdP), also in Keycloak: Konten, Organisationen, Rollen, Gruppen, Attribute. Trotzdem kennt keines der Fachmodule Keycloak. Die Registrierung weiß nicht, welche URL Keycloak hat, und die Rollenvergabe weiß nicht, wie Keycloak eine Rolle speichert.

Das liegt an einer Trennung in zwei Teile:

• Ein Port ist eine Schnittstelle in Java. Sie sagt nur, was gebraucht wird: „lege ein Konto an“, „vergib diese Rolle in diesem Mandanten“.
• Ein Adapter ist eine Klasse, die diese Schnittstelle für ein bestimmtes System erfüllt. Er weiß, wie das in Keycloak geht: welcher HTTP-Aufruf, welche Felder, welche Antwort.

Das Bild

flowchart LR
    subgraph Fachmodule
      R["cias-registration"]
      U["cias-user"]
      A["cias-authorization"]
    end
    subgraph P["cias-iam-api: Ports"]
      P1["Konten"]
      P2["Organisationen"]
      P3["Rollen"]
      P4["Gruppen"]
      P5["Attribute"]
    end
    R --> P
    U --> P
    A --> P
    P --> KA["cias-iam-keycloak<br/>Keycloak-Adapter"]
    P --> MA["cias-iam-memory<br/>Speicher-Adapter"]
    KA -- "Admin-REST-API" --> K["Keycloak"]
    MA --> M[("Speicher<br/>im Prozess")]

Lies es von links nach rechts: Die Fachmodule kennen nur die Mitte. Rechts steht genau ein Adapter, je nach Einstellung. Die Pfeile zeigen nur in eine Richtung. Kein Fachmodul greift an der Mitte vorbei auf Keycloak zu. Das prüft in jedem Fachmodul ein Architekturtest: ein Test, der beim Bauen scheitert, sobald eine Klasse ein Keycloak-Paket importiert.

Die Ports

Es gibt elf Ports. Jeder deckt eine Fähigkeit ab, nicht ein ganzes System. Ein Modul, das nur Adressen nachschlägt, hängt nicht an der Rollenverwaltung.

Drei Begriffe aus der Tabelle:

• Eine Realm-Rolle gilt im ganzen Realm und damit in allen Modulen, etwa platform-admin. Eine Client-Rolle gehört zu einem Client und bedeutet nur dort etwas, etwa eine Rolle von CDMS. Siehe Realm-Rolle, Client-Rolle, Organisationsrolle.
• Eine Organisation ist in Keycloak das Abbild eines dynamischen Mandanten. Siehe Statische und dynamische Mandanten.
• Das User Profile ist in Keycloak ein Dokument je Realm, das festlegt, welche Attribute ein Konto haben darf.

Die Regeln hinter den Ports

Die Ports sind mit Absicht so geschnitten. Jede Regel verhindert einen bestimmten Fehler.

• Kein Keycloak-Typ in einem Port. Keine Signatur und keine Fehlerklasse nennt Keycloak. Der Port kennt nur eigene, kleine Datensätze wie NewIdentity oder IamIdentity.
• Kein Passwort. Es gibt „Passwort setzen verlangen“, aber kein „Passwort setzen“. CIAS nimmt nie ein Passwort entgegen.
• Kein Benutzername. Die E-Mail-Adresse ist die Anmeldung. Ein Konto je Adresse, beliebig viele Mandanten.
• Global und „in einer Organisation“ sind getrennte Methoden. assign vergibt plattformweit, assignInOrganization nur in einem Mandanten. Wären beide eine Methode mit einem optionalen Mandanten, könnte ein Mandanten-Administrator sich aus Versehen plattformweite Rechte geben.
• Realm-Rollen und Client-Rollen sind getrennte Ports. Aus demselben Grund: Über den Port für Client-Rollen kann man keine Realm-Rolle erreichen.
• Jeder Aufruf darf zweimal kommen. Eine Rolle vergeben, die schon da ist, ändert nichts. Ein Konto freischalten, das schon frei ist, auch nicht. Zwischen CIAS und Keycloak gibt es keine gemeinsame Transaktion. Geht eine Antwort verloren, ist Wiederholen der einzige Weg, und der darf nichts kaputt machen.
• Eine neue Fähigkeit ist ein neuer Port. Keine Sammelschnittstelle mit dreißig Methoden.
• Ein Attribut braucht drei Schritte, jeder in seinem Port. Das Profil erlaubt es (UserProfileManagementPort), ein Konto bekommt einen Wert (IdentityAttributePort oder beim Anlegen), und der Wert kommt ins Token (ClaimMappingPort). Siehe Der Weg ins Token.

Verweise statt Schlüssel

Keycloak vergibt eigene IDs. CIAS hält sie in kleinen Hüllen fest: ExternalUserId, ExternalOrganizationId, ExternalGroupId, ExternalRoleId. Das sind nur Verweise: „dieses Ding liegt dort im IdP“.

Die fachliche Identität bleibt in CIAS:

Wer den IdP wechselt, ändert also Verweise, nicht Daten.

Wenn Keycloak etwas nicht tut

Jeder Port meldet Probleme mit einer von vier Fehlerarten. Die Fachmodule reagieren auf die Art, nicht auf einen HTTP-Status.

Suchen melden „nicht gefunden“ nicht als Fehler, sondern als leeres Ergebnis. „Unter dieser Adresse gibt es kein Konto“ ist auf einem öffentlichen Endpunkt die normale Antwort.

Welcher Adapter läuft

Zwei Dinge müssen zusammenkommen: Das Jar des Adapters liegt im Klassenpfad, und die Einstellung nennt ihn.

Liegen beide Jars im Klassenpfad, läuft trotzdem nur der eine, den die Einstellung nennt. Das eigenständige CIAS liefert beide mit: Im Profil local steht memory, sonst keycloak.

Ein zweiter Provider ist ein zweites Artefakt

Soll CIAS einmal mit einem anderen IdP arbeiten, ändert niemand die Fachmodule. Stattdessen entsteht ein neues Modul, etwa cias-iam-<name>:

Warum ein eigenes Artefakt und nicht ein Schalter im Keycloak-Adapter? Jeder Adapter bringt die Bibliotheken seines IdP mit. Stünden zwei IdPs in einem Modul, hinge jede Installation an beiden. Und die Vertragstests prüfen genau einen Adapter auf einmal.

Nicht jeder IdP kann alles. Organisationen, Rollen in Organisationen oder Rollen an Gruppen sind Fähigkeiten von Keycloak. Ein IdP ohne Organisationen kann keine dynamischen Mandanten tragen.

Fallen

Weiter

• Der Keycloak-Adapter
• Der Speicher-Adapter für Tests und Entwicklung
• Die Keycloak-Erweiterung für den Passwort-Link
• CIAS als Brücke zum Identity Provider