10. Inlog koppelingen

Bij inlog koppelingen kunt u de authenticatiemogelijkheden voor inwoners, bedrijven en beheerders instellen.

10.1. Configuratie ‘Haal centraal’

Dit dient ter configuratie van de BRP-integratie met de Open Inwoner omgeving. De beheerder stelt hier de Haal Centraal API-service en BRP-versie in, en configureert de HTTP-headers die met elke aanvraag worden meegestuurd.

BRP versie

Selecteer de versie van de Haal Centraal BRP API die uw leverancier ondersteunt:

  • 1.3 — BRP 1.3 (GET-gebaseerde API, endpoint ingeschrevenpersonen)

  • 2.0 t/m 2.7 — BRP 2.x (POST-gebaseerde API, endpoint personen)

Note

Patch versies hebben geen invloed op de keuze: gebruikt uw leverancier bijvoorbeeld versie 2.6.2, kies dan 2.6.

Request headers

Voer de HTTP-headers in als sleutel/waarde-paren die bij elke BRP-aanvraag worden toegevoegd. Welke headers vereist zijn is afhankelijk van uw leverancier:

I Connect

Header

Omschrijving

x-origin-oin

OIN van de gemeente (afzender)

x-afnemer-oin

OIN van de afnemer

x-doelbinding

Doelbinding van de aanvraag

x-verwerking

Verwerkingsactiviteit (vrij tekstveld)

Centric

Header

Omschrijving

x-request-organization

Organisatienaam

x-request-application

Applicatienaam

x-request-afnemerscode

Afnemerscode

x-request-user

Gebruikersnaam

Raadpleeg de documentatie van uw leverancier voor de exacte waarden.

Note

De waarde van x-verwerking werd in eerdere versies gevalideerd op het voorkomen van maximaal één @-teken. Deze validatie is vervallen omdat het veld is vervangen door een generiek sleutel/waarde-veld zonder leverancierspecifieke beperkingen.

10.2. DigiD configuratie

Dit is de configuratie voor de koppeling van het Open Inwoner platform met DigiD van Logius. Bij de onboarding van Open Inwoner wordt bij deze configuratie hulp geboden.

Note

Wanneer de OpenID Connect-koppeling voor DigiD is ingeschakeld (zie sectie 10.5), vervangt deze de SAML-koppeling op de loginpagina. Beide kunnen niet tegelijkertijd actief zijn.

10.3. eHerkenning/eIDAS configuratie

Dit is de configuratie voor de koppeling van het Open Inwoner platform met eHerkenning bij een eHerkenningsmakelaar. Bij de onboarding van Open Inwoner wordt bij deze configuratie hulp geboden.

Note

Wanneer de OpenID Connect-koppeling voor eHerkenning is ingeschakeld (zie sectie 10.6), vervangt deze de SAML-koppeling op de loginpagina. Beide kunnen niet tegelijkertijd actief zijn.

10.4. KVK configuratie

Dit is de configuratie voor de koppeling van het Open Inwoner platform met de KVK. Om Mijn Bedrijven te kunnen gebruiken is het noodzakelijk om de KVK API in te stellen. Hierdoor worden – na het inloggen met eHerkenning - de gegevens van het bedrijf opgehaald en getoond en vooraf ingevuld. Om de KVK API in te kunnen stellen zijn de API key, een client certificate (SSL) en een server certificate (SSL) noodzakelijk.

../_images/Screenshot_OIP_inlogkoppelingen_KVKconfiguratie_Djuzz_250829.png

API root De API root is verschillend voor de testomgeving en de productieomgeving van Open Inwoner. Bij de testomgeving moet de root https://developers.kvk.nl/test/api/ zijn en bij de productieomgeving https://api.kvk.nl/api/v2

Let op! Er is een abonnement noodzakelijk om gebruik te kunnen maken van deze API. Meer informatie over de KVK API kunt u vinden op: https://developers.kvk.nl/documentation

API Key De API Key ontvangt u wanneer u zich aanmeldt om gebruik te maken van de KVK API.

Client certificate Het SSL-certificaat dat wordt gebruikt voor clientidentificatie. Dit veld kan leeg blijven.

Server certificate Het SSL/TLS certificaat van de server. Dit certificaat kunt u downloaden van de KVK website: https://developers.kvk.nl/documentation/certificates

Het gedownloade zip-bestand bevat meerdere certificaat bestanden die u moet combineren tot één bestand:

  1. Pak het zip-bestand uit

  2. Combineer alle .crt bestanden tot één bestand via de commandline:

    cat bestand1.crt bestand2.crt bestand3.crt > combined.crt

    Bijvoorbeeld (bestandsnamen kunnen afwijken):

    cat api.kvk.nl.crt "DigiCert G2 TLS EU RSA4096 SHA384 2022 CA1.crt" \
    "DigiCert Global Root G2.crt" > combined.crt

  3. Upload het gecombineerde bestand bij Server certificate door een bestand certificaat bij te werken (potlood icoon) of een nieuw certificaat toe te voegen (via het plus icoon).

