This extension makes it possible to use BundID as an identity provider in Keycloak. It handles the technical details of the SAML communication with BundID, so you don't have to implement this yourself. By using this extension, you can connect your applications to BundID and authenticate users with their BundID accounts.
Specifically, this extension provides:
- BundID SAML Integration: Facilitates SAML-based identification with BundID by automatically enriching SAML requests with necessary trust levels and user information.
- Attribute Mapping: Provides mappers to transfer BundID user attributes (like email, retrieval timestamp) into Keycloak sessions and OIDC tokens.
- Configurable Trust Levels: Enables configuration of minimum required trust levels (Level of Authentication - LoA) for authentication with BundID.
- Mandatory Fields: Supports the transmission of mandatory BundID attributes (e.g., Organization Display Name, Online Service ID).
This extension is actively maintained and subject to rigorous quality standards:
- Monthly Releases: We plan to release updates at least monthly, including security patches and dependency updates to keep the extension current and secure.
- Code Quality: All code undergoes continuous quality assurance through automated testing and code reviews.
- Compatibility Testing: Each release of this Keycloak extension is thoroughly tested with the Keycloak version specified in the
pom.xmlto ensure full compatibility and stability.
Die Nutzung von BundID für die Identifizierung basiert auf SAML. Im SAML-Request müssen einige Einstellungen für das benötigte Vertrausniveau, die zulesenden Elemente und DisplayInformation abgebildet sein. Diese Keycloak-Extension sorgt für die Anreicherung des SAML-Requests.
Die Extension kann von Maven Central bezogen und in das providers-Verzeichnis von Keycloak kopiert werden.
Der Kernbestandteil ist eine Implementierung des AuthenticationPreprocessor-Interfaces, welches die Anreicherung des SAML-Requests übernimmt.
Zur Steuerung, für welchen Identity Provider die Anbindung erfolgen soll, muss die Konfigurationsoption KC_SPI_SAML_AUTHENTICATION_PREPROCESSOR_BUNDID_PROTOCOL_ACTIVE_FOR_IDP gesetzt werden.
Der Default-Wert ist bundid. D.h. wenn dieser Name für den BundID-Identity Provider verwendet wird, funktioniert die Anbindung ohne gesonderte Konfiguration.
Die Extension definiert mehrere IdentityProviderMapper:
saml-bundid-session-attribute-idp-mapper(für das Mapping von BundID-Attributen in die Keycloak-Session)saml-bundid-session-email-idp-mapper(setzt zusätzlich die E-Mail im BrokeredIdentityContext und macht sie damit für die weitere Verarbeitung in Keycloak bekannt)saml-retrieval-time-session-attribute-idp-mapper(für das Mapping des Zeitstempels der BundID-Authentifizierung in die Keycloak-Session)
Außerdem wird ein ProtocolMapper definiert:
oidc-bundid-sessionnote-mapper(zum Mapping der Attribute aus der UserSession in das Token)
Die Funktionsweise ist dabei, dass über den saml-bundid-session-attribute-idp-mapper die jeweiligen BundID-Attribute (+ das jeweilige Vertrauensniveau) in die Keycloak-Session gemappt werden.
Zusätzlich werden dort, über die angegebene OID, die Attribute im SAML-Request angefordert.
Über den oidc-bundid-sessionnote-mapper werden alle BundID-Attribute aus der Session in das Token gemappt.
Diese werden über einen Namenspräfix ba.bundid_prop_ ausgezeichnet und im ProtocolMapper erkannt.
Es ist über die Parameter der Mapper möglich, einzelne Attribute vom Automapping auszuschließen.
<saml2p:Extensions>
<akdb:AuthenticationRequest xmlns:akdb="https://www.akdb.de/request/2018/09" Version="2">
<akdb:RequestedAttributes>
<akdb:RequestedAttribute Name="urn:oid:2.5.4.18" RequiredAttribute="false" />
<akdb:RequestedAttribute Name="urn:oid:1.2.40.0.10.2.1.1.149" RequiredAttribute="true" />
<akdb:RequestedAttribute Name="urn:oid:1.3.6.1.4.1.25484.494450.3"/>
...
</akdb:RequestedAttributes>
</akdb:AuthenticationRequest>
</saml2p:Extensions>
Diese Extension definiert einen eigenen IdentityProviderMapper (für das Mapping von BundID-Attributen in die Keycloak-Session): saml-bundid-session-attribute-idp-mapper.
Dieser Mapper erlaubt zusätzlich die Angabe einer OID sowie ob das Feld als Pflichtattribut angefordert werden soll.
Dadurch werden automatisch die o.g. RequestedAttributes im SAML-Request befüllt.
Zur weiteren Vereinfachung gibt es zudem die Möglichkeit, den oidc-bundid-sessionnote-mapper (Keycloak-ProtocolMapper zum Mapping der Attribute aus der UserSession in das Token) zu nutzen.
Darüber werden alle vom saml-bundid-session-attribute-idp-mapper in die Session gemappten Attribute (+ jeweils ein Attribut zur Angabe des zugehörigen Vertrauensniveaus) in das Token gemapped.
<saml2p:RequestedAuthnContext Comparison="minimum">
<saml2:AuthnContextClassRef xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">STORK-QAA-Level-3</saml2:AuthnContextClassRef>
</saml2p:RequestedAuthnContext>
Gesteuert wird dies über das angeforderte Level of Authentication (LoA), wobei hier die Werte 1 bis 4 zulässig sind.
Die Anforderung von LoA erfolgt über die Keycloak Step-Up-Authentication. Weitere Infos sind der Keycloak-Dokumentation zu entnehmen.
Zusätzlich ist es möglich, konfigurativ ein absolut minimales vertrauensniveau zu setzen. D.h. selbst wenn Keycloak ein niedrigeres LoA fordert, wird dann dieses Niveau an BundID übergeben.
Gesteuert wird dies über den Parameter KC_SPI_SAML_AUTHENTICATION_PREPROCESSOR_BUNDID_PROTOCOL_MINIMUM_STORK_LEVEL.
<saml2p:Extensions>
<akdb:AuthenticationRequest xmlns:akdb="https://www.akdb.de/request/2018/09" Version="2">
<akdb:DisplayInformation>
<classic-ui:Version xmlns:classic-ui="https://www.akdb.de/request/2018/09/classic-ui/v1">
<classic-ui:OrganizationDisplayName>Bundesagentur für Arbeit</classic-ui:OrganizationDisplayName>
<classic-ui:OnlineServiceId>BMI-4711</classic-ui:OnlineServiceId>
</classic-ui:Version>
</akdb:DisplayInformation>
</akdb:AuthenticationRequest>
</saml2p:Extensions>
Die BundID schreibt die Übergabe weiterer Pflichtattribute vor:
- Organization Display Name (wird dem Nutzer vor Rücksprung zum Service Provider angezeigt)
- Online Service ID (der für den Service Provider durch das BSI vergebene Identifier)
Die Werte für diese Attribute werden über Keycloak-Konfigurationsparameter definiert (hier als ENV-Variable angegeben, kann aber analog sonstiger Keycloak-Konfiguration auch anders gesetzt werden):
KC_SPI_SAML_AUTHENTICATION_PREPROCESSOR_BUNDID_PROTOCOL_ONLINE_SERVICE_IDKC_SPI_SAML_AUTHENTICATION_PREPROCESSOR_BUNDID_PROTOCOL_ORGANIZATION_DISPLAY_NAME
Die Extension ermöglicht es, einzelne BundID-Authentifizierungsmethoden explizit zu aktivieren oder zu deaktivieren. Dies geschieht über zwei kommaseparierte Listen von Methodennamen:
KC_SPI_SAML_AUTHENTICATION_PREPROCESSOR_BUNDID_PROTOCOL_ENABLED_AUTHN_METHODSKC_SPI_SAML_AUTHENTICATION_PREPROCESSOR_BUNDID_PROTOCOL_DISABLED_AUTHN_METHODS
Unterstützte Methodennamen (Groß-/Kleinschreibung wird ignoriert):
| Methodenname | Beschreibung |
|---|---|
eID |
Online-Ausweisfunktion |
eIDAS |
Europäische eIDAS-Identifizierung |
Authega |
Bayern-ID / Authega |
Diia |
Ukrainische Diia-App |
Elster |
ELSTER-Zertifikat |
FINK |
Föderales Identitätsnetz der Kommunen |
Benutzername |
Benutzername und Passwort |
Sind beide Listen leer (kein Standardwert), wird kein AuthnMethods-Element in den SAML-Request eingefügt und BundID entscheidet selbst über die verfügbaren Methoden.
Beispiel – eID aktivieren, FINK deaktivieren:
KC_SPI_SAML_AUTHENTICATION_PREPROCESSOR_BUNDID_PROTOCOL_ENABLED_AUTHN_METHODS=eID
KC_SPI_SAML_AUTHENTICATION_PREPROCESSOR_BUNDID_PROTOCOL_DISABLED_AUTHN_METHODS=FINK
Mehrere Methoden werden kommasepariert angegeben:
KC_SPI_SAML_AUTHENTICATION_PREPROCESSOR_BUNDID_PROTOCOL_ENABLED_AUTHN_METHODS=eID,eIDAS,Authega
KC_SPI_SAML_AUTHENTICATION_PREPROCESSOR_BUNDID_PROTOCOL_DISABLED_AUTHN_METHODS=Diia,Elster,FINK,Benutzername
Das erzeugt folgenden SAML-Request-Abschnitt:
<saml2p:Extensions>
<akdb:AuthenticationRequest xmlns:akdb="https://www.akdb.de/request/2018/09" Version="2">
<akdb:AuthnMethods>
<akdb:eID><akdb:Enabled>true</akdb:Enabled></akdb:eID>
<akdb:eIDAS><akdb:Enabled>true</akdb:Enabled></akdb:eIDAS>
<akdb:Authega><akdb:Enabled>true</akdb:Enabled></akdb:Authega>
<akdb:Diia><akdb:Enabled>false</akdb:Enabled></akdb:Diia>
<akdb:Elster><akdb:Enabled>false</akdb:Enabled></akdb:Elster>
<akdb:FINK><akdb:Enabled>false</akdb:Enabled></akdb:FINK>
<akdb:Benutzername><akdb:Enabled>false</akdb:Enabled></akdb:Benutzername>
</akdb:AuthnMethods>
</akdb:AuthenticationRequest>
</saml2p:Extensions>Methoden, die in keiner der beiden Listen aufgeführt sind, erscheinen nicht im AuthnMethods-Element.
Ungültige oder widersprüchliche Einträge werden beim Start der Extension erkannt und per WARN-Log gemeldet:
| Situation | Verhalten |
|---|---|
| Unbekannter Methodenname | Eintrag wird ignoriert; eine Warnung mit den gültigen Methodennamen wird geloggt |
| Doppelter Methodenname in einer Liste | Duplikat wird ignoriert; eine Warnung wird geloggt |
| Methode in beiden Listen | Methode gilt als aktiviert (enabled-Liste hat Vorrang); eine Warnung wird geloggt |