Ga naar inhoud

Source and identity requirements

These requirements cover how a source describes its own services and how GBO activates that description. They also cover how the legal identity of a party follows from its certificate. For the design, see Source onboarding and Identity and trust.

This page has the following parts:

Source metadata and activation requirements

These requirements cover how a source publishes its service description, and how GBO validates and activates that description. REQ-64 applies to every GBO-delivered component that must know something per source or per service, in every data flow: EUDI issuance, the ASIP, and the consent facility (toestemmingsvoorziening) of DvTP. REQ-65 and REQ-66 describe activation as the issuance route and the shared Source Registry implement it.

The demo builds the description for two channels. EUDI issuance reads the eudi capability. Since ICTU/GBO-demo#592, the ASIP reads the asi capability (schema version 1.1) from the same Source Registry. In demo v0.9.0, the offer of a source for DvTP is in the GBO rules. The source does not publish it.

F-57 and F-58 give the background. ADR 0016 records the mechanism.

Evidence links to gbo-demo point at tag v0.9.0.

REQ-64: A GBO component works only with the service description the source publishes itself, after validation

A GBO-delivered component MUST take the service description of a source only from what the source publishes itself. The description covers the data service, the query with declared parameters, the mapping, the attestation schema, the validity per attestation type, and the offer. The component MUST NOT keep that description itself, add to it, or carry it per source in code. This applies to every GBO-delivered component that must know something per source or per service, in every data flow. These data flows are issuance, the ASIP, and the consent facility (the offer of the source per data set). A new service or data set of a source MUST be usable without a code change in such a component.

Before use, the component MUST validate the description on schema, origin (the publishing party is the bronhouder of the certificate set), version, validity window, and binding to the contract for the data service. The runtime MUST work only from a validated, activated version (REQ-66). Every request that follows from it goes through the PDP of the source (REQ-44). The description MUST name the read API of the logbook of the source, and the chain MUST fill dpl.read.nextLogbookId from it.

If the answer of the source does not fit the published mapping exactly, or holds more than one result, issuance MUST refuse. It MUST NOT pick a result, and it MUST NOT add or convert a value.

Case Outcome
Valid description, OIN equal to the certificate set, contracts present candidate activated
OIN in the description differs from the certificate set not activated: METADATA_INVALID
No contract for the data service the description names not activated: DATA_CONTRACT_NOT_FOUND
Query is not exactly one read operation, or unknown mapping profile not activated: METADATA_INVALID
Valid for less than one hour, or expires_at not after issued_at not activated: METADATA_INVALID
Issuance request with parameters outside the published offer refused (HTTP 400)
Answer does not fit the mapping (path missing, other datatype, result not a list) no attestation (HTTP 502): GBO_SIMPLE_PATH_MISSING, GBO_SIMPLE_TYPE_MISMATCH, GBO_SIMPLE_RESULT_TYPE (code)
Answer with more than one result no attestation (HTTP 502): GBO_SIMPLE_RESULT_AMBIGUOUS (code)
Answer without a result no attestation (HTTP 404) (code)
Source without its own endpoint, where the operator maintains the document admitted as an exception, visible as unauthenticated transport, lapses after expires_at
Read API of the logbook in the description proposal and not built
  • Status: ready for review