10.5. OpenID Connect configuratie voor DigiD

Open Inwoner ondersteunt DigiD-login voor burgers via het OpenID Connect protocol (OIDC). Dit is een alternatief voor de SAML-gebaseerde DigiD-koppeling. OIDC staat standaard uitgeschakeld en vereist technische configuratie voordat het in gebruik genomen kan worden.

Let op! Enkel de technisch beheerder dient de OpenID Connect Configuratie te wijzigen.

../_images/image77.png

Activatie

Inschakelen Schakelt DigiD-login via OIDC in of uit. Staat standaard uitgeschakeld.

Note

Wanneer ingeschakeld, vervangt de OIDC-koppeling de SAML-gebaseerde DigiD-koppeling op de loginpagina. Beide kunnen niet tegelijkertijd actief zijn.

Algemene instellingen

OpenID Connect client ID Het client-ID verstrekt door de OIDC-provider (identity broker).

OpenID Connect secret Het bijbehorende client-secret van de OIDC-provider.

OpenID Connect scopes De scopes die worden aangevraagd bij de identity provider. Standaard: openid, bsn.

Ondertekeningsalgoritme Algoritme waarmee de provider ID-tokens ondertekent. Standaard HS256; gebruik RS256 bij een asymmetrisch sleutelpaar.

Ondertekeningssleutel Openbare sleutel van de provider in PEM- of DER-formaat. Alleen vereist bij RSA-algoritmen zoals RS256.

Attributen uit claims

BSN claim Naam van de claim die het BSN van de gebruiker bevat. Standaard: bsn.

LoA claim Naam van de claim met het betrouwbaarheidsniveau (Level of Assurance). Laat leeg als de provider geen LoA levert; de standaardwaarde hieronder wordt dan gebruikt.

Standaard LoA Het betrouwbaarheidsniveau dat wordt toegepast als de identity provider geen LoA-claim meestuurt in het token. Het betrouwbaarheidsniveau bepaalt welke acties een ingelogde gebruiker mag uitvoeren - een hoger niveau vereist een sterkere vorm van authenticatie.

LoA-mapping Vertaaltabel voor LoA-claimwaarden van de provider naar Nederlandse standaardniveaus. Gebruik dit als de provider eigen waarden hanteert.

Eindpunten

Discovery endpoint URL van het discovery-endpoint van de provider. Het pad .well-known/openid-configuration wordt automatisch toegevoegd. Als dit is ingevuld, kunnen de overige eindpunten worden weggelaten - ze worden automatisch afgeleid bij het opslaan van de configuratie.

Note

Als er geen discovery-endpoint beschikbaar is, kunnen de onderstaande velden handmatig worden ingevuld.

JSON Web Key Set endpoint URL van het JWKS-endpoint. Verplicht bij gebruik van het RS256-algoritme.

Authorization endpoint URL van het autorisatie-endpoint van de provider.

Token endpoint URL van het token-endpoint van de provider.

Gebruik Basic auth voor token endpoint Indien ingeschakeld worden client-ID en secret via HTTP Basic auth meegestuurd bij het ophalen van het access token. Standaard worden ze in de request body geplaatst.

User endpoint URL van het userinfo-endpoint van de provider.

Logout endpoint URL van het logout-endpoint van de provider. Optioneel.

Keycloak-specifieke instellingen

Keycloak Identity Provider hint Alleen van toepassing bij Keycloak: geeft aan welke identity provider gebruikt moet worden, zodat het Keycloak-loginscherm wordt overgeslagen. Laat leeg bij andere providers.

Geavanceerde instellingen

Gebruikersinformatie claims afkomstig van Bepaalt vanwaar de gebruikersclaims worden opgehaald: het Userinfo endpoint (standaard) of het ID-token. Kies Userinfo endpoint wanneer de identity provider de claims niet in het ID-token zelf meelevert.

Nonce verificatie Schakelt nonce-verificatie in of uit (standaard ingeschakeld).

Nonce-grootte / State-grootte Lengte van de willekeurige nonce- en state-strings (standaard: 32 tekens).

Signicat (eID Hub, nieuwe stijl)

