Einleitung
Verwenden Sie die Open-Source-Software https://www.keycloak.org/ zur Authentisierung Ihrer Anwendung mittels OIDC. Die hier beschriebene Konfiguration ist ein vereinfachtes Beispiel für die Verwendung von Keycloak in Verbindung mit dem SAML 2.0 IdP der Technischen Universität Dresden. Ziel dieser Dokumentation ist die SSO Authentifizierung über den IdP der Technischen Universität Dresden. Für weitere Informationen zu Keycloak lesen sie hier
Installation
Zur Dokumentation und Testen der relevanten Keycloak Konfiguration, wird Keycloak hier als Container im Debug-Modus betrieben. Für den produktiven Betrieb wird die produktive Installation (siehe: Keycloak im Container) dringend empfohlen.
- https://www.keycloak.org/getting-started/getting-started-docker
- https://www.keycloak.org/getting-started/getting-started-podman
podman run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.1.4 start-dev
Konfiguration
Voraussetzung für die Konfiguration ist ein Zugriff auf https://localhost:8080. Verwenden Sie für den ersten Zugriff den definierten Admin Account admin mit dazugehörigen Passwort admin.
Realm erstellen
Erstellen Sie einen Realm mit Create realm.
Legen Sie einen Namen mit Realm name fest z.B. myrealm und erstellen Sie diesen mit Create.
Client Scope erstellen
Zur Verwendung von OIDC und Zugriff auf den /userinfo Endpunkt erstellen wir unter Client scopes > Create client scope den Scope Name openid.
Client erstellen
Erstellen Sie einen Client, der die Kommunikation über OIDC benötigt. In unserem Beispiel wird ein Client unter https://localhost:8443 betrieben. Mit Create client wird die Clientkonfiguration erstellt.
Als Client ID wird hier myclient festgelegt. Mit Next werden die Fähigkeiten des Clients festgelegt.
Diese Clientkonfiguration verwendet die Standard-Authentifizierung-Flows. Als zusätzlichen Schutz ist noch Client authentication aktiviert, welche ein Secret für diesen Client erstellt.
Bei den Loginangaben wird als Root URL der URL des Clients https://localhost:8443 gesetzt. Weitere Endpoints werden automatisch mit /* vom Assistenten gesetzt, wenn die Konfiguration mit Save abgeschlossen wird.
Unter Clients > Credentials entnehmen Sie bitte das Client secret, welches später für den OIDC Zugriff benötigt wird .
Der zuvor erstellte Client Scope muss mit Clients > Add client scope dieser Clientkonfiguration zugeordnet werden.
Eine vollständigen OIDC Übersicht der konfigurierten Endpunkte erhält man unter Realm settings > OpenID Endpoint Configuration. Oder unter den Link http://localhost:8080/realms/myrealm/.well-known/openid-configuration.
Client testen
Erstellen Sie sich einen lokalen Account test mit dem Passwort test. Dieser Account muss in den Standardeinstellungen eine validierte E-Mail besitzen, andernfalls wird der access_token nicht anerkannt. Weiterhin sollte das gesetzte Passwort nicht temporär sein, sondern sofort gelten. Nachdem der Nutzer erstellt ist, können Sie mit folgendem Befehl einen access_token mit einstprechender Gültigkeit abfragen:
curl -X POST \
http://localhost:8080/realms/myrealm/protocol/openid-connect/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json' \
-d 'grant_type=password' \
-d 'client_id=myclient' \
-d 'scope=openid' \
-d 'username=test' \
-d 'password=test' \
-d 'client_secret=e0eyirK26myu8Gz8Va9RrF6u1Gj2tQKX'
Mit dem access_token kann der /userinfo Endpunkt abgefragt werden, ohne dass eine erneute Authentifizierung stattfinden muss.
curl -X GET http://localhost:8090/realms/myrealm/protocol/openid-connect/userinfo -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer <access_token>'
SAML Zertifikate importieren
Für diesen Realm importieren Sie Ihre SAML Zertifikate im Menü Realm Settings > Keys mit dem Button Add provider.
Sie benötigen das SAML Zertifikat zweimal. Einmal zur Signierung rsa und für die Verschlüsselung rsa-enc. Führen Sie diesen Schritt zweimal aus.
Als Name empfiehlt sich den Suffix -saml anzuhängen. Als Algorithm wurde hier RS256 verwendet, welcher beim der IdP Konfiguration eine Rolle spielt. Die Priority wurde auf 10 gesetzt, sodass die automatisch generierten RSA Zertifikat übertrumpft werden.
Importieren Sie das SAML Verschlüsselungszertifikat ebenso.
Hinweis: Verwenden Sie für die SAML Zertifikate die Vorgaben der DFN-AAI. Weiterhin ist es sinnvoll, die automatisch generierten RSA Zertifikate rsa und rsa-enc zu löschen, da diese andernfalls in die SP Metadaten mit eingehen und nicht den Vorgaben der DFN-AAI entsprechen.
Identity Provider konfigurieren
Keycloak ermöglicht es die Authentisierung gegen eine Vielzahl von Identity Provider vorzunehmen. Darunter auch ein SAML v2.0 Identity Provider.
Sie können die Shibboleth SAML 2.0 IdP Konfiguration gegen einen der folgenden IdP SAML entity descriptor richten:
| Test | https://idp3-test.tu-dresden.de/idp/shibboleth |
| Produktion | https://idp.tu-dresden.de/idp/shibboleth |
Setzen Sie den Display-Name auf Shibboleth IdP Technische Universität Dresden, damit dieser im Anmeldefenster angezeigt wird.
Schauen Sie sich die Metadaten Show metadata an und passen Sie das NameID policy format auf Persistent an. Speichern Sie die IdP Konfiguration mit dem Button Add ab.
Nachdem die Konfiguration gespeichert wurde sind folgende Schalter nachträglich einzuschalten:
- Want AuthnRequests signed
- Wurde der Standard beim Import der SAML Zertifikaten verwendet, so sind hier keine Einstellungen nötig. Signature algorithm sollte auf
RSA_SHA256stehen.
- Wurde der Standard beim Import der SAML Zertifikaten verwendet, so sind hier keine Einstellungen nötig. Signature algorithm sollte auf
- Want Assertions signed
- Want Assertions encrypted
- Wurde der Standard beim Import der SAML Zertifikaten verwendet, so sind hier keine Einstellungen nötig. Encryption Algorithm sollte auf
RSA-OAEPstehen.
- Wurde der Standard beim Import der SAML Zertifikaten verwendet, so sind hier keine Einstellungen nötig. Encryption Algorithm sollte auf
Optional kann noch der Schalter Validate Signatures und Sign service provider metadata eingeschalten werden. Speichern Sie die Anpassungen mit Save ab.
Identity Provider Claims verknüpfen
Damit die IdP-Daten zu den Keycloak-Daten passen müssen diese mit einem Mapping versehen werden.
Legen Sie fest, welche Attribute einer Identität Sie benötigen. Diese Attribute können Sie unter Realm settings > User profile erstellen bzw. konfigurieren. Weiter Informationen dazu: Keycloak user profile.
Das Mapping der festgelegten Realm Identitätsdaten mit den IdP-Daten wird unter Identity providers > Shibboleth IdP Technische Universität Dresden > Mappers erstellt bzw. konfiguriert.
Erstellen Sie für jedes Attribut das benötigen ein Mapping. Hinweise zu den IdP Attributen finden Sie hier.
Metadaten an IdP übergeben
Ist die IdP Konfiguration abgeschlossen können die Metadaten des Realms unter http://localhost:8080/realms/myrealm/broker/saml/endpoint/descriptor abgerufen werden. Diese Metadaten benötigen die IdPs, über die der SP die Authentifizierung vornehmen möchte (siehe auch Anbindungsprozess).
Authentifizierung
Sind die Metadaten am gewünschten IdP verfügbar, so kann über http://localhost:8080/realms/myrealm/account die Anmeldung erfolgen. Der konfigurierte IdP wird als Shibboleth IdP Technische Universität Dresden dargestellt.
Ein Klick auf Shibboleth IdP Technische Universität Dresden leitet die Anmeldung zum gewünschten IdP, welcher nach erfolgreiche Nutzerauthentisierung die Daten an Keycloak zurückliefert.
Je nach IdP / Keycloak Konfiguration können die Keycloak Daten vollständig erfasst werden. Fehlende Daten müssen manuell ergänzt werden.
Authentifizierungsfluss konfigurieren
Keycloak bietet mit Authentication die Möglichkeit verschiedene Authentifizierungsflüsse einzeln anzupassen. In diesem Beispiel soll bei der browser Authentifizierung ein Standard-IdP bereits vorausgewählt angesprochen werden, ohne dass der/die Nutzer:in dies im Realm Formularfenster auswählt.
Unter Authentication > Flows sind bereits Authentifizierungsflüsse für diverse Standards vorgegeben. Wir verwenden den Standard und duplizieren mit Duplicate den browser Flow. Als Name wird browser with default idp gesetzt.
In den Einstellungen von browser with default idp wird der Punkt Identity Provider Redirector angepasst. Hier wird mit Default Identity Provider der enstrechende Alias saml gesetzt, wie er im Abschnitt Identity Provider konfigurieren angegeben wurde. Die Konfiguration wird mit dem Alias default idp gespeichert.
Die duplizierte Authentifizierungsflusskonfiguration wird nun zu einem Authentifizierungsfluss zugeordnet. Mit der Option Bind flow wird die Konfiuration dem Browser flow zugeordnet. Dabei wird die bestehende browser Konfiguration als Not in use gesetzt und die duplizierte browser with default idp Konfiguration wird zukünftig für den Realm myrealm verwendet.
