Skip to content

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:

config:
  eidMetadataRefreshInterval: "PT6H"

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, and EH_ARS_TLS_REVOKED or DIGID_ARS_TLS_REVOKED as 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 with EH_ARS_TLS_STATUS_UNKNOWN or DIGID_ARS_TLS_STATUS_UNKNOWN.
  • soft-fail lets 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:

  1. outbound 443 to the broker's (or Logius's) metadata URL and to its Artifact Resolution server (a login needs it);
  2. outbound 80 to the CRL and OCSP hosts named by the certificates of every stored broker document, and by the PKIoverheid chain;
  3. 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_UNTRUSTED in 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), Advice signature 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.