# DigiD and eIDAS connectors

What the HelixIAM DigiD and eIDAS connectors implement, and how an administrator configures them in the console. **Neither has been run
against Logius, a broker or an eIDAS node yet.** Partner chain tests are still to come; until they pass, both stay **Beta**. Nothing
on this page says either connector is certified or approved by Logius, the Dutch government or the EU.

Operating settings, reason codes and known limits are in [eID operations](eid-operations.md). eHerkenning is in
[eHerkenning](eherkenning-kv113.md). What the customer must arrange with each party (eligibility, OIN, PKIoverheid certificates, the
assessment) is in the Dutch [onboarding guide](../operations/municipality-hosting.md).

The console is English only. The sign-in pages your users see stay in Dutch.

## Routes

The console offers a route picker (`GET /admin/realms/{realm}/eid/presets` lists them). A route fills in what is the same for every
customer; you add your own account details.

| Route | Connection type | You add |
|---|---|---|
| DigiD, classic SAML v3.5 (Logius) | `digid`, interface **classic** | SSO URL, Artifact Resolution URL, IdP entity ID, IdP signing certificate, minimum level |
| DigiD, CombiConnect (Logius) | `digid`, interface **combiconnect** | SSO and Artifact Resolution URLs, OIN, entity index, ServiceUUID, test connection flag, IdP certificate, minimum level |
| DigiD via an OpenID Connect hub (Signicat) | `oidc` | issuer and endpoints, client ID and secret |
| DigiD via an identity broker (OneWelcome) | generic | what the broker publishes for the BSN claim (not published, so ask) |
| eIDAS via an OpenID Connect hub | generic | ask the hub for its parameters; they are not published |

The console control **Interface** (classic or combiconnect) sits under **Your connection** on a DigiD connection. A stored value
that is neither fails to build the connection.

## DigiD

1. **Federation & eIDs, Identity providers**, add a provider, choose the DigiD route. Save it switched off.
2. **Details from Logius or your broker:** URLs and certificate as Logius sent them after approval.
3. **Level and sector:** the minimum level of assurance (Basis, Midden, Substantieel, Hoog) and the sector code. The level is requested and enforced on the response, and **the minimum level is required**: a DigiD row without it fails to build. Leave `subjectAttribute` empty: DigiD's subject is the sector number, and a row with it set refuses every login.
   **Your reason for the BSN (required to enable):** under **BSNk and entitlement** choose the category (`publicBody` or `otherThirdParty`) and write the legal basis, at least 10 characters
   (`bsnEntitlementCategory`, `bsnLegalBasis`). The server refuses to save or import an enabled DigiD connection without both, and also asks for the ACS URL and the service provider entity ID.
   Do this before step 7, or enabling meets the refusal. Applications get the BSN only by their own release policy.
4. **Your keys:** the signing key (it is also the client identity for the Artifact Resolution call over mutual TLS) and the decryption key. Use the keys section; the certificate is the PKIoverheid
   certificate you applied for. Key backends and rollover are in [key custody](../operations/key-custody.md).
5. **Downloads:** download the SP metadata and send it to Logius.
6. **CombiConnect only:** import the RD metadata (`Read them from the RD metadata`): from a URL, a file or pasted text. The console first checks it (**Check**), then **Import**; HelixIAM verifies the
   signature against the PKIoverheid certificates it ships and asks you to confirm the signer once.
   The importer also reads the document's `validUntil` (see the warning below). Machtigen (representation) is a switch on CombiConnect only.
7. Enable the connection.

**A combiconnect document with a `validUntil` ends the connection by itself.** With the metadata refresh off (the default) logins stop on that
date, and the next 24-hour check disables the row as `EXPIRED`. The console warns from 14 days before. Import the new document and enable the connection again,
or turn the refresh on ([eID operations](eid-operations.md#automatic-refresh-of-broker-metadata)).

The BSN is handled as described in the BSN handling described on the [DigiD page](digid.md). BSNk-encrypted identifiers
(`EncryptedIdentity` and `EncryptedPseudonym`) are decrypted with keys you import with `POST /admin/realms/{realm}/identity-providers/{alias}/bsnk/keys`.
Examples in tests use only the fictitious BSNs 999999990 and 123456782.

**Applications and the `eid` scope.** A client receives the eID identity claims of a sign-in (DigiD: acting subject and service; eIDAS: person identifier, names, birth date) only if an administrator granted it
the `eid` scope. Dynamic client registration refuses the scope. DigiD Machtigen (representation) sessions serve one client with `eid`, give tokens no roles, and are closed to `/account`, `/admin`, `/mfa` and `/authenticator`;
an application without `eid` refuses every representative. Where the realm asks for a second factor, a DigiD sign-in below Substantieel is refused (`eidLevelTooLow`).

### Federated logout on the CombiConnect route

A connection with `digidSsoFederation=true` and the RD's HTTP-POST `singleLogoutServiceUrl` ends the RD session after the local one. The signed
LogoutResponse returns to `/realms/{realm}/broker/{alias}/gdi/slo`. An RD-initiated LogoutRequest is refused (the specification does not support it).
The local session always ends, whatever the RD answers. There is no audit entry for a session that times out.

## eIDAS

1. Add a provider, choose the eIDAS route. Save it switched off.
2. **Is this for a Dutch service?** Pick public or private (`spType`). **It is required to enable the connection.** An older connection needs the choice at its next save while enabled; see the [breaking changes](../operations/upgrades.md#eid-connectors). It only goes to the node as `eidas:SPType`; HelixIAM matches accounts the same for both.
3. **Your service** and **Level of assurance:** `low`, `substantial` or `high` (eIDAS URIs).
4. **The eIDAS node:** import the node's metadata (URL or file). `POST /admin/realms/{realm}/identity-providers/{alias}/eidas/node-metadata` with `url` or `xml`, and `confirmSigner` (the fingerprint
   your node's operator gave you). An unsigned document is never stored. The signer's certificate is pinned and only the leaf is pinned; a node that rotates it
   under the same root is confirmed anew. A node that signs with only the unsigned form cannot be enabled.
5. **Your keys:** eIDAS requires separate signing and decryption keys. Signing is RSASSA-PSS; RSA keys are 3072 bits. Of EC curves HelixIAM accepts six (stricter than the specification asks).
   A response signed with another algorithm (such as RSA-SHA256), or an assertion that is not encrypted, is refused. A stand-in node that sends clear assertions needs the connection's
   `allowCleartextAssertion`, which is for tests only. The algorithm check has no switch, so a test node that signs with RSA-SHA256 cannot log in.
6. **Your metadata:** `GET /realms/{realm}/broker/{alias}/eidas/metadata` (also in the console) goes to the node operator.

Account matching is on the PersonIdentifier (the LegalPersonIdentifier for an organisation), unless `subjectAttribute` names another attribute. A response must carry the mandatory
attributes (PersonIdentifier, family name, given name, date of birth; for an organisation LegalPersonIdentifier and legal name). A numeric NameID equal to someone's
BSN can join their key, about 1 in 10^9 per pair; this is accepted.

## Relinking users

A link blocked by the re-keying of an old NameID gets its key back with
`POST /admin/realms/{realm}/users/{userId}/federated-identities/{alias}/relink` with `{"externalSubject":"..."}`. Realm-admin only; `204` on success, `404` no such blocked
link, `409` `linkHeldByAnotherUser` (an administrator removes the other link first). Audited as `FEDERATED_LINK_RELINKED`.
An erasure request (the user's GDPR right) deletes **all** of the user's federated links; the next single sign-on sign-in makes a new account.
