Stelsel Toegang - SAML v1.0 - RC1 for DV/LC

Logius Guide
Draft

This version:
https://logius-standaarden.github.io/st-saml-spec/
Latest published version:
https://logius-standaarden.github.io/st-saml-spec/
Latest editor's draft:
https://logius-standaarden.github.io/st-saml-spec/
Editor:
Frans de Kok (Logius)
Authors:
Frans de Kok (Logius)
Jan Geert Koops (DICTU)
Mark Nijmeijer (DICTU)
Wiljan Pitlo (ICTU)
Carlo Huiden (ICTU)
Participate:
GitHub Logius-standaarden/st-saml-spec
File an issue
Commit history
Pull requests

This document is also available in these non-normative format: PDF


Status of This Document

This is a draft that could be altered, removed or replaced by other documents. It is not a recommendation approved by TO.

Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Abstract

This specification is intended for service providers (DV) who want to connect their webservices to DigiD and optionally DigiD-Machtigen and BVD-OG via a RD like TVS.

1. Disclaimer

This version of the document must not in any way be considered to be a normative source for the purpose of conducting audits on participants. This topic will be addressed in future versions.

Errata, functional improvements and other developments will be added to this documentation in future versions. Version history for this document is included on the History page.

2. History

Version Changes Distribution
[ST-SAML1.0] RC 1 Release Candidate 1: derived from [eID SAML4.4] Final with the following additional changes
  • Added support for BVD-OG in support of Stelsel Toegang release 1.
  • Added specifications for connection between RD and AD/BVD, based on [eID SAML4.5] specification
  • Change of structure to introduce two versions
    • Short version only covering DV and LC connecting to an RD (e.g. TVS)
    • Complete version also covering connections between RD and AD/BVD
  • All parts have been revised for improved clarity and consistency.
  • The specification now features extensive internal referencing, cross-linking and tooltips (aka 'Hover text') to improve navigation and context.
Internal

3. Glossary

3.1 Terms

Term/abbreviation English Nederlands Explanation
Artifact Artefact (SAML) Pointer to SAML message that is send through the front-channel, to avoid exposing sensitive data to the Webbrowser (UA) of the EU.
Assertion Verklaring A signed statement about a user's identity and mandates made by an AD or BVD. See SAML Assertion message.
Back channel Back channel Receiver (DV, LC, RD) uses an Artifact to collect the actual SAML message from the Sender (RD, AD or BVD). All SAML Back channel messages are placed in a SOAP envelope, the Webbrowser (UA) of the EndUser (EU) is not involved.
Front channel Front channel Communication between DV, LC, RD, AD and BVD via (a browser redirect of) the Webbrowser (UA) of the EndUser (EU).
BVD-DDM Bevoegdheidsverklaringsdienst DigiD-Machtigen A public instance of BVD specifically for mandates registered in DigiD-Machtigen only for public DV
BVD-OG BevoegdheidsVerklaringsDienst Ouderlijk Gezag A public instance of BVD specifically for legal representation concerning parental authority, based on Dutch national database of personal information (maintained by municipalities)
DigiD DigiD public IdP (AD) only for public DV
DigiD-Machtigen DDM DigiD-Machtigen - public Mandate Registry. See also BVD-DDM
DigiD-CC DigiD CombiConnect See also DigiD CC1.1 interface specification.
EntityID All systems in the network are identified by a unique EntityId in SAML Metadata, which is specified in the SAML metadata
ETD Trust Framework Afsprakenstelsel Elektronische Toegangsdiensten Dutch Trust Framework, also known as 'eHerkenning'. See https://afsprakenstelsel.etoegang.nl/.
Legal Representation Wettelijke Vertegenwoordiging Legal Representation means that someone (EU) is allowed by law to act on behalf of another person (Represented Party).
LoA Level of Assurance Betrouwbaarheidsniveau See supported Level of Assurance
Metadata Metadata Before a SAML connection can be established, all parties (DV, LC, RD, AD and BVD) must exchange connection properties. This is done through SAML Metadata.
Participant Deelnemer Any party that has a role in the authentication or representation processes that are within the scope of this specification. These include RD, AD and BVD.
Represented Party Vertegenwoordigde Service Consumer represented by EU
SAML SAML De SAML v 2.0 standard, also referred to as SAML 2.0. SAML is an acronym of Security Assertion Markup Language. See [SAML2.TO].
Service Service Dienst Service offered by a DV
Service Catalog Service Catalog Dienstencatalogus of DC Collection of Services offered by all Service Providers, kept by RD. The DV is responsible for keeping their Services in the Service Catalog up to date.
Service Consumer Service Consumer Belanghebbende Service Consumer is the Entity Concerned: either EU when acting on its own behalf, or the Represented Party when EU is representing someone else.
ServiceUUID Service Universally Unique IDentifier ServiceUUID is an identifier of a service that is unique in the context of the network
SSO Single Sign On Eenmalig Inloggen
SLO Single Log Off Federatief uitloggen Single Log Off feature
ST-SAML SAML specification for DV connecting via TVS (RD) to DigiD, DigiD-Machtigen and BVD-OG SAML specification for a DV connecting via TVS (as RD) to DigiD, DigiD-Machtigen and BVD-OG
TVS TVS TVS public RD only for public DV

3.2 Roles

De following roles are used in this specification.

Abbreviation Role/Actor Description Example
Authenticatiedienst Identity Provider (IdP) DigiD, EB and AD in ETD
BVD Bevoegdheidsverklaringsdienst Service that provides assertions for representation relationships The BVD-DDM (DigiD Machtigen), BVD-OG (parental authority)
DV Dienstverlener Service Provider Website of municipality, hospital, government agency
EB eIDAS Berichten Service eIDAS Nederland knooppunt
EU EindGebruiker End User Natural Person acting on its own behalf to consume a Service OR acting on behalf of someone else (the Service Consumer).
LC Leverancier Clusteraansluiting Clusterconnection provider: This role assists the DV in connecting to RD. LC will handle all connectivity to RD for their registered DV PaaS/SaaS providers within the health-care field
RD Routeringsdienst Routing Service Provides access to ADs and BVDs TVS
UA User Agent User Agent is application controlled by the EU WebBrowser

4. Introduction

This ST-SAML specification facilitates Stelsel Toegang release 1. [ST-SAML1.0] derived from [eID SAML4.4] and [eID SAML4.5]. It introduces the BVD-OG for an extra representation use case: legal representation of a minor by someone with parental authority (Ouderlijk Gezag). If a DV supports this use case, the RD (or DV) will offer the choice to do so to the EU.

ST-SAML specifies the communication between DV and RD and also between LC and RD. ST-SAML also specifies the communication between Routeringsdienst (RD) and BVD for parental authority (BVD-OG). [eID SAML4.5] specifies the communication between RD and DigiD (as AD) and between RD and BVD for registered mandates in DigiD-Machtigen: BVD-DDM. These DigiD specific specifications are out of scope for this ST-SAML specification.

Single

Clustered

out of scope

out of scope

DV

LC

RD

DigiD

BVD_DDM

BVD_OG

Figure 1 Stelsel Toegang SAML1.0

Routeringsdienst (RD) supports the use cases summarized below:

Use case Description
Authentication Authenticating an EU for a single Service, for a single purpose. This is the most basic use case scenario from a DV's point of view. Authentication always implies consent of the EU for accessing the Service and may include authorization if the EU is using representation.
Cluster connection connectivity In a Cluster connection setting, a LC is technically responsible for connecting a DV to RD.
Authentication with representation an EU authenticates with the intent to consume the Service on behalf of another person Represented Party using a Representation Relationship that is registered within a BVD context.
Authentication and/or representation via a RD At a RD, an EU interactively selects an AD for which they own an authentication means, and/or a BVD in which a representation relation that they intend to use is registered, from multiple options. The RD redirects the EU to the selected AD and/or BVD.
Authentication with AD/BVD preselection Authenticating an EU where selection for the AD or BVD is done at the DV prior to the authentication request to the RD in order to optimize the EU experience.

SAML specification

The document is not a complete SAML reference. It is assumed that the reader is familiar with SAML and will use the referenced documentation as well when needed.

5. Frameworks

5.1 SAML generic

SAML Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 [SAML2]

NORA, Nederlandse Overheid Referentie Architectuur [NORA].
NCSC ICT-beveiligingsrichtlijnen voor Transport Layer Security (TLS) [NCSC.TLS].

SAML profiles A SAML profile is a specific set of rules that are used for a specific use case. ST-SAML uses two profiles of the SAML standard, namely:

5.2 DV - SAML message flows & bindings

Only the bindings that are listed in the tables are supported between DV and LC

5.2.1 DV→RD authentication flow

The diagram below depicts the authentication flow between a DV and LC and the RD.

See also DV-RD - SAML authentication messages

AD/BVDRD back-channelRD front-channelDV / LCUAAD/BVDRD back-channelRD front-channelDV / LCUAOut of Scope - see RD→AD/BVDGET resource1AuthnRequest2AuthnRequest34567artifact8artifact9ArtifactResolve10ArtifactResponse11establish security context12access resource13
Figure 2 Authentication and representation flow - overview
5.2.1.1 Front-channel (re)authentication
Step # Route Message Endpoint Binding Metadata
2 + 3 DV/LC (→UA)→RD AuthN Request message SingleSignOnService HTTP-POST RD→DV
8 + 9 RD (→UA)→DV/LC Artifact binding message AssertionConsumerService (DV)
AssertionConsumerService (LC)
HTTP-Artifact DV→RD LC→RD
5.2.1.2 Back-channel (Assertion)
Step # Route Message Endpoint Binding Metadata
10 DV/LCRD Artifact Resolve message ArtifactResolutionService SOAP RD→DV
11 RDDV/LC AuthN Response message None, is a synchronous response SOAP

5.2.2 DV→RD Federated Logout flow

Only a limited form of SP (DV/LC) initiated logout is supported within the context of a SSO federation. IdP (AD) initiated Logout is NOT supported! On receiving a logout request from the EU via the UA (step 1) a DV/LC which participates in a SSO federation MUST send a LogoutRequest to RD (step 2 and 3). RD propagates the Logout Request to appropriate AD. If the AD replies success status, the RD will reply with a LogoutResponse with success status to the DV/LC.

