Skip to content

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.

In the console

  1. Open Federation & eIDs → Identity providers and click Add identity provider.
  2. Choose eHerkenning. This applies facilitated defaults for the scheme, so you supply only your environment-specific details.
  3. Supply your environment-specific trust material and service details.
  4. Configure mappers for the organisation / representative identifiers and any attributes you consume, for example a role for representatives of one service.
  5. Save; the provider loads at runtime and appears as an eHerkenning sign-in option.

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

# 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": true,
        "config": {
          "ssoUrl": "https://eherkenning.example/sso",
          "idpEntityId": "urn:etoegang:HM:00000000000000000000:entities:0000",
          "spEntityId": "urn:etoegang:DV:00000000000000000000:entities:0001",
          "assertionConsumerServiceUrl": "https://auth.example.com/realms/acme/broker/eherkenning/callback",
          "idpSigningCertificate": "-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----",
          "spDecryptionPrivateKey": "-----BEGIN PRIVATE KEY-----\n…\n-----END PRIVATE KEY-----",
          "spSigningPrivateKey": "-----BEGIN PRIVATE KEY-----\n…\n-----END PRIVATE KEY-----",
          "spSigningCertificate": "-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----",
          "minimumLoa": "urn:etoegang:core:assurance-class:loa3",
          "subjectAttribute": "urn:etoegang:core:LegalSubjectID"
        }
      }' \
  "$HELIX_URL/admin/realms/$REALM/identity-providers"

{
  "realmId": "acme",
  "alias": "eherkenning",
  "protocol": "eherkenning",
  "displayName": "eHerkenning",
  "enabled": true,
  "config": {
    "ssoUrl": "https://eherkenning.example/sso",
    "idpEntityId": "urn:etoegang:HM:00000000000000000000:entities:0000",
    "spEntityId": "urn:etoegang:DV:00000000000000000000:entities:0001",
    "assertionConsumerServiceUrl": "https://auth.example.com/realms/acme/broker/eherkenning/callback",
    "minimumLoa": "urn:etoegang:core:assurance-class:loa3",
    "subjectAttribute": "urn:etoegang:core:LegalSubjectID",
    "spDecryptionPrivateKeySet": true,
    "spSigningPrivateKeySet": true
  }
}

The SP private keys are write-only: the response reports spDecryptionPrivateKeySet / spSigningPrivateKeySet instead of the keys — see secrets are write-only.

Config keys

SAML-SP endpoints (ssoUrl, idpEntityId, spEntityId, assertionConsumerServiceUrl, idpSigningCertificate) plus the eID material: spDecryptionPrivateKey, spSigningPrivateKey, spSigningCertificate, 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), subjectAttribute (the entity-concerned/legal-subject id), and authnRequestBinding / responseBinding. 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

See Identity providers for the shared flow, and the API reference for every field.

See also