# 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](eid-operations.md). DigiD and eIDAS are in [DigiD and eIDAS](digid-eidas-setup.md).

## 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](eid-operations.md)). |

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](../operations/key-custody.md).
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](#bsn-and-pseudoid)).
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](eid-operations.md)). 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](../operations/upgrades.md#eid-connectors) 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. |

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