The diagram below depicts the single logout flow between a DV and LC and the RD.

Also see SAML Federated login and logout

ADRD back-channelRD front-channelDV / LCUAADRD back-channelRD front-channelDV / LCUAOut of Scope: see RD→AD/BVDlocal logout1LogoutRequest2LogoutRequest3456LogoutResponse7LogoutResponse8
Figure 3 SAML Federated Logout overview
Step # Route Message Endpoint Binding Meta-data
2 + 3 DV/LC (→UA)→RD Logout Request SingleLogoutService HTTP-POST RD→DV
7 + 8 RD (→UA)→DV/LC Logout Response SingleLogoutService (DV)
SingleLogoutService (LC)
HTTP-POST DV→RD LC→RD

6. Supported Use Cases

6.1 Authentication

An EU intends to consume a Service on his/her own behalf, from a DV for which authentication is required.

6.1.1 Actors

Roles

For more information see also Roles

6.1.2 Functional description

An EU intends to consume a Service on his/her own behalf. The Service is offered on the web by a DV.

The EU visits the website of the Service, where the EU may have to interact to indicate the intent to consume the Service. As the Service requires authentication, this triggers the authentication process.

The DV will now redirect the EU to RD, requesting authentication of the EU for the Service. Note that in this use case the EU will not select to act on behalf of another. (See Authentication with Representation)

Next, the EU is redirected to the AD. After successful authentication the AD takes care the EU is redirected back to RD, who includes the attestation of identity in the relevant interface response to the DV. This response includes at minimum an identifier of the EU, the LoA attested to and the Service authenticated for. The LoA of the authentication is at minimum equal to or higher than the configured LoA for the Service within the Service Catalog. The RD now includes the attestation of identity and the attestation of representation relationship in the relevant interface response to the DV. This response includes at minimum an identifier of the EU and the Represented Party, the LoA attested to and the Service authenticated for.

The DV can now take an access control decision to its Service for the EU.

The technical steps in the authentication flow are described in DV SAML Authentication.

Note

Communication between RD and DigiD is specified in DigiD Combiconnect specification (DigiD-CC) and is out of scope of this specification.

6.2 Authentication with representation

An acting EU intends to consume a Service to represent another party, from a DV, for which authentication is required. The EU acting on behalf of a Represented Party, must be a Natural Person, using a representation relationship. The Represented Party must also be a Natural Person. The relationship must be formalized and a direct relationship.

The authentication of the acting EU takes place just like in the Authentication use case. Similarly, the representation information concerning both the acting EU, the Represented Party and the Service for which they have a representation relation will provided by a BVD, either

  1. Standard representation aka DigiD-Machtigen by BVD-DDM
  2. Legal representation by other BVDs eg. BVD-OG.

6.2.1 standard representation

The acting EU acts on behalf of the Represented Party (Service Consumer). The representation relationship underpinning this must be registered by Represented Party as a formalized mandate in a mandate registry (DigiD-Machtigen), prior to application in this use case.

Rules governing representation and registration of a registration relationship are out of scope of this specification. Communication between RD and BVD-DDM is specified in DigiD-CC specification and is out of scope of this specification.

6.2.3 Actors

Roles

6.2.4 Functional description

The EU visits the website of the Service, where the EU may have to interact to indicate the intent to consume the Service. As the Service requires authentication, this triggers the authentication process. The EU must be able to indicate the intent to consume the Service on behalf of a Represented Party (and not for his/herself) before the authentication process is triggered.

The DV (or LC) will now redirect the EU to RD, requesting authentication of the EU for the Service, including the request to authorize based on a representation relationship.

Next, the EU is redirected to the AD. After successful authentication, the AD redirects the EU to RD. RD will then redirect the EU to BVD-DDM. Here the EU selects the representation relationship to use, if multiple options are available. Afterwards the BVD redirects the EU back to RD.

RD now includes the attestation of identity and the attestation of the representation relationship in the relevant interface response to the DV (or LC) . This response includes an identifier of the EU and the Represented Party and in case of legal representation also the specific type of legal representation between both. Also the requested ServiceUUID and the LoA of the authentication is included in the response. The LoA is at minimum equal to or higher than the configured LoA for the Service within the Service Catalog.

The DV can now take an access control decision to its Service for the EU on behalf of the Represented Party.

The technical steps in the authentication flow are described here: DV SAML Authentication.

6.3 Cluster connection connectivity

In Software-as-a-Service (SaaS) or multi-tenant solutions, multiple DV's are hosted on a single environment operated by a software vendor. The software vendor can act as an LC. Functionally the LC itself is not actively taking part in any of the primary use cases, thus is not an actor in those use cases.

Note
Although above the Cluster is linked to SaaS solutions, the cluster connection can be applicable in Platform-as-a-Service (PaaS) offerings as well. This is only the case if the platform natively offers connectivity to RD; it is NOT applicable if the connectivity is built on top of the platform provided using PaaS.

For Infrastructure-as-a-Service solutions (IaaS), the Cluster Connection is NOT applicable.

6.3.1 Actors

Roles Description
DV See also Roles
LC
RD

6.3.2 Technical description

The Cluster Connection is acknowledged during requests for authentication, as made in the supported use cases. The LC is registered at RD and is also responsible for registering all DV's he provides access for. Relationship between DV and LC must be established in the registration/on-boarding process with RD and in LC-metadata.

DV initiates authentication via the LC. The LC will send an AuthN Request Message to RD on behalf of DV.

Data in the response from RD will be encrypted only for the DV to decrypt, not the LC.

In this way, the LC can facilitate the authentication processes, but cannot access the sensitive information contained in the response.

Note

The way a DV interacts with a LC is not part of this specification.

6.4 Authentication with AD/BVD preselection

an EU intends to consume a Service on his/her own behalf, from a (semi-)governmental or public DV], for which authentication is required. The EU makes the selection for the AD at the DV , rather than at the RD. In order to improve [=EU=|user] experience (UX), this enables presenting the choice of AD at the DV at the most appropriate time and in the best fitting manner.

Additionally in a representation scenario, the EU can (also) select the BVD at the DV .

Note

Passing the choice for AD/BVD is solely offered for improving [=EU=|user] experience. It is explicitly not the intention that DV introduce a bias in the choice for the AD/BVD to use. Valid use cases for bypassing EU preference, where a DV selects a specific AD/BVD for an EU , are very rare and specific. DV should offer the choice for each AD/BVD in a non-discriminatory way for all applicable AD/BVD.

6.4.1 Actors

Roles

For more information see also Roles

6.4.2 Functional description

This use case is a functional extension to Authentication. Instead of choosing the AD and/or BVD after being redirected to the RD, the EU selects the AD and/or BVD for usage at an earlier stage at the DV. The RD will apply the pre-selection as a filter on all available options. If, after filtering, alternative options are found, the RD will prompt the EU to further narrow down the selection.

The DV will offer the EU to make a choice from the list of applicable ADs before sending a request for authentication to the RD. Simultaneously with the choice for an AD, the choice to represent another will be offered the EU with (optionally) the BVD to be used. After making the choice for an AD, acting-as-a-representative and the choice for a BVD , these choices will be included in the request for authentication to the RD. In case the EU acts on behalf of another without pre-selecting a BVD, the choice for a BVD will be presented in a later stage at the RD.

The technical steps in the authentication flow are described in the SAML-Message-specification.

7. Message Specification

RD - Leeg

7.1 DV - SAML Message specification

7.1.1 DV→RD - SAML authentication proces

SAML authentication messages between DV (or LC) and RD are described in this chapter. First the authentication overview and the steps, then the specification of the individual SAML messages between DV and RD.

7.1.1.1 DV→RD - authentication - diagram

The diagram below contains the authentication steps that are made when an EU authenticates with a DV through the RD. When an LC is present between DV and RD the LC will take the role of DV in relation to the RD.

AD/BVDRD back-channelRD front-channelDV / LCUser AgentAD/BVDRD back-channelRD front-channelDV / LCUser AgentOut of Scope: see RD→AD/BVDGET resource1AuthnRequest2AuthnRequest34567artifact8artifact9ArtifactResolve10ArtifactResponse11establish security context12access resource13
Figure 4 SAML authentication flow - DV/LC - RD
7.1.1.2 DV→RD - authentication - steps

Before the above authentication steps are explained, it is important to make a distinction between the Front channel and the Back channel. The Front channel is the communication between the DV or LC and RD via the UA of the EU (step 2 & 3 and step 8 & 9 in the figure above). The Back channel is the direct communication between the DV or LC and RD (step 10 and Step 11 in the figure above). This distinction is important because possibly sensitive data (such as a citizen service number) is never send via the Front channel, so that they can never be intercepted or changed by the UA.

Step 1

The EU with a UA wants to access a part on the web service of the DV that requires authentication of the EU.

Step 2 and 3

The DV or LC will send the EU to RD for authentication and or proof of representation.

Step 4 up to and including 7 (out of scope for this flow)

In this step the RD will offer the EU a choice of AD's and BVD's that fulfil the authentication requirements (e.g. minimum level of assurance required, type of mandate). Optionally, the DV can pass pre-selection information concerning the AD to query, and if representation will be used, to the RD.

If the EU hasn't already chosen in step 2, the EU chooses an authentication method that meets the minimum required LoA, and also chooses whether to use representation. The EU is presented with the corresponding AD login screen. The EU authenticates with the chosen means.

Optionally, the EU also chooses a representation method. The EU is presented with the corresponding screen with choice of who to represent. The EU chooses the correct Represented Party to represent.

Step 8 and 9

RD sends the EU back to the DV or LC via a redirect. An opaque Artifact generated by RD is send here. This Artifact refers to the actual Artifact Response message that is waiting at RD.

Even if the authentication starting in step 4 was unsuccessful or interrupted, an artifact is send to the DV or LC. This Artifact provides an error message with the Artifact Resolve request and cannot be exchanged for a valid Assertion.

Step 10

