DV-HM sequence diagram

This page describes the messages for the interface specification between a Dienstverlener (DV) (service provider) and an 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".


The interface specification described in this document is used to implement the use case GUC1 Gebruiken eToegang als dienstafnemer (Use eToegang as service consumer) and MUST (with the exception of alternative Bindings) be implemented by every  and offered to their customers, the DVs. This is in order to prevent lock-in and enables middleware suppliers to write generic code that can be used by all s.

In the interface described here, the use case GUC1 Gebruiken eToegang als dienstafnemer is populated with an SAML 2.0 AuthnRequest and Response.

The specific contents of these messages is described below. A column in a message description that starts with 'SAML:' indicates that this is a standard value within the official SAML specification. A value that starts with '' indicates that the value is specific to .

This section describes regular Authentication Requests.

Element/@Attribute0..nDescription

@ID

1

SAML: Unique message characteristic. MUST identify the message uniquely within the scope of the sender and receiver for a period of at least 12 months.

@Version

1

SAML: Version of the SAML protocol. The value MUST be '2.0'.

@IssueInstant

1

SAML: Time of issuing of the request.

@Destination

1

SAML: URL of the HM on which the message is offered. MUST match the HM's metadata.

@Consent

0..1

: MAY be included. When Consent is included, the default value MUST contain urn:oasis:names:tc:SAML:2.0:consent:unspecified.

@ForceAuthn

0..1

: The value 'true' indicates that an existing single sign-on session MUST NOT be used for the request in question.  If the value is 'false' or empty or the specification is missing, the AD MUST use an existing SSO session if one exists,  and is applicable (see Single sign-on and user sessions RFC2390).

@IsPassive

0..1

: MAY be included. If IsPassive is included, the value MUST be 'false'.

@ProtocolBinding

0..1

SAML: Specifies the used binding. MUST only be used when an @AssertionConsumerServiceURL is used, MUST NOT be used in combination with an @AssertionConsumerServiceIndex.

@AssertionConsumerServiceIndex

0..1

: This attribute element specifies the URL to which the HM sends the response for the DV. If present this index MUST refer to an endpoint of an AssertionConsumerService in the DV metadata for HM.

MUST NOT be present if @AssertionConsumerServiceURL is present.

If neither @AssertionConsumerServiceIndex or @AssertionConsumerServiceURL is present, the HM MUST send the response to the endpoint in the metadata that is marked with 'isDefault=true'

@AssertionConsumerServiceURL

0..1

SAML: If present, URL MUST point to a SAML endpoint acknowlegded in the DV metadata for HM. If present, the participant MUST check whether the @AssertionConsumerServiceUrl is included in the DV's DV metadata for HM. If it is not included in the metadata, the participant MUST reject the message with the status code RequestDenied.

MUST NOT be present if @AssertionConsumerServiceIndex is present.

@AttributeConsumingServiceIndex

0..1

SAML: If present, MUST refer to an AttributeConsumingService in the DV's metadata. If absent, the AttributeConsumingService marked as default in the DV metadata for HM SHOULD be used.

The AttributeConsumingService MUST contain exactly one attribute with a name that is the same as a long formatted ServiceID. The AttributeConsumingService MAY contain attributes to be requested.

Multiple AttributeConsumingService elements MAY be present in the DV metadata for HM and can be mapped to the same ServiceID. This allows DVs to request authentication for a single service with varying attributes depending on the context. The union of all attributes that may be queried for a ServiceID MUST be declared in the Service Catalog.

An application that cannot pass an AttributeConsumingServiceIndex can now retrieve different services and/or attribute contracts by exchanging metadata between different EntityIDs. 

@ProviderName

0..1

 (DV): MAY contain a more detailed description of the service, complimentary to the entry in the service catalog

 MAY NOT contain personally identifiable information

Issuer

1

: MUST contain the EntityID of the DV.

@NameQualifier0
: MUST NOT be included.
@SPNameQualifier0
: MUST NOT be included.
@Format0
: MUST NOT be included.
@SPProvidedID0
: MUST NOT be included.

Signature

1

: MUST contain the Digital signature of the DV for the envelopping message.

Extensions

0

: MUST NOT be included.

Subject

0

: MUST NOT be included.

NameIDPolicy

0

: MUST NOT be included.

Conditions

0

: MUST NOT be included.

RequestedAuthnContext

0..1

: MAY be used to explicitly request a specific LoA. If specified, the HM summary response will communicate the detailed LoA, rather than SAML 'unspecified'.

