Implementierung der Prototypen

Im Folgenden beschreiben wir die Implementierung unserer Prototypen. Wir hoffen, dass dies anderen Projekten hilft und wir freuen uns über Austausch mit anderen Projekten zu Best Practices in der Anbindung an BIRD. Der verlinkte Quellcode in diesem Dokument steht im Übrigen unter einer Apache-2.0 License Lizenz und kann gerne weiterverwendet werden.

SSO Konfiguration mit Keycloak

Deployment von Keycloak

Wir deployen Keycloak über einen Kubernetes Cluster (via Terraform). Die Konfigurationen dazu befinden sich in infrastructure-modules-shared/keycloak und infrastructure-env-staging/auth.tf.

Wichtig: In der Version 15.0.x gibt es einen Bug, so dass die Metadaten-XML für Service-Provider falsch generiert wird. Mit der Version 14.0.0 konnten wir erfolgreich eine SAML Anbindung herstellen und diese Konfiguration bezieht sich nur auf diese Version. Für die Version 15.1.0, in der der Bug behoben ist, sind ggf. noch Einstellungen zum AssertionConsumerService Tag in den Metadaten notwendig. Wenn jemand in dieser Version eine erfolgreiche Anbindung hergestellt hat, freuen wir uns über einen Austausch (Ansprechperson Stephan Kulla).

Grundlegende Konfiguration von Keycloak

Zunächst muss ein Realm und ein Client angelegt werden. Hier haben uns die Tutorials https://www.keycloak.org/getting-started/getting-started-kube und https://scalac.io/blog/user-authentication-keycloak-1 geholfen.

Der Client ist die Applikation, die sich mit Keycloak verbindet. Bei uns ist es unser Frontend. Hier benutzen wir die Bibliotheken @react-keycloak/ssr und keycloak-js (siehe unsere prototypische Umsetzung in single-sign-on.tsx). Für andere Programmiersprachen gibt es entsprechende Alternativen.

Wichig: Um Probleme mit Cookies zu vermeiden, sollten der Client und Keycloak auf derselben Domain laufen (ggf. mit unterschiedlichen Subdomains). Bei uns läuft der Client auf lenabi.serlo-staging.dev und Keycloak auf keycloak.serlo-staging.dev, siehe auch https://www.keycloak.org/docs/latest/securing_apps/#_modern_browsers.

BIRD-DAAD als SAML Identity Provider (IdP) anlegen

1. Den neu angelegten Realm auswählen.
2. Auf Identity Providers -> Add provider… -> SAML v2.0 klicken.
3. Alias für den IdP eingeben (z.B. bird-saml).
4. Unter Import External IDP Config -> Import from URL die URL https://saml-bird.daad.com/saml2/idp/metadata.php eingeben und auf Import drücken.
5. Den Button Save klicken.
6. Unter Endpoints auf SAML 2.0 Service Provider Metadata klicken und die angegebene URL mit BIRD-Ansprechperson teilen (siehe Dokumentation in Confluence).
7. Weitere manuelle SAML Konfigurationen:
   • Validate Signature und Want AuthnRequests Signed müssen auf ON gestellt sein.
   • Wir haben auch auf ON gestellt:
     • `Allow Create*
     • HTTP-POST Binding Response
     • HTTP-POST Binding for AuthnRequest
     • Want Assertions Signed
     • Want Assertions Encrypted
     • Sign Service Provider Metadata
   • Als Principal Type sollte Subject NameID gewählt werden (NameID Policy Format ist Persistent). Bei dieser Wahl wird zur Identifikation eine "vom IdP für den SP und User eindeutige ID" genutzt (siehe Confluence-Dokumentation). Es ist aber auch möglich eine globale UUID zu nutzen (Attribut urn:oid:0.9.2342.19200300.100.1.1, siehe Confluence-Dokumentation). Hierfür muss Principal Type auf Attribute [Name] und Principal Attribute auf urn:oid:0.9.2342.19200300.100.1.1 gesetzt werden.
8. Im Reiter "Mappers" haben wir folgende Attribute Importer Mappers definiert:
   • urn:oid:2.16.840.1.113730.3.1.241 -> username
   • urn:oid:2.5.4.42 -> firstName
   • urn:oid:2.5.4.4 -> lastName
   • urn:oid:0.9.2342.19200300.100.1.3 -> email
9. Optional: Um direkt auf die DAAD-BIRD-Login-Seite weiterzuleiten (ohne dass eine Keycloak-Login Seite erscheint), kann man folgende Einstellung vornehmen.

Weitere Hinweise

1. Über samltest.id kann eine grundlegende SAML v2.0 Konfiguration gestested werden.
2. Über keycloak.org/app kann die grundlegende Konfiguration eines Clients getestet werden.
3. In den Tests haben wir die Browser Extension SAML-tracer verwendet.
4. Es lohnt sich, Keycloak in den DEBUG-Modus zu setzen. In den Logs (z.B. per kubectl logs) findet man ausführliche Informationen zum SAML Vorgang (wie z.B. die entschlüsselten SAML Assertions).
5. Keycloak ist im Übrigen nicht von Log4Shell betroffen, siehe keycloak-discussions#9078. Im Docker-Container findet man zwar eine log4j-api.jar, diese enthält aber nicht den betroffenen Code.
6. Die Identifizierung seitens des IdP wurde von E-Mail auf eine eindeutige ID umgestellt (siehe Änderungen in der Confluence-Dokumentation). Bei Neuanmeldungen nach der Umstellung erscheint dementsprechend eine Fehlermeldung, dass ein Account mit der entsprechenden E-Mail bereits existiert (weil sich die ID seitens IdP geändert hat, geht Keycloak davon aus, dass der User neu sei). Hier ist der Workaround den entsprechenden Account unter dem Reiter Users zu löschen.

Data-Wallet

Zum Deployment des Connectors nutzen wir Terraform / Kubernetes. Die Konfigurationen dazu sind in den Dateien unter infrastructure-modules-shared/enmeshed und in infrastructure-env-staging/data-wallet.tf.

• In der Datei data-wallet.tsx befindet sich der Code für das Frontend.
• Die Web-Hooks für den Connector sind in der Datei enmeshed-middleware.ts implementiert.

Metadatenschnittstelle

Die Metadatenschnittstelle von BIRD generieren wir aus unserer prototypischen neuen Metadatenschnittstelle, welche unter lenabi.serlo.org/metadata-api beschrieben ist. In dieser Dokumentation findet man auch Details zur Implementierung dieser GraphQL Schnittstelle. Der Quelltext für den Endpunkt, welches Metadaten im XML Format von BIRD zurückgibt, findet man in der Datei bird-metadata-api.ts.