Signicat is een veelgebruikte identity broker voor DigiD en eHerkenning via OIDC. Onderstaande instellingen zijn de aanbevolen configuratie voor gebruik met Open Inwoner. Deze instructies gaan uit van de eID and Wallet Hub (nieuwe stijl), niet de legacy-omgeving.

  • Log in op https://dashboard.signicat.com/

  • Ga naar de eID and Wallet Hub

  • Klik op Add Client:

    • Client name: een beschrijvende naam, bij voorkeur: {gemeente}-open-inwoner-{acceptatie,productie}

    • Redirect URI: de basis-URL van de deploy, zonder verdere paden, bijvoorbeeld https://open-inwoner-test.maykin.nl

  • Tabblad URIs:

    • Redirect URIs - voeg de volgende drie toe (pas de basis-URL aan):

      • https://open-inwoner-test.maykin.nl/digid-oidc/callback/

      • https://open-inwoner-test.maykin.nl/eherkenning-oidc/callback/

      • https://open-inwoner-test.maykin.nl/eidas-oidc/callback/

    • Post logout Redirect URIs:

      • https://open-inwoner-test.maykin.nl/accounts/login/

    • Front Channel Logout URI:

      • https://open-inwoner-test.maykin.nl/accounts/login/

    • Required Front Channel Logout Session: uitgevinkt

    • Automatic Redirect to Logout URL: aangevinkt

  • Tabblad Secrets:

    • Maak één secret aan met een beschrijvende naam (gebruik bijvoorbeeld de URL van de doelomgeving)

    • Kopieer de client secret naar het daartoe bestemde veld in Open Inwoner

  • Tabblad Access:

    • Allowed scopes: - openid - eherkenning-extra - idp-id - profile

    • Identity provider restrictions: leeg laten

    • ACR values: leeg laten

    • Force use ACR values: leeg laten

  • Tabblad Advanced:

    • Sectie Security:

      • ID Token User data: Minimal

        Note

        Omdat Signicat met deze instelling de claims niet in het ID-token meelevert, moet in Open Inwoner onder Geavanceerde instellingen de optie Gebruikersinformatie claims afkomstig van worden ingesteld op Userinfo endpoint. Dit veld is te vinden in de DigiD- en eHerkenning OIDC-configuratiepagina’s in de beheeromgeving.

      • User Info Response Type: JSON

      • Content encryption algorithm: A128CBC-HS256

      • Allowed CORS Origins: leeg laten

      • Requires Secret: aanvinken; alle overige checkboxes uitvinken

10.5.1. Geschiedenis

Wanneer er wijzigingen aan de OpenID Connect configuratie hebben plaatsgevonden, kunnen deze worden nagetrokken in de geschiedenis rechts bovenin beeld.

10.6. OpenID Connect configuratie voor eHerkenning

Open Inwoner ondersteunt eHerkenning-login voor ondernemers via het OpenID Connect protocol (OIDC). Dit is een alternatief voor de SAML-gebaseerde eHerkenning-koppeling. OIDC staat standaard uitgeschakeld en vereist technische configuratie voordat het in gebruik genomen kan worden.

Let op! Enkel de technisch beheerder dient de OpenID Connect Configuratie te wijzigen.

Activatie

Inschakelen Schakelt eHerkenning-login via OIDC in of uit. Staat standaard uitgeschakeld.

Note

Wanneer ingeschakeld, vervangt de OIDC-koppeling de SAML-gebaseerde eHerkenning-koppeling op de loginpagina. Beide kunnen niet tegelijkertijd actief zijn.

Algemene instellingen

OpenID Connect client ID Het client-ID verstrekt door de OIDC-provider (identity broker).

OpenID Connect secret Het bijbehorende client-secret van de OIDC-provider.

OpenID Connect scopes De scopes die worden aangevraagd bij de identity provider. Standaard: openid, kvk.

Ondertekeningsalgoritme Algoritme waarmee de provider ID-tokens ondertekent. Standaard HS256; gebruik RS256 bij een asymmetrisch sleutelpaar.

Ondertekeningssleutel Openbare sleutel van de provider in PEM- of DER-formaat. Alleen vereist bij RSA-algoritmen zoals RS256.

Attributen uit claims

Identifier type claim Naam van de claim die aangeeft hoe de bedrijfsidentifier geïnterpreteerd moet worden. Verwachte waarden: urn:etoegang:1.9:EntityConcernedID:KvKnr (KVK-nummer) of urn:etoegang:1.9:EntityConcernedID:RSIN. Standaard: namequalifier.

Bedrijfsidentifier claim Naam van de claim met het KVK-nummer of RSIN van het ingelogde bedrijf. Standaard: urn:etoegang:core:LegalSubjectID.

Vestigingsnummer claim Naam van de claim met het vestigingsnummer, indien van toepassing. Standaard: urn:etoegang:1.9:ServiceRestriction:Vestigingsnr.

Vertegenwoordiger claim Naam van de claim met de (pseudonieme) identifier van de gebruiker die namens het bedrijf handelt. Standaard: urn:etoegang:core:ActingSubjectID.

LoA claim Naam van de claim met het betrouwbaarheidsniveau (Level of Assurance). Laat leeg als de provider geen LoA levert; de standaardwaarde hieronder wordt dan gebruikt.