If present it MUST be used to request a equal to or lower than the level of assurance specified in the Service catalog. A lower LoA can for instance be used in requests to allow read-only access to services.

If RequestedAuthnContext is absent, then the request will be further processed, using the Level of assurance (AuthnContextClassRef) as specified in the service catalog for the requested service.

@Comparison1MUST use the value 'minimum'.
AuthnContextClassRef1MUST be one of the following requested Level of assurance.

Scoping

0..1

: MUST be included in case an AD is pre-selected by the user at the DV, MUST NOT be included otherwise.

IDPList1MUST be present in case of pre-selection of an AD.
IDPEntry1MUST be present in case of pre-selection of an AD.
@ProviderID1EntityID of the AD selected by the user.
@Name0MUST NOT be present.
@Loc0..1In case an AD has multiple endpoints in the Network metadata, the endpoint selected by the user MUST be provided.

Rules for processing requests

A requesting DV:

  • MUST sign the <AuthnRequest>.
  • MUST request a serviceID that is listed for that ServiceProvider itself in the Service Catalog. Requesting services of other Service Providers is not allowed. A Dienstbemiddelaar (DB) (Service Intermediary) can intermediate another service, if permitted by the Dienstaanbieder (Service Supplier), by indicating this in the Service Catalog (@IntermediatedService in ServiceInstance).
  • MAY use the @AttributeConsumingServiceIndex to reference the service (as specified in the metadata).
  • MAY use the <RequestedAuthnContext> to indicate a requested level of assurance, optionally lower than the LoA listed in the Service Catalogue for the requested Service.
    NB. Using the <RequestedAuthnContext> indicates the DV can accept/process the LoA in the <AuthnContextClassRef> in the response as well. (NB. this may restrict out-of-box-processing by appliances!)
  • MAY pass AD pre-selected for authentication. In this case:
    • the DV MUST use an authentic list (signed by BO/HM) of accredited ADs. The list SHOULD be updated at least once every 15 minutes, the list MUST NOT be older than 30 minutes.
    • the DV MUST show the OrganizationDisplayName of all valid, applicable ADs, in alphabetic order and equal appearance. Applicable means an AD supporting at least a LevelOfAssurance equal to or greater than the minimum requested level of assurance and the requested NameIDFormat(s) (=EntityConcernedType). The OrganizationDisplayName MUST be taken from the beforementioned list of accredited ADs, which MUST contain an exact copy from the Network metadata.
      • In case of a Portal request the eIDAS-berichtenservice MUST NOT be offered in the list of AD's to be selected. 
      • If eIDAS-inbound is supported for the service, the eIDAS-berichtenservice MUST be displayed as a separate option / brand for authentication, next to eHerkenning. The EB MUST NOT be part of the eHerkenning AD list.

      The list of AD's for eHerkenning as returned by service requestADList will not contain the eIDAS Berichtenservice (anymore).


      • In case of multiple OrganizationDisplayNames: if a user-specified preference or user interface language is available, the DV MUST present the OrganizationDisplayName with a matching LanguageQualifier; else if an OrganizationDisplayName with LanguageQualifier "nl" is present, this Dutch OrganizationDisplayName MUST be displayed; else if an OrganizationDisplayName with LanguageQualifier "en" is present, this English OrganizationDisplayName MUST be displayed; else, the first OrganizationDisplayName with a different LanguageQualifier MUST be displayed.
    • the DV MUST show the logo of the applicable brand of the service classifier specified by the DV:
    • in case an AD has multiple endpoints (SingleSignOnService elements): the user MUST be allowed to select one of the endpoints, based on the eme:name attribute of applicable SingleSignOnService endpoints, by listing an AD multiple times with the eme:name appended.

    • Additionally a DV MUST present A separate  "eIDAS" login option , to opt for the eIDAS-berichtenservice as an AD for login with an eIDAS-authentication scheme from another eIDAS-member state:

      • The Dienstverlener MUST use the Richtlijnen communicatie eIDAS to present the eIDAS. Berichtenservice to the user.
      • The Dienstverlener MUST use the EntityID to refer to the EB in the AuthnRequest to the HM.
      • Since this reference is static, a Dienstverlener is not bound to honour the update requirements of a refresh atleast once every 15 minutes as mentioned above.
      • When presenting "eIDAS" link/button  the "eHerkenning" button MAY also be presented by the DV to allow access to the full list of regular ADs as specified above.
    • A DV MAY offer the user to save the selection of the AD as default, except for eIDAS. However, if an error occurs when authenticating at a user-preselected default AD, the DV MUST retrieve a current list of accredited AD's from the HM and prompt the user to choose an AD.
    • The ASTA's MUST NOT be requested by DV's, ONLY the EB and BRP MAY request ASTA's