With the Artifact the DV/LC sends an Artifact Resolve request to the RD for the result of the (successful or unsuccessful) authentication and (optionally) representation via a Back channel.

Artifacts are stored by RD for a maximum of 15 minutes and can only be retrieved once by the DV/LC. Situations are possible (process breakdown, early logout) where RD saves an Artifact for less than 15 minutes.

Step 11

RD replies with an Artifact Response message that belongs to the Artifact. In this message, RD provides an Assertion that includes the authentication result and optionally the representation selection. And, if the authentication / representation selection was successful, the requested (encrypted) identifier(s) and attribute(s) of the EU and optionally the Represented Party. The identities and attributes are encrypted so that only the intended DV(s) can obtain the plain text value.

If the authentication or attempt to select representation was unsuccessful, it is indicated in the Status Code of the Response message and if possible, a reason is given so that the web service can inform the EU.

Step 12 & 13

Successful authentication / selection of representation gives the DV information needed for access control decision typically resulting in EU access to service in step 13.

7.1.2 DV→RD - SAML messages

The SAML messages are specified in detail in the following sections. The following rules apply

  1. The messages contain at least the elements that are specified as mandatory by the standard.
  2. In addition, the messages also contain optional elements. It is indicated whether these elements are mandatory, conditional or optional. With optional elements, it is up to the participants to determine whether they are used.
  3. Optional SAML elements that are not in this specification SHOULD NOT be included. When present they will be ignored when possible.
7.1.2.1 DV→RD AuthnRequest

