Interface specifications web

Afsprakenstelsel		Document
Versie	AS1.24a-Ondersteuning Restgroepen (TRR) voor intermediairs	Auteur	Beheerorganisatie
Datum vaststelling	23 mei 2024	Classificatie	Openbaar
Datum publicatie	14 okt. 2024	Status	Definitief

This section describes the interface specifications for the traffic between all roles in the network. The messages are based on SAML 2.0, or XACML where applicable.

General requirements

The following requirements are valid for all interfaces.

SAML Web Browser SSO Profile

The SAML Web Browser SSO Profile MUST be used for the interface described in this document. Optionally, an extension can be used for retrieving attributes.

Relay State

Every SAML request message MAY contain RelayState data. The response to an SAML request with RelayState data MUST also contain this RelayState data. The content of the RelayState MUST NOT exceed 80 byte and MUST be protected against changes by the party creating the RelayState.

Namespace aliases

Perhaps superfluously, it must be said that the parties are free to choose the aliases they use for the abbreviations of namespaces in tags.

HTTP Headers

The following HTTP headers MUST be used for all content that is sent to the browser of a user:

Cache-Control with value "no-cache, no-store"
Pragma with value "no-cache"

Optional elements and attributes

Optional elements and attributes MAY be included in the messages. These elements MUST be populated according to the specifications and MUST NOT be empty.

Versioning

Because different versions of the interface specifications (e.g. 1.9 and up) must be distinguished from each other at the interface level, message versioning MUST be used in the implemented interface. Because SAML 2.0 messages do not have a field for this and it is not desirable to use an extension in the messages, participants MUST link the URL on which SAML messages can be offered to a version of the framework in the published metadata. For example, https://www.deelnemer.nl/SAML-endpoint/v1.0/.

The same URL MUST NOT be used for two different versions of the framework. See also SAML metadata.

Language preference

The language preference of the user can be specified, so the dialogue can take place in that language. Because SAML 2.0 messages do not have a field for this and it is not desirable to use an extension in the messages, EherkenningPreferredLanguage MAY be used as query variable in the URL or provided as POST variable. See also section SAML attribute elements.

Character set and encoding

All message MUST the Unicode character set. All characters MUST be UTF-8 encoded.

Contents of this chapter

Interface specifications DV-HM — This page describes the messages for the interface specification between a Dienstverlener (DV) (service provider) and a Herkenningsmakelaar (HM) (broker). For eIDAS Outbound, the eIDAS Berichtenservice acts as a DV, and as Dienstbemiddelaar (DB) for the BRP. Any statement in this page about the DV should therefore be interpreted as "DA (BRP) and/or EB".

Interface specifications HM-MR — This page describes the messages for the interface between an Herkenningsmakelaar (HM) (broker) and a Machtigingenregister (MR) (authorization information provider).

Interface specifications HM-EB — This page describes the interface between a Herkenningsmakelaar (HM) and the eIDAS-berichtenservice (EB).

Interface specifications HM-AD — This page describes the messages that are exchanged between an Herkenningsmakelaar (HM) and an Authenticatiedienst (AD) (identity provider).

Interface specifications DB-DA — This paragraph describes the (guidelines for) interface(s) between the Dienstbemiddelaar (DB) (Service Intermediary) and the Dienstaanbieder (DA) (Service Supplier). The interface between a DB and a DA is considered a machine to machine interface. The implementation details of this interface will always be specified by the Dienstaanbieder. In order to facilitate adoption, Elektronische Toegangsdiensten aims to deliver an Authorization Solution compatible not only with green field implementation, but also with existing services as already consumed in the field today. Thus to be interoperable with the wide variety of implementations that exist. Therefore the machine to machine interface will not specify a technical or protocol specific implementation but rather a set of principles, concepts and requirements. Currently, a reference for the interface DB-DA based on SOAP WebsServices is provided. In a future version these design principles will be further illustrated by including several other reference architectures of common service implementations, and how they map with these specifications and principles.

Reference Architecture DB-DA SOAP — This paragraph describes a reference architecture and specification of Interface specifications DB-DA, for use with a machine-to-machine interface using WebServices (SOAP).