eID operations: metadata refresh, certificate status, egress, reason codes, limits¶
For whoever runs a HelixIAM installation with DigiD (classic or CombiConnect), eHerkenning (KV1.13 and KV1.11) or eIDAS. Setup in the console is in eHerkenning and DigiD and eIDAS. These connectors have not yet been run against Logius, a broker or an eIDAS node; partner chain tests are still to come. Upgrading an existing installation: see the breaking changes.
Automatic refresh of broker metadata¶
| Property | helix.eid.metadata-refresh-interval |
| Environment | HELIX_EID_METADATA_REFRESH_INTERVAL |
| Helm value | config.eidMetadataRefreshInterval |
| Default | off (unset, empty or zero) |
| Format | ISO-8601 duration, for example PT6H |
Off means HelixIAM never fetches an eHerkenning or CombiConnect DigiD document by itself. With it off, logins through a broker
fail after the broker renews its certificates, until an administrator imports its metadata again. On eHerkenning a renewed
Artifact Resolution certificate shows up as EH_ARS_TLS_UNTRUSTED in the log. A CombiConnect DigiD document with a validUntil
also stops working on that date (see DigiD and eIDAS). The server says once at startup, at INFO, when a row has a metadata
URL and the refresh is off; the console shows the state of each connection read-only.
To turn it on, set the value, for example in the chart:
or HELIX_EID_METADATA_REFRESH_INTERVAL=PT6H. A negative or unreadable value stops the server at startup with a message naming the setting; 6h is
refused (ISO-8601 only), 0 means off. The job looks every five minutes, so a shorter interval acts as five minutes. A document's shorter
cacheDuration shortens the wait, to five minutes at the least, and never turns the refresh on.
What it does: fetches the URL a document was imported from, https only, through the egress guard, and adopts the new document only if it passes every check of an import.
eHerkenning needs an enabled row and the PKIoverheid checks in force. It writes only the document; the connection's other settings stay. A
refused document (another signer, say, or an older signed one with an older leaf) keeps the stored one, disables nothing, shows in the console and sets rdRefreshRefused and the audit event
IDP_HM_METADATA_REFRESH_REFUSED (DigiD: IDP_RD_METADATA_REFRESH_REFUSED).
A URL is kept while the refresh is off, so a row imported from a URL starts refreshing as soon as an interval is set. A document imported as text has no URL and is yours to renew.
After a failed login, with an interval set: a login that meets EH_ARS_TLS_UNTRUSTED or EH_ARS_TLS_REVOKED asks the document's URL once in the
background, at most once per connection per five minutes on each replica. That login is not retried, so the first login after a renewal can still fail.
The 24-hour check¶
helix.eid.hm-revalidation-interval (HELIX_EID_HM_REVALIDATION_INTERVAL; in the chart through config.extraEnv) defaults to PT24H; zero is off. A negative value stops the
server at startup. This check fetches no document. With the PKIoverheid checks in force it asks the OCSP and CRL URLs of the certificates of each stored document; a connection whose document has expired is disabled as EXPIRED. For no timed outbound traffic from these checks set both settings to zero; a revoked certificate is
then noticed only at the next registry build (a restart, an import, a change to a connection). Audit: IDP_HM_METADATA_MISSING once per enabled eHerkenning row that has no imported document.
Certificate status of the Artifact Resolution server¶
| Property | helix.eid.pkio-revocation |
| Environment | HELIX_EID_PKIO_REVOCATION |
| Helm value | config.eidPkioRevocation |
| Values | empty or hard-fail (default), soft-fail. Any other value, from any source, stops the server at startup. |
At every login over the Artifact binding, the certificate of the broker's (or Logius's) Artifact Resolution server has its revocation status asked at the TLS handshake.
- A known revocation always refuses, under both values: one ERROR, the audit event
IDP_ARS_TLS_REVOKED, andEH_ARS_TLS_REVOKEDorDIGID_ARS_TLS_REVOKEDas reason. - Under
hard-fail, a status that cannot be determined passes only if that exact certificate had a definite good answer within the last 7 days. The 7 days run from the last time a valid answer was read, cached or not, so up to about 8 days after the CA actually answered. Otherwise the login is refused withEH_ARS_TLS_STATUS_UNKNOWNorDIGID_ARS_TLS_STATUS_UNKNOWN. soft-faillets it pass with a WARN, and logs one WARN at startup. Do not use it in production.- The remembered good answers are in memory, per replica. A restart or an upgrade empties them, so during an outage of the CA a stale list refuses logins at once on that replica.
- A login asks OCSP and CRL for up to three seconds (one for OCSP). Without an answer the certificate is not asked again for 45 seconds when the login goes on, or 5 seconds while logins are refused.
These lookups have their own limit,
helix.outbound.fetch.pkio-revocation.max-concurrent(default 32).
What an egress list must contain¶
The chart opens outbound port 80 to public addresses by default (networkPolicy.allowRevocationEgress, default true), because CRLs and OCSP are usually plain http.
If you narrow egress yourself (allowRevocationEgress=false and your own NetworkPolicy) the list must cover:
- outbound 443 to the broker's (or Logius's) metadata URL and to its Artifact Resolution server (a login needs it);
- outbound 80 to the CRL and OCSP hosts named by the certificates of every stored broker document, and by the PKIoverheid chain;
- and the CRL and OCSP hosts of the Artifact Resolution server's own certificate chain, not only those of the documents. A host missing from the list refuses every login through that server under
hard-fail.
Keep the list up to date yourself: hosts differ per provider, and a CRL host can be a name whose address changes. An internal CA's responder
goes in networkPolicy.revocationEgressExtraCidrs. HelixIAM has no setting for an HTTP egress proxy on these fetches.
Reason codes¶
Reason codes are written to the server log (and, where noted, audited); the pages users see do not show them. Every code below exists in the product source. Console messages for the metadata import codes are explained in the console itself.
| Group | Codes |
|---|---|
| Artifact Resolution server certificate | EH_ARS_TLS_UNTRUSTED, EH_ARS_TLS_REVOKED, EH_ARS_TLS_STATUS_UNKNOWN, DIGID_ARS_TLS_REVOKED, DIGID_ARS_TLS_STATUS_UNKNOWN |
| DigiD response | DIGID_AUTHN_FAILED, DIGID_DENIED, DIGID_USER_CANCELLED, DIGID_STATUS_NOT_SUCCESS, DIGID_STATUS_UNAUTHENTICATED, DIGID_LOA_BELOW_MINIMUM, DIGID_LOA_NOT_REACHED, DIGID_NUMBER_INVALID, DIGID_SECTOR_UNEXPECTED, DIGID_SETTINGS_MISSING, DIGID_ARTIFACT_RESPONSE_EMPTY, DIGID_SUBJECT_ATTRIBUTE_UNSUPPORTED |
| CombiConnect (GDI) response | GDI_AMBIGUOUS_SUBJECT, GDI_ARTIFACT_ENDPOINT_UNKNOWN, GDI_ARTIFACT_MALFORMED, GDI_ARTIFACT_REQUIRED, GDI_ARTIFACT_SOURCE, GDI_ASSERTION_COUNT, GDI_ASSERTION_UNSIGNED, GDI_ATTRIBUTE_ENCRYPTED, GDI_ATTRIBUTE_STATEMENT_COUNT, GDI_ATTRIBUTE_WITHOUT_VALUE, GDI_AUTHN_STATEMENT_COUNT, GDI_CONDITIONS_INCOMPLETE, GDI_ENCRYPTED_ASSERTION, GDI_IDENTIFIER_FORMAT, GDI_IDENTIFIER_TYPE, GDI_LEGACY_BSN_INVALID, GDI_LOA_UNKNOWN, GDI_NAMEID_FORMAT, GDI_NAMEID_SP_QUALIFIED, GDI_NO_ACTING_SUBJECT, GDI_RD_CERTIFICATE_EXPIRED, GDI_RD_METADATA_EXPIRED, GDI_RD_METADATA_UNVERIFIED, GDI_REPRESENTATION_WITHOUT_LEGAL_SUBJECT, GDI_REQUEST_ID_MISSING, GDI_RESPONSE_DESTINATION, GDI_RESPONSE_IN_RESPONSE_TO, GDI_RESPONSE_ISSUER, GDI_SERVICE_UUID_MISMATCH, GDI_SERVICE_UUID_MISSING, GDI_SETTINGS_MISSING, GDI_SIGNATURE_ALGORITHM, GDI_SIGNATURE_INVALID, GDI_SUBJECT_NOT_FOR_US, GDI_SUBJECT_NOT_TRANSIENT |
| CombiConnect logout | GDI_SLO_DESTINATION, GDI_SLO_IN_RESPONSE_TO, GDI_SLO_ISSUE_INSTANT, GDI_SLO_ISSUER, GDI_SLO_MALFORMED, GDI_SLO_NOT_PROCESSED, GDI_SLO_NOT_SSO, GDI_SLO_REQUEST_UNSUPPORTED, GDI_SLO_STATUS_MISSING, GDI_SLO_STATUS_NOT_SUCCESS, GDI_SLO_UNSIGNED; audit reasons SLO_COMPLETED, SLO_NOT_CONFIRMED, SLO_RESPONSE_REFUSED, SLO_SKIPPED |
| eIDAS response | EIDAS_ASSERTION_COUNT, EIDAS_ASSERTION_NOT_ENCRYPTED, EIDAS_ATTRIBUTE_EMPTY, EIDAS_ATTRIBUTE_NAME_FORMAT, EIDAS_DATE_OF_BIRTH_FORMAT, EIDAS_DESTINATION, EIDAS_ENCRYPTED_ASSERTION_CONTENT, EIDAS_ENCRYPTED_ATTRIBUTE, EIDAS_IN_RESPONSE_TO, EIDAS_LEGAL_PERSON_IDENTIFIER_DESTINATION, EIDAS_LEGAL_PERSON_IDENTIFIER_FORMAT, EIDAS_LOA_NOT_ACCEPTED, EIDAS_MANDATORY_ATTRIBUTE_MISSING, EIDAS_NAMEID_MISSING, EIDAS_PERSON_IDENTIFIER_DESTINATION, EIDAS_PERSON_IDENTIFIER_FORMAT, EIDAS_RESPONSE_ISSUER, EIDAS_RESPONSE_UNSIGNED, EIDAS_SIGNATURE_ALGORITHM, EIDAS_SIGNING_CERTIFICATE_CURVE, EIDAS_SIGNING_CERTIFICATE_KEY_SIZE, EIDAS_LINK_REKEYED, EIDAS_BSN_KEPT, EIDAS_BSN_REMOVED |
| eIDAS node metadata import (shown in the console) | EIDAS_NODE_FETCH, EIDAS_NODE_INPUT, EIDAS_NODE_XML, EIDAS_NODE_TOO_LARGE, EIDAS_NODE_ROLE, EIDAS_NODE_WANT_AUTHN_REQUESTS_SIGNED, EIDAS_NODE_VALID_UNTIL, EIDAS_NODE_EXPIRED, EIDAS_NODE_ENTITY_ID, EIDAS_NODE_ENTITY_ID_URL, EIDAS_NODE_PIN_EXPIRED, EIDAS_NODE_UNSIGNED, EIDAS_NODE_SIGNATURE, EIDAS_NODE_SIGNATURE_ALGORITHM, EIDAS_NODE_SIGNING_CERTIFICATE, EIDAS_NODE_SSO, EIDAS_NODE_SIGNER_CONFIRMATION, EIDAS_NODE_SIGNER_UNCONFIRMED, EIDAS_NODE_SIGNER_NOT_IN_DOCUMENT, EIDAS_NODE_SIGNER_EXPIRED; warnings EIDAS_NODE_SIGNER_NOT_PINNED, EIDAS_NODE_ALGORITHMS, EIDAS_NODE_SIGNING_METHODS, EIDAS_NODE_DIGEST_METHODS |
| BSNk | BSNK_BAD_PADDING, BSNK_BAD_STRUCTURE, BSNK_BSN_INVALID, BSNK_DECRYPT_FAILED, BSNK_KEY_MISMATCH, BSNK_KEY_MISSING, BSNK_KEY_NOT_ALLOWED_HIGH, BSNK_KEY_UNAVAILABLE, BSNK_KEY_UNREADABLE, BSNK_KEY_VERSION_MISMATCH, BSNK_NOT_A_BSN, BSNK_NOT_AVAILABLE, BSNK_RECIPIENT_MISMATCH, BSNK_SCHEME_KEY_CHANGED, BSNK_SCHEME_KEY_INVALID, BSNK_SCHEME_KEY_MISSING, BSNK_SCHEME_UNSUPPORTED, BSNK_SIGNATURE_INVALID, BSNK_SIGNATURE_MISSING, BSNK_SIGNATURE_UNSUPPORTED, BSNK_STRUCTURE_UNSUPPORTED; audited key events BSNK_KEY_IMPORTED, BSNK_KEY_REMOVED |
Import warnings in the console and API (warnings) |
hmArsTlsUntrusted (a login would be refused), hmArsTlsUntrustedIfArtifact (the same on a preview, binding not known yet), hmArsTlsRevoked (the CA revoked the server's certificate: the broker must replace it), hmArsTlsNoStatus (the server answered but no revocation source did: check egress on port 80), hmArsTlsNotChecked (the server could not be reached, or the document names more than four) |
| Import refusals | hmUnpinned (import again and confirm the signer), METADATA_CERT_NOT_PKIO, METADATA_RESPONSE_BINDING_NOT_ARTIFACT, METADATA_INCOMPLETE, eidasProfileRequired, linkHeldByAnotherUser |
| Audit events | IDP_ARS_TLS_REVOKED, IDP_HM_METADATA_IMPORTED, IDP_HM_METADATA_REFRESHED, IDP_HM_METADATA_REFRESH_REFUSED, IDP_HM_METADATA_MISSING, IDP_HM_METADATA_CLEARED, IDP_RD_METADATA_IMPORTED, IDP_RD_METADATA_REFRESHED, IDP_RD_METADATA_REFRESH_REFUSED, IDP_RD_METADATA_CLEARED, IDP_EIDAS_NODE_METADATA_IMPORTED, IDP_EIDAS_NODE_SIGNER_PINNED, IDP_EIDAS_NODE_SIGNER_CHANGED, IDP_EIDAS_NODE_SIGNER_CONFIRM_REFUSED, EID_PKIO_TRUST_DISABLED, FEDERATED_LINK_RELINKED, FEDERATED_LINK_BLOCKED |
A refusal of a missing or unlisted certificate on the back channel is logged at DEBUG only. To find out why a login fails with a wrong broker certificate, raise the log level for the eID package.
New endpoints¶
Admin, under /admin/realms/{realm}, writes need the CSRF header:
| Method and path | Purpose |
|---|---|
GET /eid/presets |
The list of routes the console offers. |
POST /identity-providers/etoegang/hm-metadata/preview |
Check a broker document without storing it. |
POST /identity-providers/{alias}/etoegang/hm-metadata |
Import eHerkenning broker metadata. |
GET /identity-providers/{alias}/etoegang/service-catalog |
Service catalog draft (KV1.13). |
GET /identity-providers/{alias}/etoegang/metadata |
DV metadata for the broker. |
POST /identity-providers/digid/rd-metadata/preview |
Check CombiConnect RD metadata. |
POST /identity-providers/{alias}/digid/rd-metadata |
Import it. |
POST /identity-providers/{alias}/eidas/node-metadata |
Import an eIDAS node's metadata. |
GET /identity-providers/{alias}/eid/metadata |
SP metadata of an eID connection. |
GET · POST /identity-providers/{alias}/bsnk/keys |
List and import BSNk key files. |
DELETE /identity-providers/{alias}/bsnk/keys/{keyId} |
Remove one. |
POST /users/{userId}/federated-identities/{alias}/relink |
Give a blocked link its key back. |
Public, under /realms/{realm}: GET /broker/{alias}/etoegang/metadata, POST /broker/{alias}/etoegang/ars, GET /broker/{alias}/eidas/metadata, and /broker/{alias}/gdi/slo for CombiConnect logout.
Known limits¶
- A certificate that a broker document lists on a public CA has no revocation check in this release. Its trust comes from the signed document, its period and the host name. With the refresh off, withdrawing it needs an administrator to import the document again. A listed certificate that also chains to the PKIoverheid bundle is checked.
- A revoked mark lasts until the replica restarts. A replica that saw a revocation refuses that certificate even if the CA reinstates it; other replicas may pass it. The mark can also be lost by cache eviction after more than 1024 accepted certificates on one replica.
- A CRL that cannot finish within the handshake's budget, with OCSP down and no remembered good answer, stays refused until something caches it.
- The remembered good answers are per replica and in memory.
- The shipped PKIoverheid certificates end in November 2028 (the first on 2028-11-12). The console warns from 180 days before. Update HelixIAM to a release with their successors before then.
- With the refresh off, a broker's renewal is a login outage until an administrator acts. No alert comes before it; the signal is
EH_ARS_TLS_UNTRUSTEDin the log. - A withdrawn future certificate that a broker published and then dropped, once it is valid, is refused as a rollback until an administrator imports again.
- A failed metadata fetch is a WARN in the log; the console does not show it.
- A session that times out is not audited as a logout (no expiry hook exists); a logout request through the browser is.
- A restore into a fresh installation refuses enabled rows that carry a bundle.
- A YAML eID entry that is wrong stops the server at startup. A YAML eHerkenning or CombiConnect entry stops it when a PKIoverheid bundle is in force: YAML has no import.
- The console is English only. The sign-in pages users see stay in Dutch.
- Not supported: BSNk migration keys and DRKi (stored, not used),
Advicesignature checks, AD preselection, relying-party terms of non-public eIDAS nodes. - Not yet done: any chain test against Logius, a recognised broker or an eIDAS node.