When a principal (or an agent acting on the principal's behalf) wishes to obtain assertions containing authentication statements to establish a security context at one or more relying parties, it can use the authentication request protocol to send an AuthN Request message message element to a SAML authority and request that it returns a AuthN-Response message containing one or more such assertions.

7.1.2.1.1 DV→RD AuthnRequest Diagram

The possible sender and recipient of the AuthnRequest message are the following:

Sender Recipient
DV RD
LC RD
AD/BVDRD back-channelRD front-channelDV / LCUser AgentAD/BVDRD back-channelRD front-channelDV / LCUser AgentOut of Scope: see RD→AD/BVDGET resource1AuthnRequest2AuthnRequest34567artifact8artifact9ArtifactResolve10ArtifactResponse11establish security context12access resource13
Figure 5 SAML authentication flow - DV/LC - RD - AuthN-Request
7.1.2.1.2 DV→RD AuthnRequest Message

See also Example AuthnRequest DV for RD

Element/@Attribute 0..n Description
Issuer = DV or LC
Recipient = RD
@ID 1 Unique message identifier. MUST identify the message uniquely within the scope of the sender and receiver for a period of at least 12 months.
@Version 1 Version of the SAML protocol. The value MUST be 2.0.
@IssueInstant 1 Time of issuing of the request.
@Destination 1 URL of the recipient on which the message is offered. MUST match SingleSignOnService in the metadata .
@ForceAuthn 0..1 The value true indicates that an existing SSO session MUST NOT be used for the request. If the value is false or empty or the attribute is missing, an existing SSO session MAY be used for the request.
@AssertionConsumerServiceIndex 1 This index MUST refer to an endpoint of an AssertionConsumerService in the issuer's metadata for the recipient.

NOTE: as a consequence, the AssertionConsumerServiceURL MUST NOT be included.
@AttributeConsumingServiceIndex 0..1 Conditional. Only one of Extensions or @AttributeConsumingServiceIndex MUST be present.

NOTE: Also see the use of @AttributeConsumingServiceIndex and Extensions
@ProviderName 0..1 Conditional. Reserved for use with eIDAS UIT to show information about the foreign DV and country in order to obtain EU consent. SHOULD NOT be used in other use cases and will be ignored if used.
Issuer 1 MUST contain the EntityID of the issuer as registered in the Metadata.
Signature 1 MUST contain the XML signature of the sender for the enveloped message. MUST contain a KeyInfo element with a KeyName or X509Certificate elements. See Signature
Extensions 0..1 Conditional. Only one of Extensions or AttributeConsumingServiceIndex MUST be present. And when Extensions is present, it MUST contain the attributes described below.

NOTE: Also see the use of @AttributeConsumingServiceIndex and Extensions
-Attribute 1 An Attribute with the @Name="urn:nl-eid-gdi:1.0:IntendedAudience" MUST be present and contain an AttributeValue with the EntityID of the DV for which authentication is requested.

NOTE: (future) support for more than one audience where each audience receives the audience specific EncryptedID is provided by the Service Definition registered with the Service Catalog.
-Attribute 1 An Attribute with the @Name="urn:nl-eid-gdi:1.0:ServiceUUID" MUST be present and contain an AttributeValue containing a ServiceUUID that is known at the Service Catalog of the receiving RD, AD and BVD.
Scoping 0..1 Conditional. Element MAY be used to limit the selection of AD's or BVD's at the RD.
-IDPList 0..1 Conditional. List of IDP's - Element MUST be present in DV Authn-request message when Scoping element is present.
--IDPEntry 1..n At least one IDPEntry (of an AD) MUST be present if the IDPList element is present.
If no valid IDPEntry is present, the AuthnRequest will fail with a top level status code urn:oasis:names:tc:saml:2.0:status:Requester and second-level code depending on the condition according to [SAML2.CORE] section 3.2.2.2: urn:oasis:names:tc:SAML:2.0:status:NoSupportedIDP.
If the list also contains the EntityID of a BVD. This indicates that representation using the BVD is optional in combination with the AD'(s) in the IDPList. The RD will let the EU choose whether to use representation with a BVD. The RD MUST limit the AD and BVD selection list presented to EU's for AD's or combination of AD’s and BVD’s that are supported.
---@ProviderID 1 MUST contain the EntityID of a pre-selected AD or BVD
-RequesterID 0..n Conditional. Element MAY be present if using authentication with representation. If used it MUST contain the EntityID of a BVD.
If more than one RequesterID is included with different BVD’s the RD MUST let the EU choose a BVD. If both RequesterID and IDPList are used, any BVD that is in a RequesterID MUST also be included in the IDPList.
7.1.2.1.2.1 The use of AttributeConsumingServiceIndex or Extensions for referring to service definitions

This specification uses the concept of a Service Catalog kept by RD, which contains amongst others Service Definitions. In the Service Catalog each 'Service Definition' has a unique ServiceUUID. Each AuthN Request message must refer to a Service Definition using its ServiceUUID.

An AuthN Request message has two options for this ServiceUUID reference:

  1. Only the DV MAY provide a @AttributeConsumingServiceIndex that MUST correspond to an @Index attribute of an AttributeConsumingService entry in the DV Metadata. And this AttributeConsumingService entry MUST contain a ServiceUUID. When using the AttributeConsumingServiceIndex the RD will obtain the DV's EntityID from the Issuer element in the AuthN Request message.
  2. Alternatively a DV MAY use the Extensions element in the AuthN Request message. All other Participants MUST use the Extensions element in the AuthN Request message. The Extensions element contains both the EntityID of the DV and the explicit ServiceUUID.
7.1.2.1.3 DV→RD AuthnRequest Processing rules

In addition to the processing rules required by the SAML specification the following rule applies. If any of these validations fails, the authentication MUST fail:

  1. RD MUST validate that the DV is registered for the requested ServiceUUID referenced by the index in the DV metadata or in the Extensions element of the DV AuthN-request and validate that the registration is valid;

  2. IF an LC is involved THEN RD MUST validate that the DV is registered to use the requested ServiceUUID with the LC that sends the DV AuthN-Request message on behalf of the DV and that the registration is valid;

7.1.2.2 DV←RD Artifact Binding

The SAML response of a RD to a SAML request of a DV (or LC) uses an Artifact-Binding for extra security see [SAML2.BINDINGS] section 3.6.6. Therefor SAML Response does not return the actual SAML message with an Authentication Assertion but an Artifact as a reference to actual the SAML AuthN Response - Assertion message. The Artifact is used by the DV (or LC) to retrieve the SAML AuthN Response - Assertion at the RD.

7.1.2.2.1 DV←RD - Artifact Binding - Diagram

The sender and recipient of this message are the following:

Sender Recipient
RD DV
RD LC
AD/BVDRD back-channelRD front-channelDV / LCUser AgentAD/BVDRD back-channelRD front-channelDV / LCUser AgentOut of Scope: see RD→AD/BVDGET resource1AuthnRequest2AuthnRequest34567artifact8artifact9ArtifactResolve10ArtifactResponse11establish security context12access resource13
Figure 6 SAML authentication flow - DV/LC - RD - Artifact Response
7.1.2.2.2 DV←RD - Artifact Binding - Message

The RD sends an Artifact via the Front channel to the DV/LC, using a HTTP-redirect of the webbrowser to the AssertionConsumerService referenced in the AuthN Request message.

e.g. https://dv.nl/SAML/ACS?SAMLart=AAQAAMh0dHA6Ly9pZHAuZXhhbXBsZS5jb20vU0FNTC9N&RelayState=xyz123

The Artifact is only a reference to the SAML AuthN Response - Assertion. And even if no authentication has taken place, an Artifact will be send.

7.1.2.3 DV→RD ArtifactResolve

The DV/LC uses the Artifact to send an ArtifactResolve request to the RD via a SOAP binding over the Back channel. The Back channel is protected with two-sided TLS authentication.

7.1.2.3.1 DV→RD ArtifactResolve Diagram

The sender and recipient of the Artifact Resolve are the following:

Sender Recipient
DV RD
LC RD
AD/BVDRD back-channelRD front-channelDV / LCUser AgentAD/BVDRD back-channelRD front-channelDV / LCUser AgentOut of Scope: see RD→AD/BVDGET resource1AuthnRequest2AuthnRequest34567artifact8artifact9ArtifactResolve10ArtifactResponse11establish security context12access resource13
Figure 7 SAML authentication flow - DV/LC - RD - Artifact Resolve
7.1.2.3.2 DV→RD ArtifactResolve Message
Element/@Attribute 0..n Description
@ID 1 Unique message identifier. MUST identify the message uniquely within the scope of the sender and receiver for a period of at least 12 months.
@Version 1 Version of the SAML protocol. The value MUST be 2.0.
@IssueInstant 1 Time at which the message was created.
@Destination 0..1 MAY be included. If included MUST contain the URL of the receiver on which the message is offered. MUST match one of the ArtifactResolutionService elements in the receiver's metadata.
Issuer 1 MUST contain the EntityID of the sender.
Signature 1 MUST contain the Digital signature of the sender for the enveloped message. MUST contain a KeyInfo element with either a KeyName or X509Certificate elements. See Signature.
Artifact 1 Contains the Artifact that was received as query parameter.
7.1.2.4 DV←RD ArtifactResponse

In response to the Artifact Resolve message, the RD will send an Artifact Response message back to the DV/LC via the SOAP binding over the Back channel. If successful this Artifact Response message contains the AuthN-Response Assertion for the original AuthN Request message.

7.1.2.4.1 DV←RD ArtifactResponse Diagram

The sender and recipient of the Artifact Response message message are the following:

Sender Recipient
RD DV
RD LC
AD/BVDRD back-channelRD front-channelDV / LCUser AgentAD/BVDRD back-channelRD front-channelDV / LCUser AgentOut of Scope: see RD→AD/BVDGET resource1AuthnRequest2AuthnRequest34567artifact8artifact9ArtifactResolve10ArtifactResponse11establish security context12access resource13
Figure 8 SAML authentication flow - DV/LC - RD - Artifact Response
7.1.2.4.2 DV←RD ArtifactResponse Message
Element/@Attribute 0..n Description
@ID 1 Unique message identifier. MUST identify the message uniquely within the scope of the sender and receiver for a period of at least 12 months.
@InResponseTo 1 Unique ID attribute of the Artifact Resolve message request for which this ArtifactResponse message is the response.
@Version 1 Version of the SAML protocol. The value MUST be 2.0.
@IssueInstant 1 Time of issuing of the AuthN Response message.
Issuer 1 MUST contain the EntityID of the sender.
Signature 1 MUST contain the Digital signature of the sender for the enveloping message. MUST contain a KeyInfo element with a KeyName element. See Signature.
Status 1 MUST contain a StatusCode element with the status of the artifact resolve.
-StatusCode 1 MUST be present in a Status element.
-@Value 1 The Value of this StatusCode element MUST be from the top-level list provided in [SAML2.CORE] section 3.2.2.2 and follow the rules described in [SAML2.BINDINGS] section 3.6.6.
--StatusCode 0..1 Conditional. Should only be present if top-level StatusCode is not urn:oasis:names:tc:SAML:2.0:status:Success.
--@Value 1 If present MUST contain an URI reference indication details about the error.
-StatusMessage 0..1 Only present if top-level StatusCode is not urn:oasis:names:tc:SAML:2.0:status:Success. MAY contain a message detailing the error that occurred.
Response 0..1 Conditional. If the artifact resolves to a response this MUST contain the AuthN Response - Assertion to the AuthN Request message. The AuthN Response - Assertion is described below.
7.1.2.4.2.1 Processing Rules for Status

Special processing rules for Status are described in [SAML2.BINDINGS] §3.6.6.

Even if the ArtifactResponse's Status indicates success it may still not contain a AuthN Response - Assertion conform [SAML2.BINDINGS] §3.6.6:

If the RD receives an Artifact Resolve message message that it can understand, it MUST return a AuthN Response message with a StatusCode value of urn:oasis:names:tc:SAML:2.0:status:Success`, even if it does not return the corresponding message (for example because the artifact requester is not authorized to receive the message or the artifact is no longer valid).

7.1.2.4.3 DV←RD AuthN Response - Message

Via the Artifact Response Message the RD sends the SAML AuthN-Response Message which is the response the original AuthN Request message of the DV/LC. The SAML AuthN-Response Message contains the AuthN Response - Assertion if authentication of the EU at the AD was successfull, and (when relevant) the BVD could establish a valid representation relationship.

Element/@Attribute 0..n Description
@ID 1 Unique message characteristic. MUST identify the message uniquely within the scope of the sender and receiver for a period of at least 12 months.
@InResponseTo 1 Unique ID attribute of the AuthN Request message request for which this AuthN Response - Message is the response.
@Version 1 Version of the SAML protocol. The value MUST be 2.0.
@IssueInstant 1 Time of issuing of the AuthN Response - Assertion.
@Destination URL of the endpoint on which the message is offered. MUST match a recipient’s metadata AssertionConsumerService.
Issuer 1 MUST contain the EntityID of the sender.
Signature 0..1 SHOULD NOT be used as the AuthN Response - Assertion is part of the AuthN Response message messages which is already signed by RD. If included MUST contain the Digital signature of RD for the enveloping message. MUST contain a KeyInfo element with a KeyName or X509Certificate element.
Status 1 MUST contain a StatusCode element with the status of the authentication.
-StatusCode 1 MUST be present in a Status element.
-@Value 1 If not urn:oasis:names:tc:SAML:2.0:status:Success additional information SHOULD be provided in the embedded StatusCode element.
The Value of this StatusCode element MUST be from the top-level list provided in SAML core section 3.2.2.2. See the codes listed in Error codes.
--StatusCode 0..1 Conditional. SHOULD only be present if top-level StatusCode is not urn:oasis:names:tc:SAML:2.0:status:Success.
--@Value 1 In the event of a cancellation or error, the element MUST be populated with the value urn:oasis:names:tc:SAML:2.0:status:AuthnFailed.
-StatusMessage 0..1 Only present if top-level StatusCode is not urn:oasis:names:tc:SAML:2.0:status:Success. MAY contain a message detailing the error that occurred, MUST contain exact phrase Authentication cancelled when authentication is cancelled (see also SAML Error codes)
Assertion 0..1 Conditional. MUST contain the AuthN Response - Assertion if the request was processed successfully (Status was urn:oasis:names:tc:SAML:2.0:status:Success). See AuthN Response - Assertion. Otherwise, MUST not be included.
EncryptedAssertion 0 MUST NOT be included.
7.1.2.4.4 DV←RD AuthN Response - Assertion
Element/@Attribute 0..n Description
    Issuer = RD
Recipient = DV or LC
@ID 1 Unique message identifier. MUST identify the message uniquely within the scope of the sender and receiver for a period of at least 12 months.
@Version 1 Version of the SAML protocol. The value MUST be 2.0.
@IssueInstant 1 Time of issuanceing of the AuthN Response - Assertion.
Issuer 1 MUST contain the EntityID of RD.
Signature 1 MUST contain the Digital signature of the sender for the enveloped message. MUST contain a KeyInfo element with a KeyName element. See Signature.
Subject 1 MUST be included.
-NameID 1 NameID MUST contain a TransientID.
-SubjectConfirmation 1 Contains the SubjectConfirmation conform the WebSSO profile.
See also: SubjectConfirmation.
Conditions 1 NotBefore and NotOnOrAfter limit the window during which the assertion can be delivered.
See also: Conditions.
-@NotBefore 1 MUST be included.
-@NotOnOrAfter 1 MUST be included.
-AudienceRestriction 1 MUST be included.
--Audience 1..n MUST contain an EntityID for all relevant parties that are intended to receive and process this assertion, as per SAML WebSSO profile. See below under Audience restriction)
AuthnStatement 1 MUST be included.
-@AuthnInstant 1 MUST contain the time of creation of the enclosing AuthN Response - Assertion.
-SessionIndex 0..1 Conditional, MUST contain the same TransientID as NameID. Is used to uniquely identify a session in case of a federated logout-request see Federated Logout-request message.

NOTE: For future proof better add SessionIndex element which will probably replace @NameID for LogOut request.
-AuthnContext 1 MUST be included.
--AuthnContextClassRef 1 MUST contain the LoA at which authentication took place. Contains the obtained effective Level of assurance, see below under LoA.
‑‑AuthenticatingAuthority 0..n MUST contain the EntityID(s) of all authorities that were involved in the authentication and representation except for the assertion issuer.
AttributeStatement 0..1 Conditional. MUST be included if StatusCode is urn:oasis:names:tc:SAML:2.0:status:Success. MUST NOT be included otherwise. MUST contain a single attributestatement in accordance with the section Attributestatement below and the rules for processing an AuthN Response.
Advice 1 MUST contain the original assertions received from the AD and BVD (if applicable) that were involved in processing the AuthN Request message.
-Assertion 1..n Contains the original Assertion elements this assertion is composed of:
MUST contain the original AD Assertion.
MAY contain the original Assertion of the BVD in case of representation.
7.1.2.4.4.1 Audience restriction - DV

The AudienceRestriction element in the AuthN Response - Assertion must be checked in terms of content. An AuthN Response - Assertion may only be processed if the AudienceRestriction contains the EntityID of the recipient.

The values for DVs included in Audience are reflected in the Recipient attribute of the EncryptedID element in the Attributestatement. This does not apply to the LC or RD that is only included in the AudienceRestriction. The LC or RD is not, after all, an entity which may receive identities.

7.1.2.4.4.2 Level of assurance validation

The AuthnContextClassRef in the AuthN Response - Assertion always states the authentication level at which the citizen has authenticated himself. DV's MUST be prepared for the AuthnContextClassRef to contain a higher LoA than the requested LoA. DV's MUST accept authentications with a level equal to or higher than the minimum level registered for the Service in the Service Catalog. DV must configure minimum LoA for the Service when providing information in the onboarding process. The AD is responsible for providing the correct LoA for a given authentication request (equal to or higher than the LoA registered for the Service in the Service Catalog)

7.1.2.4.4.3 SubjectConfirmation - DV

The SubjectConfirmation exists in a Subject and is used to hold a bearer confirmation in a AuthN Response - Assertion to an AuthN Request message, to conform to the WebSSO profile. In case a relying party is requesting authentication of an EU according to the SAML Web SSO profile, a bearer SubjectConfirmation (see [SAML2.PROFILES], §3.3 and §4.1.4) must be provided. The NotOnOrAfter in the SubjectConfirmationData element limits the time during which the AuthN Response - Assertion result MAY be used to establish an authenticated session for the EU using the AuthN Response - Assertion. The NotOnOrAfter is initially set to +2 minutes relative to the time of issuance of the enclosing AuthN Response - Assertion. These values can be changed however in time. The dv-authn-response-assertion/NotBefore attribute MUST NOT be used.

Element/@Attribute 0..n Description
SubjectConfirmation 1 Allows for association of client with assertion to conform to the SAML Web SSO profile.
-@Method 1 MUST contain the value urn:oasis:names:tc:SAML:2.0:cm:bearer.
SubjectConfirmationData 1 MUST be included.
--@NotOnOrAfter 1 A time instance at which the subject can no longer be confirmed.
--@Recipient 1 The assertion consumer Service URL of the immediate requester to which an attesting entity can present the assertion.
--@InResponseTo 1 The ID of the AuthN Request message this AuthN Response - Assertion is in response to.
7.1.2.4.4.4 Conditions

The NotBefore and NotOnOrAfter in the Conditions element limit the time during which the AuthN Response - Assertion is considered valid within a prior established authenticated EU session based on this AuthN Response - Assertion. The value of these attributes should be aligned with the maximum session duration (which may be dependent on the LoA) and typically is much longer than the validity of the SubjectConfirmation .

7.1.2.4.5 AttributeStatement - DV

The AuthN Response - Assertion when present MUST contain an attributestatement. An attributestatement contains one or more Attribute elements and MUST contain exactly one Attribute with @Name="urn:nl-eid-gdi:1.0:ActingSubjectID". It MAY contain exactly one Attribute element with @Name="urn:nl-eid-gdi:1.0:LegalSubjectID" indicating representation. Both ActingSubjectID and LegalSubjectID Attributes MUST contain one or more AttributeValues for one or more Recipients (e.g. DV). And these Recipients must be included in the AudienceRestriction element.

Element/@Attribute 0..n Description
AttributeStatement 1 MUST be included.
-Attribute 1..n See the tables below for details.
--@Name 1 MUST contain the type of the attribute.
--AttributeValue 1..n The Attribute MUST contain one or more AttributeValues.
7.1.2.4.6 EncryptedID

Both ActingSubjectID as LegalSubjectID (Attribute with @Name="urn:nl-eid-gdi:1.0:ActingSubjectID" respectivly @Name="urn:nl-eid-gdi:1.0:LegalSubjectID") are unencrypted Attributes and MUST contain one or more AttributeValues. Each of these AttributeValues MUST contain exactly one EncryptedID element.

Element/@Attribute 0..n Description
EncryptedID 1 MUST contain one encrypted NameID element. See below for details.
-EncryptedData 1..n MUST contain the encrypted data containing the XML encrypted NameID which contains the identity.
-EncryptedKey 1..n MUST contain the wrapped decryption keys, as defined by [XML.ENC]. This element MUST include the intended Recipient
--@Recipient 1 The recipient for which this EncryptedID is intended.
This attribute MUST contain an EntityID.

See also: Example EncryptedID

7.1.2.4.6.1 NameID - after decrypting EncryptedID

An EncryptedID MUST contain a SAML NameID after decryption, with the following properties:

  • The @Format attribute MUST be set to urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.
  • The @NameQualifier attribute MUST be populated with the full name of the type of identifying attribute (see Attribute Identifier Types for the @NameQualifier types).
  • The attributes @SPNameQualifier and @SPProvidedID MUST NOT be used.
  • In case more than one certificate is listed for encryption for the recipient in the metadata, the content-encryption-key MUST be encrypted for each certificate. This will result in multiple EncryptedKey each with the same Recipient.

See also: Example NameID (after decryption)

7.1.2.4.6.2 Multiple recipients

SAML and XML-encryption allow for multiple recipients of the same encrypted element. The construct for this is specified in more detail in errata E43 of [SAML2.ERRATA.05]. In case of multiple recipients:

  • each EncryptedKey MUST have a CarriedKeyName equal to the KeyName used in the KeyInfo of the EncryptedData.
  • each EncryptedKey SHOULD have a ReferenceList referring back to the data encrypted with the symmetric key contained.

Upon decryption, elements without an EncryptedKey intended for the decrypting recipient MAY be ignored and EncryptedKey for other recipients of encrypted elements SHOULD be ignored.

7.2 Federated Logout Message specification

7.2.1 DV→RD login & logout

NOTE
Support for federated login and logout may be subject to change in future versions of this specification. DV/LCs which decide to make use of federated login and logout, as supported by this version of the specification, must be prepared to make all the necessary changes to their use of federated login and logout as soon as a later version of the specification mandates such changes.

Support for federated login and logout in future versions of this specification will adhere to policies that are expected to emerge from the broader discussion about federated login and logout in the context of the eIDAS regulation.

Most notably, support for IdP AD initiated logout may become mandatory in a future version of this specification.

7.2.1.1 DV Federated Login

Federated Login via a SSO federation is only supported for multiple connections (websites) of a single DV. Furthermore, DigiD does not support SSO federation between [DigiD SAML3.x] and [eID SAML4.4] (or later) connections.

A DV who wants to grant access to his services through SSO can do so via the SSO service from RD. The DV then participates in an SSO federation which may include several websites of the DV who all want to use the SSO functionality that is offered within the SSO federation. Details on the SSO service are provided by RD. In a number of cases, the EU is still asked to provide his credentials:

  1. The Level of Assurance LoA that the DV website requests may be higher than the level of reliability that is stored in the existing SSO session.
  2. The existing SSO session can apply to a different SSO federation than the DV website is a member of.
  3. The DV website can include the ForceAuthn element in the authentication request, with the value True. If a value is not provided or the element is omitted, the default is "False"
  4. The existing SSO session has expired.
7.2.1.2 DV→RD logout Request - Diagram

A DV or LC can send this message to RD when an EU logs out at an DV. A RD can send this message to an AD.

Sender Recipient
DV RD
LC RD
ADRD back-channel-channelRD front-channel-channelDV / LCUser AgentADRD back-channel-channelRD front-channel-channelDV / LCUser AgentOut of Scope: see RD→AD/BVDlocal logout1LogoutRequest2LogoutRequest3456LogoutResponse7LogoutResponse8
Figure 9 LogoutRequest DV/LC - RD

Only SP (DV) initiated logout is supported by RD. On receiving a logout request (1) a DV which participates in a SSO federation MUST send a Logout request to RD (2b).

This will result in RD to terminate the SSO session if it still was active. As a result, the EU will have to re-authenticate when accessing a DV even if that DV is part of the same SSO federation that was just terminated.

SP initiated logout is limited in the sense that any other active SSO originated sessions with DV's is not actively terminated upon receipt of a SP (DV) initiated logout message. Sessions with other active DV's within the same federation will continue to be active until the local DV session times out or the EU logs out of the DV.

7.2.1.3 DV→RD logout Request - Message
Element/@Attribute 0..n Description
@ID 1 Unique message attribute
@Version 1 Version of the SAML protocol. The value MUST be '2.0'.
@IssueInstant 1 Time at which the message was created.
@Destination 1 URL of the recipient on which the message is offered.
Signature 1 MUST contain the Digital signature of the sender for the enveloped message (@Algoritm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"). MUST contain a KeyInfo element with either a KeyName or X509Certificate elements. See Signature.
NameID 1 MUST contain the @NameID NameID element of the original Assertion.
SessionIndex 0..1 Conditional, MUST contain the TransientID SessionIndex element of the original Assertion.
Issuer 1 MUST contain the of the sender.
7.2.1.4 DV←RD logout Response - Diagram

In response to a Logout Request message the RD will send this message to the DV or LC, or a AD will send this message to the requesting RD.

Sender Recipient
RD DV
RD LC
ADRD back-channel-channelRD front-channel-channelDV / LCUser AgentADRD back-channel-channelRD front-channel-channelDV / LCUser AgentOut of Scope: see RD→AD/BVDlocal logout1LogoutRequest2LogoutRequest3456LogoutResponse7LogoutResponse8
Figure 10 LogoutResponse DV/LC - RD
7.2.1.5 DV←RD logout Response - Message
Element/@Attribute 0..n Description
@ID 1 Unique message attribute
@Version 1 Version of the SAML protocol. The value MUST be 2.0.
@IssueInstant 1 Time at which the message was created.
@Destination 1 URL of the recipient on which the message is offered.
@InResponseTo 1 ID of the Logout Request message for which this Logout Response message is the answer.
Signature 1 MUST contain the Digital signature of the sender for the enveloped message (@Algoritm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"). MUST contain a KeyInfo element with a KeyName element. See Signature.
Issuer 1 MUST contain the EntityID of the sender.
Status 1 MUST contain a StatusCode element with the status of the logout.
-StatusCode 1 MUST be present in a Status element.

7.2.2 RD→AD login & logout

This section is extending the DV/LC→RD SAML Federated login and logout between RD and AD.

A RD that supports SSO to DV s or LCs must propagate logout requests to the correct AD or ADs. The diagram below depicts the flow between a RD and an AD. The encompassing flow, between DV/LC and RD, is out of scope (see [[eID SAML4.4]] for details).

7.2.2.1 RD→AD logout Request - Diagram

A DV or LC can send this message to RD when a user logs out at an DV. A RD can send this message to an AD.

Sender Recipient
RD AD
ADRDDV / LCUAADRDDV / LCUASee DV→RDSee DV→RD123LogoutRequest!4LogoutRequest5terminate SSO session6LogoutResponse7LogoutResponse8910
Figure 11 Logout Response RD -AD
7.2.2.2 RD→AD logout Request - Message

A DV or LC can send this message to RD when a user logs out at an DV. A RD can send this message to an AD. he message is identical to DV/LC→RD SAML Federated logout Request - Message

7.2.2.3 RD←AD logout Response - Diagram

In response to a Logout Request message from RD, an AD will send this message to the requesting RD.

Sender Recipient
AD RD
ADRDDV / LCUAADRDDV / LCUASee DV→RDSee DV→RD123LogoutRequest!4LogoutRequest5terminate SSO session6LogoutResponse7LogoutResponse8910
Figure 12 Logout Response RD -AD
7.2.2.4 RD→AD logout Response - Message

An AD can send this Federated logout response message to the requesting RD. The message is identical to DV/LC→RD SAML Federated logout Response - Message

7.3 Error messages

7.3.1 Toplevel codes

The standard SAML 2.0 error codes are used. For error handling, conformity regarding the interpretation of the status codes as used in the AuthN Response - Assertion element is critical. The following top-level status codes MAY be used:

Status code Description
urn:oasis:names:tc:SAML:2.0:status:Requester This status code is used for errors caused by the initiator of the SAML request. For example, because an assurance level is requested which is not supported by the recipient, or because the request message has expired.
urn:oasis:names:tc:SAML:2.0:status:Responder This status code is used for errors caused by the recipient of the SAML request. For example, because of technical failure or because the recipient does not support requested (optional) functionality.

7.3.2 Second-level status codes

The following second-level status codes MAY be used:

Status code Description
urn:oasis:names:tc:SAML:2.0:status:AuthnFailed This status code is used when a user cannot be authenticated for example because invalid credentials have been provided or the cancel button has been used.
urn:oasis:names:tc:SAML:2.0:status:NoAuthnContext This status code is used when a user cannot be authenticated at the minimum level as specified in the Service Catalog.
urn:oasis:names:tc:SAML:2.0:status:RequestUnsupported This status code is used when a message is correctly formatted by the requester, and understood by the recipient, but that functionality is requested which is not supported by the recipient.
urn:oasis:names:tc:SAML:2.0:status:RequestDenied This status code is used when a SAML responder that refuses to perform a message exchange with the SAML requester, for example because a mandatory signature could not be verified.
urn:oasis:names:tc:SAML:2.0:status:NoSupportedIDP Used to indicate that a RequesterID is not supported by the intermediary.

7.3.3 Cancelling

During the process of authenticating and authorizing, an EU may cancel the process by clicking on the cancel button.

If an EU cancels, the Participant MUST direct the EU automatically to the latest sender of a SAML request, accompanying a valid SAML AuthN Response - StatusMessage including valid SAML status codes (urn:oasis:names:tc:SAML:2.0:status:Responder with urn:oasis:names:tc:SAML:2.0:status:AuthnFailed). A AuthN Response - StatusMessage element MUST be included, containing the exact phrase Authentication cancelled.

If RD receives a cancellation message (from an AD or BVD), it MUST be forwarded to the DV or LC.

If a DV or LC receives a cancellation message (from RD), it MUST indicate to the EU that he is not logged in, and MAY offer the EU the option to re-authenticate.

7.3.4 Attributes not supported

A Participant can receive a message that matches the Interface specifications but cannot be processed by the recipient.

A Participant receiving such a message:

  • MUST show the EU a message indicating that something went wrong (without revealing security sensitive details).
  • MAY offer the EU the option to cancel, in that case the flow continues as stated in Cancelling.

7.3.5 Incorrect message (recoverable)

A Participant can receive a message that matches the interface specifications but cannot be processed by the recipient. The recipient MUST direct the EU to initiator of the SAML request, accompanying a valid SAML AuthN-response message including valid SAML status codes (urn:oasis:names:tc:SAML:2.0:status:Responder with urn:oasis:names:tc:SAML:2.0:status:RequestUnsupported). A AuthN Response - StatusMessage element MUST be included, containing a description of the problem (for example "Level of assurance not supported").

A Participant receiving such a response:

  1. MUST show the EU a AuthN-response message indicating authentication has failed, including the contents of AuthN Response - StatusMessage.

  2. If the Participant is a RD then the RD MUST ask the EU to re-select an AD or BVD or cancel. Except in case of Use Case AD-preselection, then the RD MUST forward the AuthN-response message to the DV or LC.

7.3.6 Incorrect message (non-recoverable)

A Participant can receive an invalid formatted message. Examples:

  • Not a valid SAML message
  • XML does not match XSD

Alternatively, the message can be valid according to SAML specifications, but it does not match the Interface specifications. Examples:

Such messages are the result of either an incorrect implementation by a Participant, or an attempt to hack the system. The EU cannot always be send back to the requester, because the source of the message is unknown and/or cannot be trusted. If the message is an AuthN-response message, it would not make sense to send the EU back to the responder.

A Participant that receives a AuthN-response message in this category

8. SAML Metadata

8.1 Metadata

Before a SAML connection can be established, the participants must provide each other with configuration data about the connection. This indicates which services, locations of services and certificates are used for the connection.

8.1.1 TLS certificates in metadata

For TLS certificates see technical requirements on Signature and on Signing, encryption algorithms and hash functions

8.1.2 General processing requirements

Processing requirements for the consuming parties:

  • The metadata MUST be validated by the consuming parties
  • The consuming parties MUST NOT use the metadata if the validation is not successful

8.2 DV Metadata

8.2.1 DV→RD Metadata

Published by Consumed by
DV that connects to RD directly RD

This section describes the metadata that a DV with a direct connection to RD (not using a LC) must provide. This metadata MAY be published on a location known to RD or MAY be provided to RD by any other means supported.

See also Example SAML-metadata DV for RD

Element/@Attribute 0..n Description
EntityDescriptor 1 The metadata MUST contain one EntityDescriptor with one SPSSODescriptor element.
-@ID 1 A document-unique identifier for the element, typically used as a reference point when signing.
-@entityID 1 Specifies the unique identifier of the SAML entity whose metadata is described by the element's contents. Contains the entityid of the DV.
-@validUntil 0..1 MAY contain a datetime at which the metadata expires.
If validUntil is expired, the metadata is considered invalid.
Either validUntil or cacheDuration MUST be present. (following OASIS specification [SAML2.METADATA])
-@cacheDuration 0..1 MAY contain cacheduration. Every Participant is advised to check for new Metadata after the given period.
Either validUntil or cacheDuration MUST be present. (following OASIS specification [SAML2.METADATA])
-Signature 1 MUST contain the Digital signature of the DV to verify the integrity of this Metadata and MUST be generated with a (private signing key associated with a) PKIoverheid public-key certificate which contains the same OIN as used in the entityID. Also see technical requirements on Signature and on Signing, encryption algorithms and hash functions
-SPSSODescriptor 1
--@AuthnRequestsSigned 1 MUST be set to true.
‑‑@protocolSupportEnumeration 1 MUST be set to urn:oasis:names:tc:SAML:2.0:protocol
--@WantAssertionsSigned 1 MUST be set to true.
--KeyDescriptor 2..n MUST contain KeyDescriptor element(s) that allow for signing of SAML messages and authenticating a TLS connection. This can be achieved by inclusion of 2 KeyDescriptor element with @use="signing" or a single certificate with @use="signing" that supports both functions. A second KeyDescriptor MAY be present for both of these keys to support certificate rollover. SAML message signing and TLS functions MAY be combined in a single certificate or in separate certificates.
MUST contain at least 1 KeyDescriptor element that supports encryption (@use="encryption"). A second KeyDescriptor with @use="encryption" MAY be present to support certificate rollover.
Also see technical requirements on Signing, encryption algorithms and hash functions
---KeyInfo 1
----KeyName 1 Contains the name which identifies the key.
----X509Data 1 Contains the encoded PKIOverheid X509 certificate with the public key.
--SingleLogoutService 0..n Conditional: MUST be present if the DV supports SSO. Describes the endpoint used to log the EU out of its current session if participating in a SSO session.
---@Binding 1 MUST contain the appropriate binding for the endpoint. The binding parameter denotes the type of binding used. This is an urn relating to [SAML2.BINDINGS]. At least one SingleLogoutService MUST contain the HTTP-POST binding.
---@Location 1 MUST contain the URL of the SingleLogoutService endpoint for the Binding.
--AssertionConsumerService 1..n Must contain at least one URL to which the EU will be redirected after authentication. If more than one is included one MUST contain the attribute @isDefault with value true.
--AttributeConsumingService 0..n Conditional: MUST be present when DV uses a correspondingAttributeConsumingServiceIndex in the DV AuthnRequest Message. MUST NOT be present in any other case or by any other Participant role. <br>When used, AttributeConsumingService MUST contain 1 or more elements that describe the Service requested using an @Index to a Service Definition registered with Service Catalog kept by RD.
---@Index 1 MUST be present.
---@isDefault 0..1 MUST be present if more than one Index is specified in the metadata. MAY only be present once. If present indicates the default AttributeConsumingService which is used when no AttributeConsumingServiceIndex was referenced in the AuthN Request Message. It is advised to always include an AttributeConsumingServiceIndex in the AuthN Request Message.
---ServiceName 1..n One or more language-qualified names for the service. Only one descriptor per language MUST be present.
---RequestedAttribute 1..n At least one RequestedAttribute element MUST be present with @name="urn:nl-eid-gdi:1.0:ServiceUUID".
----AttributeValue 1 MUST contain the ServiceUUID to be used for this authentication. The ServiceUUID must be pre-registered with Service Catalog kept by RD.

8.2.2 LC→RD metadata

Published by Consumed by
LC RD

This section describes the metadata the LC publishes for the RD. The LC MUST provide the metadata for each DV it supports. The metadata MUST be signed by the LC. The metadata of all DVs using an LC MUST be supplied as a single file and MAY additionally be supplied as individual files.

This section describes the layout of the metadata. The XML schema for the Metadata is that of [SAML2.METADATA].

See also Example SAML-metadata LC for RD

Element/@Attribute 0..n Description
EntitiesDescriptor 1 Required element to start metadata containing multiple EntityDescriptors.
-@ID 1 A document-unique identifier for the element, typically used as a reference point when signing.
-@validUntil 0..1 MAY contain a datetime at which the metadata expires.
If validUntil is expired, the metadata is considered invalid.
Either validUntil or cacheDuration MUST be present. (following OASIS specification [SAML2.METADATA]).
-@cacheDuration 0..1 MAY contain cache duration. Consumers are advised to check for new metadata after the given period.
Either validUntil or cacheDuration MUST be present. (following OASIS specification [SAML2.METADATA]).
-Signature 1 MUST contain the Digital signature of the LC to verify the integrity of this Metadata and MUST be generated with a (private signing key associated with a) PKIoverheid public-key certificate which contains the same OIN as used in the entityID. Also see technical requirements on Signature and on Signing, encryption algorithms and hash functions
-EntityDescriptor 1..n MUST contain the EntityDescriptor of the LC, see LC EntityDescriptor.
MUST contain the EntityDescriptors of all DV's the LC supports, see DV EntityDescriptor.
8.2.2.1 LC→RD EntityDescriptor
Element/@Attribute 0..n Description
@ID 1 A document-unique identifier for the element, typically used as a reference point when signing.
@entityID 1 MUST contain the entityid of the LC.
@validUntil 0..1 SHOULD NOT be used as either validUntil or cacheDuration is already present at EntitiesDescriptor level.
MAY contain a datetime at which the metadata expires.
If validUntil is expired, the metadata is considered invalid.
@cacheDuration 0..1 SHOULD NOT be used as either validUntil or cacheDuration is already present at EntitiesDescriptor level.
MAY contain cacheduration. RD is advised to check for new metadata after the given period.
@Signature 0..1 SHOULD NOT be used as the metadata is already signed at the EntitiesDescriptor level.
If used it MUST be generated with the private signing key with an associated PKIoverheid public-key certificate which contains the same OIN as the entityid in the EntityDescriptor.
@SPSSODescriptor 1 The SPSSODescriptor implements profiles specific to service providers.
-@AuthnRequestsSigned 1 Must be set to true.
-@WantAssertionsSigned 1 Must be set to true.
‑@protocolSupportEnumeration 1 MUST be set to: urn:oasis:names:tc:SAML:2.0:protocol.
-KeyDescriptor 1..4 MUST contain KeyDescriptor element(s) that allow for signing of SAML messages and authenticating a TLS connection. This can be achieved by inclusion of 2 KeyDescriptor element with @use="signing" or a single certificate with @use="signing" that supports both functions. A second KeyDescriptor MAY be present for both of these keys to support certificate rollover. SAML message signing and TLS functions MAY be combined in a single certificate or in separate certificates.

NOTE:Also see technical requirements on Signing, encryption algorithms and hash functions
--KeyInfo 1
---KeyName 1 Contains the name which identifies the key. MAY be any string. Common practice is using the SHA1 fingerprint stripped of colons.
---X509Data 1 Contains the encoded X509 certificate with the public key.
-SingleLogoutService 0..n Conditional: MUST be present if the LC supports SSO. Describes the endpoint used to log the EU out of its current session if participating in a SSO session.
--@Binding 1 MUST contain the appropriate binding for the endpoint. The binding parameter denotes the type of binding used. This is a urn relating to [SAML2.BINDINGS]. At least one SingleLogoutService MUST contain the HTTP-POST binding.
--@Location 1 MUST contain the URL of the SingleLogoutService endpoint for the @Binding.
-AssertionConsumerService 1..n Must contain at least one URL to which the EU will be redirected after authentication.
--@Binding 1 The binding parameter denotes the type of binding used. This is a urn relating to [SAML2.BINDINGS]
At least one AssertionConsumerService binding MUST be set to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact. Other bindings are NOT supported.
--@Location 1 The URL of the SAML endpoint
--@Index 1 The index of the binding, MUST be unique for all AssertionConsumerService elements.
--@isDefault 0..1 If more than one AssertionConsumerService elements are included, one of these elements MUST be flagged as default by setting the isDefault XML attribute with value true.
8.2.2.2 DV→RD EntityDescriptor

For each DV supported by an LC the following metadata must be included in the LC metadata.

Element/@Attribute 0..n Description
@ID 1 A document-unique identifier for the element, typically used as a reference point when signing.
@entityID 1 Specifies the unique identifier of the SAML entity whose metadata is described by the element's contents. MUST contain the entityid of the DV.
@validUntil 0..1 SHOULD NOT be used as either validUntil or cacheDuration is already present at EntitiesDescriptor level.
MAY contain a datetime at which the metadata expires.
If validUntil is expired, the metadata is considered invalid.
@cacheDuration 0..1 SHOULD NOT be used as either validUntil or cacheDuration is already present at EntitiesDescriptor level.
MAY contain cacheduration. RD is advised to check for new metadata after the given period.
Signature 0..1 SHOULD NOT be used as the metadata is already signed at the EntitiesDescriptor level.
If used it MUST be generated with the private signing key with an associates PKIoverheid public-key certificate which contains the same OIN as the entityid in the DV EntityDescriptor. The public key certificate MUST be present in the KeyDescriptor metadata. MUST contain a KeyInfo element with a KeyName or X509Certificate elements.
SPSSODescriptor 1
@‑@protocolSupportEnumeration 1 Set to: urn:oasis:names:tc:SAML:2.0:protocol.
-KeyDescriptor 1..2 MUST contain at least 1 KeyDescriptor element that supports encryption (@use="encryption"). A second KeyDescriptor with @use="encryption" MAY be present to support certificate rollover.
Also see technical requirements on Signing, encryption algorithms and hash functions
--KeyInfo 1
---KeyName 1 Contains the name which identifies the key. MAY be any string. Common practice is using the SHA1 fingerprint stripped of colons.
---X509Data 1 Contains the encoded X509 certificate with the public key.
-AssertionConsumerService 1..n According to saml-metadata-2.0 MUST contain at least one URL to which the EU will be redirected after authentication. MUST contain only one entry. MUST contain a copy of the AssertionConsumerService element in the LC’s EntityDescriptor. This entry will be ignored as the AssertionConsumerService definitions in the LC EntityDescriptor MUST be used.

8.2.3 RD→DV/LC metadata

Published by Consumed by
RD DV that connect directly with RD, LC

RD publishes metadata in accordance with [SAML2.METADATA] with one EntityDescriptor element. The metadata is signed in accordance with the SAML signature.

See also Example SAML-metadata a RD for DV

Element/@Attribute 0..n Description
EntityDescriptor 1
-@ID 1 A document-unique identifier for the element, typically used as a reference point when signing.
-@entityID 1 Specifies the unique identifier of the SAML entity whose metadata is described by the element's contents. Contains the entityid of RD.
-@validUntil 0..1 MAY contain a datetime at which the metadata expires.
If validUntil is expired, the metadata is considered invalid.
Either validUntil or cacheDuration MUST be present. (following OASIS specification [SAML2.METADATA])
-@cacheDuration 0..1 MAY contain cache duration. DV or LC is advised to check for new metadata after the given period.
Either validUntil or cacheDuration MUST be present. (following OASIS specification [SAML2.METADATA])
-Signature 1 MUST contain the Digital signature of the RD to verify the integrity of this Metadata and MUST be generated with a (private signing key associated with a) PKIoverheid public-key certificate which contains the same OIN as used in the entityID. Also see technical requirements on Signature and on Signing, encryption algorithms and hash functions
-IDPSSODescriptor 1
‑‑@protocolSupportEnumeration 1 Set to: urn:oasis:names:tc:SAML:2.0:protocol
--@WantAuthnRequestsSigned 1 Set to true indication that AuthnRequest messages MUST be signed by the DV or LC.
--KeyDescriptor 1..n Contains at least 1 KeyDescriptor element with @use="signing"
---KeyInfo 1
----KeyName 1 Contains the name which identifies the key.
----X509Data 1 Contains the encoded X509 certificate with the public key.
--ArtifactResolutionService 1..n The ArtifactResolutionService MUST be implemented at least once per service.
---@Binding 1 The binding parameter denotes the type of binding used. In the ArtifactResolutionService this is the SAML-SOAP binding only. The value of this attribute is a urn relating to [SAML2.BINDINGS].
---@Location 1 The URL of the SAML artifact resolution endpoint
---@Index 1 The index of the binding, MUST be unique for all ArtifactResolutionService elements
--SingleSignOnService 1..n One or more elements of type EndpointType that describe endpoints that support the profiles of the Authentication Request protocol defined in [SAML2.PROFILES].
---@Binding 1 The binding parameter denotes the type of binding used. In the SingleSignOnService this is the HTTP-POST binding only. The value of this attribute is an urn relating to [SAML2.BINDINGS].
---@Location 1 The URL of the SAML SingleSignOnService endpoint
--SingleLogoutService 1..n Describes the endpoint used to log the EU out of its current session if participating in a SSO session.
---@Binding 1 MUST be set to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST. Other bindings are NOT supported.
---@Location 1 The URL of the SAML endpoint

9. Technical requirements and recommendations

9.1 Signing, encryption algorithms and hash functions

ST-SAML does not support SHA1 except for the padding function (xmldsig # rsa-sha1). Only RSA is supported for signing as PKIoverheid certificates do not support other methods. For signing, the following list of signing algorithms is supported:

Signing algorithm urn
RSAwithSHA256 http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
RSAwithSHA384 http://www.w3.org/2001/04/xmldsig-more#rsa-sha384
RSAwithSHA512 http://www.w3.org/2001/04/xmldsig-more#rsa-sha512

(source: [XML.SIG] § 6.1)

At minimum, SHA256 must be used to calculate the message digest (<ds:DigestMethod Algorithm = "http://www.w3.org/2001/04/xmlenc#sha256" />).

Digest algorithm urn
SHA256 http://www.w3.org/2001/04/xmlenc#sha256
SHA384 http://www.w3.org/2001/04/xmldsig-more#sha384
SHA512 http://www.w3.org/2001/04/xmlenc#sha512

(source: [XML.SIG] § 6.1)

All SAML messages that must be signed, must be signed with an Enveloped Signature Transform http://www.w3.org/TR/2013/REC-xmldsig-core1-20130411/#enveloped-signature

Participants are required to fully check signatures and associated messages according to standards including checking the correctness of the sender. This also applies to Metadata.

To guarantee authenticity, integrity and non-repudiation, each message described MUST be provided with a digital signature from the message sender. The message recipient MUST validate all of the digital signatures - except signatures in an Assertion/Advice as they are intended for evidence - in the message before processing it according to the processing rules required by PKIoverheid per Certificate Practice Statements (CPS) including checking the validity of the certificate.

The following requirements apply to generating digital signatures:

9.2 Signature

Each Signature element in SAML messages generated by a DV or LC (see Signature in DV AuthN-request message) and in the DV or LC entries in the Service Catalog (see Signature in DV metadata) MUST contain either a KeyInfo element with a X509Certificate element OR a KeyName element containing a key name. The use of KeyName is preferred as this limits the amount of data exchanged. The X509Certificate or KeyName MUST match a X509Data or KeyName in the DV metadata KeyDescriptor element with @use="signing".

Each Signature element in SAML messages generated by a RD (or any other Participant) and in the Metadata MUST contain a KeyInfo element with a KeyName element containing a key name that corresponds to a KeyName in a KeyDescriptor element in the Metadata for that Participant .

Certificates used to verify a Signature MUST be retrieved from the Participant's verified Metadata. The X509Certificate or KeyName in the KeyInfo of the Signature MUST only be used to retrieve the corresponding certificate from the Participant's verified Metadata.

9.3 Encryption

Encryption is used to guarantee confidentiality. Encryption in combination with SAML is achieved via XML-encryption (see EncryptedID). In case encryption MAY or MUST be used, one MUST use the block encryption algorithms identified by the following URI in conjunction with the use of XML Encryption

algorithm urn
AES-256 http://www.w3.org/2001/04/xmlenc#aes256-cbc

For asymmetric encryption, used to encrypt keys, the RSA algorithm in combination with OAEP padding and a SHA digest MUST be used, as described at http://www.w3.org/TR/xmlenc-core1/#sec-RSA-OAEP. The SHA1 version MUST be used (http://www.w3.org/2009/xmlenc11#mgf1sha1).

9.4 TLS transport

RD requires that a service provider always protects http traffic with TLS v1.2 or higher in accordance with the NCSC directive with 'good' assessment (ICT security guidelines for Transport Layer Security (TLS)). The certificate used for this must be issued under PKIoverheid, and the certificate must have a key length or at least 2048 bits.

For the Back Channel between RD and the DV or LC, both parties must use a PKIoverheid certificate and mutual authentication is mandatory. This is also called two-sided or mutual TLS.

9.5 NotBefore and NotOnOrAfter

DVs and LCs must respect the NotBefore and NotOnOrAfter parameters in the message elements and reject messages that do not comply and cancel the authentication. With a re-authentication, the entire protocol handling must take place.

For this it is advisable to use NTP servers (for example from the nl.pool.ntp.org collection of NTP servers). This measure is taken because lag can make the web service vulnerable to certain attacks on the authentication protocol.

9.6 Levels of assurance

The Levels of Assurance (LoA) that are supported in the interface are listed in Level of Assurance.

9.7 Local session

The DV is responsible for keeping track of the local EU session. This session MUST be terminated after at most 15 minutes inactivity.

The DV must recognize replay attacks and ward off these attacks.

If the DV uses cookies to manage sessions, the "Secure" and "HttpOnly" parameters must be used.

NOTE
The setting of the SameSite policy still has to be determined as browsers show inconsistent behavior.

9.8 RelayState

DVs may provide a RelayState for their own session monitoring. RD returns the RelayState value provided without any verification. The monitoring of the content and integrity of the RelayState must be done by the service provider (DV).

The SAML standard uses a maximum of 80 bytes for the RelayState (see the SAML standard).

9.9 EU interaction

When a DV forwards an EU to RD this must be done in such a way that it is clear to the EU on which website they are and that they can actually check this. That is why the following requirements apply:

  1. The EU must be redirected to RD in the same screen that the EU clicked on "Log in to DigiD".
  2. The EU must see a browser window with the full address bar. This allows an EU to see on which website he is entering his data. The EU can check this by inspecting the certificate (green lock).
  3. It is not allowed to invoke RD in a frame or iframe, or to embed these websites in another way in a webpage of the DV.

The DV must decide on the basis of the Assertion in the AuthN-response whether an EU can gain access to the Service or, in the case of re-authentication (applicable to SAML SSO), may continue his session.

If the status in the Assertion is not successful or the EU does not have the required LoA in the AuthnContext of the Assertion in the AuthN-response then:

  1. The DV or LC MUST immediately end the current session of the EU.
  2. SHOULD show an appropriate message (see SAML Error codes).

10. Type definitions

This page and underlying pages describe identifier types which are used by ST-SAML

10.1 Attribute identifier types

Stelsel Toegang SAML v1.0 specification describes the following attribute identifier types

Attribute urn Remarks
BSN urn:nl-eid-gdi:1.0:id:legacy-BSN BSN. encoded in 9-digits, padded with leading 0 if needed.
Example: 123456789 or 012345678.
BSN urn:nl-eid-gdi:1.0:id:BSN Encrypted Identity (see [BSNk.DEC], Encrypted structures )
Pseudonym urn:nl-eid-gdi:1.0:id:Pseudonym Encrypted Pseudonym (see [BSNk.DEC] Encrypted structures)

The following attributes may be supplied additionally, only through ETD (see https://afsprakenstelsel.etoegang.nl/Startpagina/as/identificerende-kenmerken )

10.2 Attribute representation types

The table shows the allowed representationTypes in URN format that are supported by the BVD (BVD-OG) and can be found in the Attribute Statement of the AuthN Response - Assertion as a unencrypted with @name Name="urn:nl-eid-gdi:1.1:RepresentationType". See attribute for legal representation

representation-types urn Sector description
Zorg_Volledig_Gezag_Kind urn:nl-eid-gdi:1.1:RT:Zorg_Volledig_Gezag_Kind health care Specific Parental authority for children under 12 years old in healthcare

10.3 EntityID Format

The format of value of the @entityID attribute is: urn:nl-eid-gdi:1.0:<ROLE>:<OIN>:entities:<index>

<OIN>

The OIN of the organization.

<ROLE>

Indication of the role of the entity:

  • AD
  • DV
  • BVD
  • LC
  • RD

<index>

The <index> is a number with 4 positions between 0000 and 8999 that can be selected by the Participant to define different endpoints (in the Metadata). Numbers between 9000 and 9999 are reserved for test systems.

10.4 Level of Assurance

The table shows the four Levels of Assurance supported by ST-SAML and the corresponding urn’s which are used in the SAML messages.

LoA urn
Basis http://eID.logius.nl/LoA/basic
Midden http://eidas.europa.eu/LoA/low
Substantieel http://eidas.europa.eu/LoA/substantial
Hoog http://eidas.europa.eu/LoA/high

A. Example SAML messages

This section is non-normative.

A.1 Example - AuthnRequest

A.2 Example - AuthnRequest using Extensions

A.3 Example - AuthnRequest with Representation

A.5 Example - ArtifactResolve

A.6 Example - ArtifactResponse

A.7 Example - ArtifactResponse with Representation

A.8 Example - LogoutRequest

A.9 Example - LogoutResponse

B. Example SAML metadata

This section is non-normative.

B.1 Example - Metadata DV for RD

B.2 Example - Metadata LC for RD

B.3 Example - Metadata RD for DV

C. List of Figures

D. Index

D.1 Terms defined by this specification

D.2 Terms defined by reference

E. References

E.1 Normative references

[BSNk.DEC]
BSNk PP technische specificaties. Logius. URL: https://gitlab.com/logius/bsnk/bsnk-techspecs/bsnk/-/raw/main/BPTSlive.pdf
[DigiD SAML3.x]
DigiD SAML3.x - legacy SAML specification for DigiD. LOGIUS. URL: https://www.logius.nl/domeinen/toegang/digid/documentatie/koppelvlakspecificatie-digid-saml-authenticatie
[eID SAML4.4]
eID SAML4.4 specification for DigiD. LOGIUS. URL: https://logius.gitlab.io/eid-saml/4.4/index.html
[eID SAML4.5]
eID SAML4.5 specification for DigiD. LOGIUS.
[NCSC.TLS]
ICT-beveiligingsrichtlijnen voor Transport Layer Security (TLS). NCSC. URL: https://www.ncsc.nl/documenten/publicaties/2019/mei/01/ict-beveiligingsrichtlijnen-voor-transport-layer-security-tls
[NORA]
Nederlandse Overheid Referentie Architectuur. URL: https://www.noraonline.nl/wiki/NORA_online
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[SAML2]
Security Assertion Markup Language (SAML) V2.0. OASIS. URL: https://www.oasis-open.org/standard/saml/
[SAML2.BINDINGS]
Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0 – Errata Composite. OASIS. URL: https://groups.oasis-open.org/higherlogic/ws/public/download/56779/sstc-saml-bindings-errata-2.0-wd-06.pdf
[SAML2.CORE]
Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 – Errata Composite. OASIS. URL: https://groups.oasis-open.org/higherlogic/ws/public/download/56776/sstc-saml-core-errata-2.0-wd-07.pdf
[SAML2.ERRATA.05]
SAML Version 2.0 Errata 05. OASIS. URL: https://docs.oasis-open.org/security/saml/v2.0/sstc-saml-approved-errata-2.0.html
[SAML2.METADATA]
Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0 – Errata Composite. OASIS. URL: https://groups.oasis-open.org/higherlogic/ws/public/download/56785/sstc-saml-metadata-errata-2.0-wd-05.pdf
[SAML2.PROFILES]
Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0 – Errata Composite. OASIS. URL: https://groups.oasis-open.org/higherlogic/ws/public/download/56782/sstc-saml-profiles-errata-2.0-wd-07.pdf
[SAML2.TO]
Security Assertion Markup Language (SAML) V2.0 Technical Overview. OASIS. URL: https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html
[ST-SAML1.0]
Stelsel Toegang SAML v1.0 specification. LOGIUS. URL: https://logius.gitlab.io/digid-combiconnect
[XML.C14N.EXCL]
Exclusive XML Canonicalization. W3C. URL: https://www.w3.org/TR/xml-exc-c14n/
[XML.ENC]
XML Encryption Syntax and Processing. W3C. URL: https://www.w3.org/TR/2002/REC-xmlenc-core-20021210/
[XML.SIG]
XML Signature Syntax and Processing. W3C. URL: https://www.w3.org/TR/xmldsig-core/
Logius Guide - Draft