Skip to content

eHerkenning connector (DV-HM interface 1.13, with 1.11)

This page describes what the HelixIAM eHerkenning connector implements and how an administrator sets it up in the console. It is built against Afsprakenstelsel eToegang AS1.24e, DV-HM interface KV1.13. It has not yet been run against a broker. Partner chain tests (a test login through a recognised broker's pre-production) are still to come, and until they pass the feature stays Beta. Nothing here says the connector is certified or approved by anyone.

Operating settings (metadata refresh, certificate status checks, egress), the reason code list and the known limits are in eID operations. DigiD and eIDAS are in DigiD and eIDAS.

Which version to choose

Version Use it when Notes
1.13 (default for new connections) Your broker offers it. The broker always answers over the Artifact binding. Keys are made by HelixIAM in the realm's key store.
1.11 Your broker has not moved to 1.13 yet. Use it only until it has. A row with no version counts as 1.11. It needs the broker's metadata imported like every other row; without it the row fails to build (see eID operations).

Both versions need the broker's metadata imported (below). There is no path that logs in with only pasted certificates. The console control is Interface version on the connection page.

Set it up in the console

The console is in English only. Sign-in pages shown to your users stay in Dutch (and are themeable per realm).

  1. Open Federation & eIDs, Identity providers, add a provider and choose an eHerkenning route (a broker preset fills what is the same for every customer). Save the connection switched off until step 6.
  2. Your identity: your OIN (20 digits) and the entity index (0 to 8999 production, 9000 to 9999 test). The console shows the entity ID that follows.
  3. Broker (makelaar): your broker's HerkenningsmakelaarId (ask your broker for it; it is needed for the service catalog draft). The response binding is fixed to Artifact on 1.13.
  4. Keys: HelixIAM makes your signing and encryption keys in the realm's key store (activate one of each in the keys section). Key backends and rollover are in key custody.
  5. Services: add the services (and their levels of assurance) that you will offer, and the minimum level of assurance of requests. Mark a service as one that may receive the BSN only if your organisation is entitled to it, and fill in the BSNk key versions (see BSNk).
  6. Import broker metadata (from a URL or a file). HelixIAM checks the signature against the PKIoverheid certificates it ships, the version, validity and the Artifact Resolution server (see eID operations). On the first import for a connection the console asks you to confirm who signed the metadata (the signer's subject or OIN, as your broker told you). Only that signer is accepted from then on. Then enable the connection.
  7. Downloads: download the DV metadata and the service catalog draft and send them to your broker.

What to send to the broker

  • The DV metadata, or its URL: https://<host>/realms/<realm>/broker/<alias>/etoegang/metadata (the public route works when the connection is enabled; the console download also works while it is switched off).
  • The service catalog draft (console download). Your broker checks it and adds it to the catalogue. The scheme page on the catalog's XML schema says the schema "is currently not correct", so the exact form your broker wants is an open question to ask it.
  • Your OIN, and the PKIoverheid certificates for pre-production and production.
  • Your SP signing and encryption certificates (they are inside the DV metadata; their KeyName is the SHA-1 of the certificate in lower-case hex). During a key rollover both the old and the new certificate are published, so the broker can move over.

Switches for broker-specific behaviour

Some behaviour is not settled by the public specification. These are per-connection switches with the safer default. Change one only after your broker has told you what it does (console: Broker-specific switches):

  • Send WS-Addressing headers with the SOAP ArtifactResolve (wsAddressing; off by default).
  • ArtifactResponse issuer: the broker's entity ID (usual) or your own (artifactResponseIssuer).
  • Binding of the sign-in request (authnRequestBinding): POST or Redirect.
  • Broker's TLS certificates: only when the broker's TLS client certificate is not its signing certificate.

Three open questions are not switches but need an answer from your broker before go-live: which block cipher it encrypts with, whether it ever calls your own Artifact Resolution endpoint, and which test PKIoverheid certificates its pre-production accepts.

Logout

HelixIAM cannot send a logout over Artifact, so there is no logout at the broker: users stay signed in there. If your broker has a sign-out URL, enter it under the manual fields.

Time tolerance (clock skew)

The scheme pages name no clock skew. HelixIAM accepts a tolerance of 60 seconds on assertion validity times (NotBefore, NotOnOrAfter, and the subject confirmation). Keep your nodes' clocks in sync.

Changes you must report to the broker

The scheme's terms for service providers (GVDV art. 18) say that changes to the legal entity, the levels of assurance, the service scope, the DV-HM interface (for example moving from 1.11 to 1.13), the data requested and the technical contact must be reported to the broker (HM). HelixIAM cannot do this for you; plan it as part of any change to the connection.

Representation, BSN and PseudoID

  • Ordinary (non-eHerkenning) connections drop RSIN and 1-in-11 KvK values in their mappers, and the audit log records it. A customer who mapped rsin on a generic connection loses it, visibly in the audit log; use an eHerkenning connection for these identifiers.
  • An identifier typed as a BSN is protected like a DigiD BSN (hash as link key, encrypted at rest, released only to applications that a realm admin allowed with a legal basis). A PseudoID goes through BSNk (next section).
  • Your application must itself enforce the service restrictions that HelixIAM returns (eh_service_restrictions). Only a client that has been granted the eid scope receives them, with the KvK number, the acting subject and the service data. An administrator adds eid to the client (console, client scopes, or the admin API); dynamic client registration refuses it. A second application in the same SSO session that has no eid gets an ordinary token with the account's roles and nothing that says a restriction (such as a Vestigingsnr) applies, so it must not be trusted to treat the person as restricted: give the applications where a restriction matters eid, and keep the others to people for whom it does not.
  • What an eID session cannot do. Both company and chain sign-ins get 403 on /account, /admin, /authenticator, /mfa, /required-actions, /webauthn/register, /device/enroll/start and /tx. A company user keeps roles and SSO between clients. A chain (an intermediary) serves one client with the eid scope, with no roles, and a second client needs a new sign-in. Where the realm asks for a second factor, a sign-in below EH3 is refused with the message that its level is too low; there is no second-factor page for it.
  • Link keys: the link key of a KvK or other non-BSN identity carries its type (kvknr:<number>). Links stored by an older release are not re-keyed; see the breaking changes for what to do per user.
  • A stored eHerkenning bare-BSN link stays in its raw form until the user's first sign-in, when it is re-keyed.

BSN and PseudoID

BSN or PseudoID in an assertion is encrypted by BSNk. For a service that may receive it you import the key files you obtained through your broker (the entitlement form to RvIG and the key delivery are the customer's to arrange; HelixIAM cannot request them). The endpoint is POST /admin/realms/{realm}/identity-providers/{alias}/bsnk/keys (multipart, field file), realm-admin only, audited without key content; GET lists key metadata, DELETE .../bsnk/keys/{keyId} removes one. Types accepted: EI Decryption, EP Decryption, EP Closing. EP migration source/target and DRKi are stored but unused. No real key file from Logius or a broker has been seen yet: the formats follow the published specification. After a BSNk key rotation a PseudoID is a new pseudonym, so the user gets a new link (use relink, below).

Unsupported

  • BSNk migration keys and DRKi (stored, not used).
  • Signature checks on the Advice element.
  • AD preselection.
  • Logout at the broker over Artifact.
  • A broker whose metadata is signed outside PKIoverheid works only with the PKIoverheid checks switched off (none), which is for tests.

API

Under /admin/realms/{realm}/identity-providers (CSRF header on writes, as for every admin write):

Method and path Purpose
POST /etoegang/hm-metadata/preview Check a broker document without storing it.
POST /{alias}/etoegang/hm-metadata Import it. Body: url or xml, and confirmSigner at the first import.
GET /{alias}/etoegang/service-catalog The service catalog draft (XML). KV1.13 only.
GET /{alias}/etoegang/metadata The signed DV metadata, also while the connection is switched off.
GET /{alias}/eid/metadata The SP metadata summary of an eID connection.
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"

Refusals are 400 {message, fieldErrors}; a response with warnings still imported.