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.
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.

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/