Keycloak SAML identiteitsaanbieders voor DigiD / eHerkenning / eIDAS

Custom Keycloak-extensies voor het brokeren van de Nederlandse overheids-IdP's (DigiD, eHerkenning en eIDAS) via SAML. Deze module bevat de identity providers, het SAML-endpoint, de attribuut-/subject-mappers en de SAML-preprocessors.

Bijdrages

Zie CONTRIBUTING.md

Componenten

Component	Provider-id	Omschrijving
DigiDIdentityProviderFactory	digid-saml	DigiD SAML identity provider (sync mode IMPORT).
EHerkenningProviderFactory	eherkenning-saml	eHerkenning SAML identity provider met custom artifact-afhandeling.
EIDasProviderFactory	eidas-saml	eIDAS SAML identity provider met custom artifact-afhandeling.
CustomSamlUserAttributeMapper	custom-saml-user-attribute-idp-mapper	Standaard SAML attribuut-mapper, herregistreerd voor de custom IdP's.
EncryptFederatedIdentifier	encryption-subject-mapper	Hasht het gevoelige subject (bv. BSN) met HMAC-SHA256 vóór opslag.
StripNameIDPolicy	strip-nameid-policy	Verwijdert de NameIDPolicy uit het uitgaande authn-request.
ScopeProcessorPolicy	scope-processor-policy	Voegt een Scoping-element met de doel-IdP toe aan het authn-request.

Configuratie

1. Identity provider-instellingen (admin console)

Configureer per IdP in de Keycloak admin console (Identity Providers) de volgende velden. Deze worden geleverd door AbstractSAMLIdentityProviderFactory:

Veld	Config-key	Type	Omschrijving
User name prefix	usernamePrefix	string	Prefix dat bij import vóór de gebruikersnaam wordt geplaatst.
Redirect context path when cancel the authorization request	cancelRedirectPath	string	Context waarnaar wordt geredirect als de gebruiker de authenticatie annuleert.
Redirect context path when the remote idp is unavailable	unavailableRedirectPath	string	Context waarnaar wordt geredirect als de externe IdP onbereikbaar is.
Force logout before redirect	preForceLogoutFlow	boolean	Als true, rondt Keycloak zijn eigen logout al af vóórdat de browser naar de externe IdP wordt geredirect. Zie Geforceerde logout-flow.
Strip name id from saml request	stripNameIDPolicy	boolean	Als true, verwijdert StripNameIDPolicy de NameIDPolicy uit het uitgaande authn-request van deze IdP.
Set scope value for saml request	customScope	string	Provider-id (URN); is dit gezet, dan voegt ScopeProcessorPolicy een Scoping-element met deze waarde toe aan het authn-request van deze IdP.

overrideArtifactHandling wordt voor eHerkenning en eIDAS automatisch op true gezet (custom artifact-resolutie en handmatige signature-validatie). Dit hoeft niet handmatig geconfigureerd te worden.

Geforceerde logout-flow

Standaard wordt de Keycloak-sessie pas opgeruimd nadat de externe IdP de gebruiker terugstuurt naar het single-logout-endpoint. Sommige IdP's sturen die response nooit, waardoor de Keycloak-sessie blijft hangen tot deze verloopt.

Staat preForceLogoutFlow op true, dan rondt CustomSAMLIdentityProvider in keycloakInitiatedBrowserLogout de Keycloak-kant van de logout direct af (via AuthenticationManager.finishBrowserLogout), nog vóór de redirect naar de IdP. De lokale sessie wordt daarmee altijd opgeruimd, ongeacht of de IdP antwoordt. De browser wordt daarna alsnog naar het SAML-logoutrequest van de IdP geredirect.

2. Subject-encryptie mapper (encryption-subject-mapper)

Voeg aan elke IdP de mapper Subject Encryption toe (categorie Subject Transformer) om het gevoelige subject (bv. BSN) niet in platte tekst op te slaan. Deze mapper heeft géén eigen configuratievelden, maar vereist de omgevingsvariabele KC_PII_ENCKEY. Ontbreekt de sleutel, dan faalt de login met een IdentityBrokerException.

SAML-preprocessors

De StripNameIDPolicy- en ScopeProcessorPolicy-preprocessors worden automatisch toegepast op alle uitgaande SAML authn-requests, maar passen het request alleen aan op basis van de per-IdP-configuratie (zie Identity provider-instellingen). De preprocessor leidt de broker-alias af uit de assertion consumer service URL van het request en haalt vervolgens de bijbehorende IdentityProviderModel op:

Preprocessor	Config-key (per IdP)	Gedrag
strip-nameid-policy	stripNameIDPolicy (boolean)	Verwijdert de NameIDPolicy uit het request als de waarde true is.
scope-processor-policy	customScope (string)	Voegt een Scoping-element met de opgegeven provider-id toe als de waarde niet leeg is.

Omgevingsvariabelen

Variabele	Vereist	Omschrijving
KC_PII_ENCKEY	Ja (bij gebruik van de subject-encryptie mapper)	HMAC-SHA256 geheim voor het hashen van het subject. Minimaal 16 tekens.

Bekende problemen

Client credentials zichtbaar bij eerste aanmaak in de UI

Dit is een bekend issue in de Keycloak admin console: bij het initieel aanmaken van de provider/client toont de UI de gegenereerde client credentials (client secret). Dit is gedrag van Keycloak zelf en geen onderdeel van deze extensie.

Bouwen en installeren

De extensie wordt gebouwd tot één JAR en in de Keycloak providers-map geplaatst:

mvn clean package -Dkeycloak.version=<keycloak-versie>
# resultaat: target/keycloak-custom-provider.jar  ->  /opt/keycloak/providers/

SIG

This repo is uploaded (published) to SIG on every main branch build. SIG queues the code for analysis immediately after receiving it. The SIG monitor is available to see results.

See sigrid.yaml for some config and a list of excluded files.

Sigrid CI

The GitLab pipelines use Sigrid CI to report the maintainability of new code when a merge request is made. New code is defined by the files that are changed on the branch the pipeline runs for, compared to the most recent baseline from the main branch. The results sigrid code analysis, for a feature branch with a merge request, can be found in the output the gitlab report sigrid stage.

See .gitlab-ci.quality.yml for details of invoking Sigrid CI. The credentials 'SIGRID_CI_TOKEN' are configured in the GitLab project.

See also https://docs.sigrid-says.com/sigridci-integration/gitlab.html.