eHerkenning (NL Business eID)¶
Sign in Dutch businesses and their employees with eHerkenning — the national business eID. The connector is included; connecting to production is arranged through the scheme (see below).
What it is¶
eHerkenning is the Netherlands' standardised business electronic identity, used by organisations and their authorised representatives to access services securely. With HelixIAM the eHerkenning connector is built in: you add it from the identity-provider wizard, and the realm can authenticate business users with their eHerkenning identity, provisioning the user just-in-time and mapping it into your realm.
Out-of-the-box business-eID coverage is one of HelixIAM's flagship differentiators — capability you would otherwise have to build and maintain yourself.
eHerkenning is an identity provider with protocol: "eherkenning". It builds on the SAML 2.0 SP profile (signed AuthnRequest, encrypted assertion) and asserts the organisation and its acting representative. Optional representation (mandate) support lets a request ask for a mandated serviceId and read the acting subject from the assertion.
BSN-typed identifiers
A KvK number or an RSIN is a public register number and is used as the link key as is. An identifier typed as a
BSN (EntityConcernedID:BSN, e.g. a sole trader) gets the same protection as a DigiD BSN: link keyed on its hash,
stored encrypted, never the username, released only to opted-in applications — see
DigiD: how the BSN is handled.
Watch: add an eHerkenning connection¶
In the console¶
- Open Identity providers (under Federation & eIDs), click Add identity provider and choose eHerkenning.
- Under Your identity, enter your OIN (20 digits) and Entity index (0 to 8999 for production, 9000 to 9999 for a test connection), and choose the Minimum level of assurance. The SP entity ID follows from these:
urn:etoegang:DV:<OIN>:entities:<index>. Add mappers for the organisation / representative identifiers if you need them, and create the connection. It starts switched off. - Open the connection's eID & assurance tab. There you import your broker's metadata (Import broker metadata, from a URL or a file, and Confirm who signed this metadata on the first import), activate the signing and encryption keys HelixIAM made in the realm's key store, add your Services with their levels of assurance, and download the DV metadata and service catalog draft under Downloads for your broker.
- Switch the connection on once your broker's details and your services are in. It then appears as an eHerkenning sign-in option.
The step-by-step setup, the Interface version (1.13 or 1.11) and the Broker-specific switches are in eHerkenning connector, KV1.13.
Operational note — production accreditation
The eHerkenning connector is built in and configurable now. Connecting to production is a formal scheme process: admission and accreditation are arranged through the Afsprakenstelsel eToegang scheme. Plan that accreditation track separately from the technical configuration, which you can complete immediately.
Over the API¶
eHerkenning is created like any identity provider, with protocol: "eherkenning". The examples below assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.
Create an eHerkenning connector¶
The console creates a connection from the OIN and entity index on the KV1.13 defaults. The broker's endpoints and certificates are not sent here: they come from the broker's metadata, imported afterwards. The SP keys are made in the realm's key store.
# Refresh CSRF after any GET, then POST (see the auth guide for the helper)
curl -s -b cookies.txt -c cookies.txt "$HELIX_URL/admin/realms/$REALM/identity-providers" >/dev/null
CSRF=$(awk '($6=="__Host-XSRF-TOKEN"||$6=="XSRF-TOKEN")&&$7~/^r1\./{t=$7} END{print t}' cookies.txt)
curl -s -b cookies.txt \
-H "Content-Type: application/json" \
-H "X-XSRF-TOKEN: $CSRF" \
-d '{
"alias": "eherkenning",
"protocol": "eherkenning",
"displayName": "eHerkenning",
"enabled": false,
"config": {
"scheme": "eherkenning",
"etoegangVersion": "1.13",
"oin": "00000001234567890000",
"entityIndex": "9001",
"spEntityId": "urn:etoegang:DV:00000001234567890000:entities:9001",
"minimumLoa": "loa3",
"binding": "post",
"responseBinding": "artifact"
}
}' \
"$HELIX_URL/admin/realms/$REALM/identity-providers"
Then import the broker's metadata (the first import also needs confirmSigner):
curl -s -b cookies.txt -H "X-XSRF-TOKEN: $CSRF" -H "Content-Type: application/json" \
-d '{"url":"https://broker.example/metadata"}' \
"$HELIX_URL/admin/realms/$REALM/identity-providers/eherkenning/etoegang/hm-metadata"
Config keys
oin, entityIndex, spEntityId, etoegangVersion (1.13 or 1.11), minimumLoa (loa2, loa2plus, loa3, loa4, or the urn:etoegang:core:assurance-class:* URN of the same name; EH2+ ranks above EH2 and below EH3; an unknown value is refused with 400), and authnRequestBinding / responseBinding (Artifact on 1.13). The broker's idpEntityId, ssoUrl and signing certificates are set by the metadata import. Representation (mandate) is opt-in; its exact attribute identifiers are supplied from your eHerkenning onboarding.
Full endpoint set¶
Method & path (under /admin/realms/{realm}) |
Purpose |
|---|---|
GET /identity-providers · POST /identity-providers |
List / create providers |
GET · PUT · DELETE /identity-providers/{alias} |
Read / update / delete a provider |
POST /identity-providers/{alias}/etoegang/hm-metadata |
Import the broker's metadata |
GET /identity-providers/{alias}/etoegang/metadata · GET /identity-providers/{alias}/etoegang/service-catalog |
Download the DV metadata / service catalog draft |
See Identity providers for the shared flow, and the API reference for every field.
See also¶
- Identity providers — broker model, JIT provisioning, SLO
- DigiD (NL citizen) · eIDAS (EU cross-border)
- SAML broker — the underlying SAML 2.0 profile
- Users & credentials · Authentication flows