Standaard LoA Het betrouwbaarheidsniveau dat wordt toegepast als de identity provider geen LoA-claim meestuurt in het token. Het betrouwbaarheidsniveau bepaalt welke acties een ingelogde gebruiker mag uitvoeren - een hoger niveau vereist een sterkere vorm van authenticatie.

LoA-mapping Vertaaltabel voor LoA-claimwaarden van de provider naar Nederlandse standaardniveaus. Gebruik dit als de provider eigen waarden hanteert.

Eindpunten

Discovery endpoint URL van het discovery-endpoint van de provider. Het pad .well-known/openid-configuration wordt automatisch toegevoegd. Als dit is ingevuld, kunnen de overige eindpunten worden weggelaten - ze worden automatisch afgeleid bij het opslaan van de configuratie. Als er geen discovery-endpoint beschikbaar is, kunnen de onderstaande velden handmatig worden ingevuld.

JSON Web Key Set endpoint URL van het JWKS-endpoint. Verplicht bij gebruik van het RS256-algoritme.

Authorization endpoint URL van het autorisatie-endpoint van de provider.

Token endpoint URL van het token-endpoint van de provider.

Gebruik Basic auth voor token endpoint Indien ingeschakeld worden client-ID en secret via HTTP Basic auth meegestuurd bij het ophalen van het access token. Standaard worden ze in de request body geplaatst.

User endpoint URL van het userinfo-endpoint van de provider.

Logout endpoint URL van het logout-endpoint van de provider. Optioneel.

Keycloak-specifieke instellingen

Keycloak Identity Provider hint Alleen van toepassing bij Keycloak: geeft aan welke identity provider gebruikt moet worden, zodat het Keycloak-loginscherm wordt overgeslagen. Laat leeg bij andere providers.

Geavanceerde instellingen

Gebruikersinformatie claims afkomstig van Bepaalt vanwaar de gebruikersclaims worden opgehaald: het Userinfo endpoint (standaard) of het ID-token. Zie sectie 10.5 voor een toelichting.

Nonce verificatie Schakelt nonce-verificatie in of uit (standaard ingeschakeld).

Nonce-grootte / State-grootte Lengte van de willekeurige nonce- en state-strings (standaard: 32 tekens).

10.7. OpenID Connect sessie management

Bij gebruik van OpenID Connect (OIDC) voor DigiD en eHerkenning is het belangrijk om rekening te houden met sessie-management. Open Inwoner vernieuwt periodiek de authenticatiesessie om te controleren of de gebruiker nog steeds ingelogd is bij de Identity Provider (IdP).

De omgevingsvariabele OIDC_RENEW_ID_TOKEN_EXPIRY_SECONDS bepaalt hoe vaak de sessie wordt ververst. De standaardwaarde is 15 minuten. Na deze periode wordt de gebruiker automatisch en onzichtbaar doorgestuurd naar de IdP:

  • Als de IdP-sessie nog actief is: De gebruiker wordt automatisch teruggestuurd naar Open Inwoner en kan ongestoord doorwerken. Dit gebeurt op de achtergrond zonder dat de gebruiker het merkt.

  • Als de IdP-sessie verlopen is: De gebruiker wordt uitgelogd en krijgt een foutmelding te zien:

    • DigiD: “Uw DigiD-sessie is verlopen. Log alstublieft opnieuw in.”

    • eHerkenning: “Uw eHerkenning-sessie is verlopen. Log alstublieft opnieuw in.”

Important

Stel de sessieduur bij uw Identity Provider (DigiD/eHerkenning) in op minimaal de duur van één vernieuwingsinterval langer dan OIDC_RENEW_ID_TOKEN_EXPIRY_SECONDS. Bij voorkeur zelfs aanzienlijk langer om te voorkomen dat gebruikers onverwacht worden uitgelogd tijdens het werken. Houd hierbij rekening met de eisen en aanbevelingen van Logius en uw identity broker (bijvoorbeeld Signicat).

Bijvoorbeeld:

  • Als OIDC_RENEW_ID_TOKEN_EXPIRY_SECONDS is ingesteld op 10 minuten (600 seconden)

  • Stel de IdP-sessieduur in op minimaal 21 minuten of langer, zodat de gebruiker tot tweemaal toe de sessie kan laten vernieuwen.

Als de IdP-sessieduur korter is dan het vernieuwingsinterval, kunnen gebruikers onverwacht worden uitgelogd. Let ook op dat een korter vernieuwingsinterval betekent dat er vaker een redirect plaatsvindt naar de IdP. Hierdoor is de kans groter dat een redirect gebeurt tijdens het versturen van een formulier (POST-verzoek), wat kan leiden tot verlies van ingevulde gegevens.