Source, evidence and notes
  • Source: design:
    • PSA S07 ("the bronhouder can in principle add new services through the source-specific GBO configuration")
    • PSA S10 ("the bronhouder manages a source-specific GBO configuration that records which data services are available for which data flows, and which schemas, mappings and other processing instructions apply", "central GBO facilities can consult the configuration relevant to them in machine readable form", "the configuration can be validated, versioned and traced")
    • PSA S11 (the bronhouder records mapping and attestation schema in its GBO configuration)
    • GO ("the mapping happens centrally with the settings from the decentral configuration component")
    • Implementing Regulation (EU) 2025/1569, Annex II point 2(b) (verify the identity of the authentic source)
    • P-10
    • for the exception: D-13
  • Addressee: GBO-delivered component: the reconciler and the runtime of the EUDI adapter, the ASIP, and the consent facility. Interface agreement: the form of the publication and the validation rules. What the bronhouder must publish is in AV-07 and AV-08.
  • Evidence: PR #219, PR #224, PR #242, PR #318, PR #463, #592.
  • Related: REQ-44, REQ-57, REQ-65, REQ-66, REQ-67, REQ-72, REQ-77, REQ-78, REQ-116, REQ-121, REQ-124, F-57, F-68, F-71, F-74, Q-14, Q-19, Q-38, ADR 0016, ADR 0017, ADR 0039.
  • Notes:
    • The requirement is built for EUDI issuance and, since #592, for the ASIP. The Source Registry is a shared module in services/source-registry. The ASIP reads the active release every 5 seconds.
    • The eudi capability describes each attestation with type_id, type_version, offers, graphql, mapping_profile, display, and claims. Each claim has one gbo-simple-v1 rule in source, a label, and an sd value. GBO derives the mapping and generates the Type Metadata from it. The schema has no separate mapping, attribute_schema, and type_metadata blocks.
    • The asi capability maps source fields onto GBO-catalogued attribute value schemas with pointer, join, const, and each. gbo-simple-v1 applies to the eudi capability only (ADR 0039).
    • For DvTP, the offer of a source is in the GBO rules (dvt0001.rego#L32-L44). The source does not publish it. For DvTP, the requirement covers the supply side. The legal ceiling per service, and whether a data set is mandatory or optional, come from the catalogue (FR-32, F-74, REQ-121, Q-45).
    • In demo v0.9.0, the origin check is authenticated transport (FSC) plus the OIN from the certificate set. The document itself is not signed.
    • The exception for a source without an endpoint follows D-13. The demo builds the exception as visible (data_transport_authenticated) and temporary (expires_at). The agreement of the bronhouder is only an instruction in the README (AV-08, F-71). The local compose also has a source over unsecured HTTP. Deployments do not mount it (docker-compose.yml#L1868-L1870).
    • Not built: the logbook read API in the description. In demo v0.9.0, the adapter gets it per caller from configuration (docker-compose.yml#L1819, F-68). Also not built: a reference to the DCAT-AP-NL description of the data service (S10: "refers to managed objects where possible").
    • The content and the interface of the source configuration are an open decision of PSA S10. gbo-source-metadata-v1 is the proposal of the demo.
    • The issuance runtime of nl-wallet reads its configuration only at start. That is a product property.

REQ-65: Only an explicit management action takes a source into use, and a valid contract is not enough

A valid FSC contract MUST NOT be enough to take a source into use or to publish its offer in the wallet. Taking a source into use MUST be an explicit management action, recorded in configuration apart from the contract. A validated service description MUST apply only after a separate promotion. A component MUST NOT discover and activate a source by itself.

Case Outcome
Valid metadata contract, no source configuration nothing activated
Source configuration, no metadata contract source blocked: METADATA_CONTRACT_NOT_FOUND
Source configuration, no contract for the data service source blocked: DATA_CONTRACT_NOT_FOUND
Validated candidate without promotion not active
  • Status: ready for review
Source, evidence and notes

REQ-66: Source metadata fails closed per source, ages within bounds, and can be rolled back

Source metadata can fail to validate, fall outside its validity, or fail to refresh within a grace period set in advance. In each of these cases, the metadata MUST fail closed for that source: no issuance follows on that metadata. The failure of one source MUST NOT stop issuance for other sources.

An activated version MUST be immutable, MUST be activated as a whole, and MUST be possible to roll back to an earlier valid version. A version number MUST identify one content. A candidate with the same version but other content MUST NOT be activated. A candidate with a lower version than the last validated candidate of that source MUST NOT be activated either. Only the explicit management action of REQ-65 can go back to an earlier version.

Case Outcome
Refresh fails, previous version within grace source stale, and issuance on the previous version
Refresh fails, no previous version or grace over source blocked
Active version of a source past grace issuance for that source refused (HTTP 503)
Certificate set of one source missing that source blocked, the others activated
One configured source without a valid version no new release for any source, and the active release stays (deviates from the requirement, see notes)
One source past grace offer list for all sources HTTP 503 (deviates from the requirement)
Roll back to a stored release active. Automatic promotion does not undo that.
Roll back to a release the adapter cannot load refused
Source publishes the same version with other content not activated (code, no test)
Source publishes a lower version than the last validated one not activated (code, no test)
  • Status: ready for review
Source, evidence and notes

Removed numbers

No numbers of this page were removed. The list of all removed numbers is on the requirements overview.

Identity, trust and transport requirements

These requirements cover how GBO establishes who an organization is, and how channels reach a source. FSC establishes the identity of the calling organization on every channel. The legal identity of a bronhouder (OIN and name) comes from its certificate. It does not come from configuration that an operator can fill in. Authorization for each request stays a separate layer: see Authorization.

ADR 0003 records FSC as the transport. ADR 0023 records the certificate roles. Evidence links to gbo-demo point at tag v0.9.0.

REQ-46: Every channel that calls a source on behalf of an external party does so through FSC, with a valid certificate

Every channel that calls a service of a bronhouder on behalf of an external party MUST do so through FSC. A channel MUST NOT enter the service of the bronhouder, or the authorization for it, directly. FSC establishes the identity of the calling organization. The authorization for each request (consent, PID binding, legal basis) stays a separate layer of the channel. If the certificate of the calling party is expired or revoked, the connection MUST be refused. The revocation check MUST NOT be disabled.

Case Outcome
Certificate of the calling party expired connection refused
Certificate of the calling party revoked connection refused, after the revocation propagates. Time limit: Q-53
Revocation check disabled in an Inway, Outway or Manager not allowed (proposal: not checked)
  • Status: ready for review
Source, evidence and notes
  • Source: design:
    • GO (FSC as the connectivity standard).
    • PSA S04.
    • FR-34 criterion 3 ("on expiry or revocation of the organization identification means, access to the consent process and the data traffic is blocked immediately").
    • FR-33 criterion 2.
  • Addressee: interface agreement for every channel: DvTP, EUDI issuance (PuB-EAA), and the Authentic Source Interface.

  • Evidence: all three channels call through their own FSC Outway:

    Nobody checked the revocation behavior.

  • Related: REQ-61, REQ-74, REQ-111, Q-53, Q-60, ADR 0003.

  • Notes:
    • FSC establishes the organization. That says nothing about what the organization is allowed to do in each request. The regime for each request follows from the evidence that the request carries (REQ-74).
    • open-fsc checks revocation with a CRL cache. An operator can switch the check off for each Inway, Outway, and Manager. Without this requirement, that switch is a silent configuration choice.
    • The time within which a revocation must take effect is Q-53.
    • The consent process blocks through the status in the register (REQ-111), as long as the initiation is not bound to the certificate (Q-60).

REQ-67: The legal identity of a bronhouder comes from its certificate and not from configuration

A GBO component can put the legal identity of a bronhouder (OIN and organization name) in an attestation or a decision record. The component MUST then take it from verified certificate material of that bronhouder. A value that an operator can fill in freely MUST NOT be the source for it.

Case Outcome
Certificate with the OIN in serialNumber and exactly one organization name OIN and name come from the certificate
Configured OIN or name differs from the certificate refused: the certificate set is not loaded
Certificate without a 20-digit OIN, or without exactly one organization name refused
  • Status: draft
Source, evidence and notes
  • Source: design:
    • PSA S04 ("organizations and systems use recognized identifiers and certificates", "the set-up links the technical identity to the admitted legal organization and role").
    • PSA F1.
    • FR-33 and FR-34.
    • P-07.
  • Addressee: GBO-delivered component: the source registration of the EUDI adapter.
  • Evidence: PR #242, PR #247, PR #321. Code and tests:
  • Related: REQ-58, REQ-64, F-60, Q-06, Q-07, Q-68, ADR 0023.
  • Notes:
    • It is open whether policy can read the Peer ID of a consumer as its OIN: Q-68.
    • In FSC the Peer ID is the subject.serialNumber of the FSC certificate. If the peer is the bronhouder itself, the Peer ID is the OIN. One peer can offer services of more than one bronhouder. So the source configuration keeps provider_peer_id apart from the OIN in the certificate (source_configuration.go#L35-L44).
    • The runtime gets leaf material and public CA certificates. It gets no CA private keys (development_ca_provider_test.go#L128).
    • Consents are bound to the identity of the consumer. A change of that identity makes them unusable (PR #244, PR #277).
    • In the default demo onboarding, RvIG is published through the Belastingdienst peer with the Belastingdienst OIN. That is a demo shortcut, and it does not show one OIN for each bronhouder. The certificate sets still differ for each source.

Removed numbers

  • REQ-01: removed. Organization attributes from a register described FSC and OpenFTV behavior that no longer exists.
  • REQ-02: merged into REQ-61 (admission comes from a register).
  • REQ-03: removed. A verified token before each query described code that no longer exists.

The list of all removed numbers is on the requirements overview.