Interface specifications web
Afsprakenstelsel | Document | |||
---|---|---|---|---|
Versie | 1.13 23 November 2023 | Auteur | Beheerorganisatie | |
Datum vaststelling |
| Classificatie | Openbaar | |
Datum publicatie |
| 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.
All message MUST the Unicode character set. All characters MUST be UTF-8 encoded.
Contents of this chapter
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.