A responding HM:

  • MUST only process requests from contracted DVs.
  • MUST validate all signatures to be valid before further processing any request. Message (elements) MUST be signed using a certificate as listed in the DV Metadata for HM for the purpose of signing for a SPSSODescriptor of the requesting DV.
  • MUST verify the structure and contents of the request.
  • MUST request authentication, authorization, sectorIDs and attributes on behalf of the DV, as applicable to the requested Service and User's choices. 
  • In case of service intermediation the HM MUST verify the Service Intermediary is still authorized by the Dienstaanbieder (DA) (Service Supplier) by verifying the authorization status of the mediated service (@intermediationAllowed) in the Service Catalog.
  • MUST support the IDPEntry element from the Scoping element in the AuthnRequest. In case the element Scoping is present, the HM MUST use the IDPEntry as reference for the AD selected by the user, bypassing the AD-selection page (applying use case GUC1-alt and GUC3-alt).
  • MUST verify the chosen AD and optional endpoint provided in the IDPEntry element reference a valid AD/EB as listed in the Network metadata.
  • MUST sanitize @ProviderName to remove any script or formatting before displaying

  • MUST determine the branding to use based on the service classifier specified by the DV.

    If one of the criteria is not met, the HM must handle this as a non-recoverable error (see Error handling).

    Note: When a HM receives a DV request on a specific version of the DV-HM interface, it should only show AD’s that list eme:version in the Metadata with the same, or higher version.

    Note: When a HM receives a response from an AD, and the AD specifies an MR that is not of the same version, the HM must handle this as a non-recoverable error.

  • In case a portal service request is made at the eIDAS-berichtenservice, the HM MUST return a error message containing ResultMajor "RequesterError" and ResultMinor "NotSupported"

With regards to determining the user's choice of AD/MR, the following processing rules apply;

  • A HM MAY maintain user preferences (selected AD and MR, and 'Representation' use), except for eIDAS-inbound requests, and use these values for determining applicable AD/MR queries, else;
  • When the EntityConcernedTypesAllowed for the requested service signify a representation scenario (i.e. KVK, RSIN etc.), the HM MUST NOT query the user if it wants to authenticate on behalf of himself or another.
    • In such a scenario a HM MAY opt to only offer a selection list for AD's (GUC3 Aantonen identiteit). This facilitates the current common practice that the AD already knows the MR so that the user will not be confronted with a potential confusing new choice to make whilst this information is already known within the scheme. (However this does invoke the possibility that AD will be confronted with lacking logistic information; see processing rules HM-AD). In case of a Portal request the eIDAS-berichtenservice MUST NOT be offered in the list of AD's to be selected.

Note: The examples below show only the AuthnRequest. Additional wrapping elements can be present in case of HTTP Artifact binding.

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    ID="_6984066c-de03-11e4-a571-080027a35b78"
    ForceAuthn="true"
    IsPassive="false"
    Destination="https://..."
    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
    AssertionConsumerServiceURL="https://"
    AttributeConsumingServiceIndex="1"
    IssueInstant="2015-04-08T16:30:03Z"
    Version="2.0">
    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:etoegang:DV:...</saml:Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <ds:Reference URI=" ">
                <ds:Transforms>
                    <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                    <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                </ds:Transforms>
                <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                <ds:DigestValue>...</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>...</ds:SignatureValue>
        <ds:KeyInfo>
            <ds:KeyName>...</ds:KeyName>
        </ds:KeyInfo>
    </ds:Signature>
    <samlp:RequestedAuthnContext Comparison="minimum">
        <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:etoegang:core:assurance-class:loa3</saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>
</samlp:AuthnRequest>

 

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    ID="_2962ac7c-de04-11e4-9801-080027a35b78"
    Destination="https://..."
    IssueInstant="2015-04-08T16:30:07Z"
    Version="2.0">
    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:etoegang:DV:...</saml:Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <ds:Reference URI="#_2962ac7c-de04-11e4-9801-080027a35b78">
                <ds:Transforms>
                    <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                    <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                </ds:Transforms>
                <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                <ds:DigestValue>...</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>...</ds:SignatureValue>
        <ds:KeyInfo>
            <ds:KeyName>...</ds:KeyName>
        </ds:KeyInfo>
    </ds:Signature>
</samlp:AuthnRequest>

Response (2)