Skip to main content
Skip table of contents

Discovery webservice MR for chain authorisations


This page describes the interface specifications for the discovery webservice implemented  by a Machtigingenregister (MR) (authorization information provider). This service is intended to be used by other Machtigingenregisters (MR) or by management applications of participants in order to obtain information about chain authorizations (MR2). This interface MUST NOT be used as a replacement for Interface specifications HM-MR chain authorization. In order to maintain the same level of security as is usual in other SOAP services like the one the BSNk provides, the security demands including include SOAP-signing and encryption of the message. 

During SOAP signing the body of both request and response MUST be signed with a WS-Security header containing an XMLSignature based on the PKIo certificate of the participant issueing the message. The WS-Security signature MUST include the KeyInfo in the signature, as a BinarySecurityToken, as per WS-Security X.509 Certificate Token Profile 1.0, ยง3.3.2. The certificate referenced MUST be listed in the Metadata for participants in a KeyDescriptor of the Participant marked for the use "signing" (or without use, the default includes signing).

The content requirements for signing and encryption are added in the supplementary page MR-MR webservice Security.


Elektronische Toegangsdiensten only supports chains with one intermediary:

  • User G (user) > Intermediary A > Service consumer B.


The authorization that the user may act on behalf of Intermediary A is registered as authorization with the first MR. The information that there is an authorization from Service consumer B for Intermediary, and in which MR it is stored, MUST also be known by the first MR (or retrieved at the time of authentication).


ChainInformationQuery

This is a SOAP service to be implemented by the MR. Schematically it looks like this:

NameRequiredDescription

ID

YES

Unique message attribute, like the SAML ID field

RequestingEntityIdYESThe entityID of the MR requesting this information. The EntityID MUST match the entityID of the MR in the Network metadata
IntermediarySubjectID_TypeYES

ECTA type to use to identify the intermediary company. MUST be set to  urn:etoegang:1.9:EntityConcernedID:KvKnr.

Only one LegalSubjectID_Type element MUST be included

IntermediarySubjectID  YESContains the value of the ECTA of the intermediary 
LegalSubjectID_Type YES

ECTA type to use to identify the Service consumer company. 


LegalSubjectIDYES

Contains the value of the ECTA of the Service consumer which is to be represented

Only one LegalSubjectID element MUST be included

LegalSubjectIDServiceRestriction_TypeNOMUST be set to vestigingsnummer if this function is used. No other restructions are currently used
LegalSubjectIDServiceRestrictionCONDITIONAL

If the tag LegalSubjectIDServiceRestriction_Type is used, this tag is required. It contains the value of the LegalSubjectIDServiceRestriction_Type

Service_TypeYES

Can be set to either OIN, ServiceUUID or GeneralAuthorization. If OIN is used all services belonging to the OIN are requested. The ServiceUUID option can be used to request a specific service. GeneralAuthorization refers to a special authorizationtype where the user has access to all current and future services of all Dienstverlener (DV).

ServiceCONDITIONAL

In case Service_Type is OIN:

  • An OIN must be selected from the Service catalog.
  • All services which are registed under this OIN will be part of the discovery request
  • This field is required

In case Service_Type is ServiceUUID

  • A serviceUUID MUST be selected from a service definition in the Service catalog.
  • Only the selected service is part of the discovery request
  • This field is required

In case Service_Type is GeneralAuthorization

  • Service field MUST NOT be used
SignatureYES

A Signature that scopes all the elements in the Response message, see Digital signature

LOAminNOSpecifies the minimum LOA level to be considered by the responding MR


Processing rules for creating the request:

  • The sender MUST sign and encrypt the request with the keys of the MR in the Network metadata 
  • The MR MAY only inquire if a chain authorisation exists if one of the organisations is its customer


Processing rules for validating the request:

  • The recipient MUST verify the request with the keys of the MR in the Network metadata. The keys must be retrieved from the MR stated in the RequestingEntityId.

Response

NameRequiredDescription

ID

YES

Unique message attribute, like the SAML ID field

InResponseToYESThis is the same value as send in the ID in the ChainInformationQuery
SignatureYESSignature scopes the Response message
DateTimeYESIssue datetime of the response
IntermediarySubjectID_TypeYESECTA type to use to identify the intermediary company. MUST be set to urn:etoegang:1.9:EntityConcernedID:KvKnr.
IntermediarySubjectID  YESContains the value of the ECTA of the intermediary 
LegalSubjectID_Type YES

ECTA type to use to identify the Service consumer company.

MUST return the same LegalSubjectId_Type as included in the request.

LegalSubjectIDYES

Contains the value of the ECTA of the Service consumer which is to be represented

MUST return the same LegalSubjectId as included in the request.

LegalSubjectIDServiceRestriction_TypeNOMUST be set to vestigingsnummer if this function is used. No other restructions are currently used
LegalSubjectIDServiceRestrictionCONDITIONAL

If the tag LegalSubjectIDServiceRestriction_Type is used, this tag is required. It contains the value of the LegalSubjectIDServiceRestriction_Type

ServiceList

YES

A list of services for which the Intermediary is authorized (see processing rules). 


Service
OPTIONAL, one or moreSpecifies the services for which the chainauthz is applicable. If no services are applicable, this element is not used


ServiceDefinitionUUIDYES

The serviceUUID of the service as specified in the ServiceDefinition of the service catalog.

In case Service_Type is GeneralAuthorization, the string "GeneralAuthorization" MUST be returned instead of a serviceUUID.



LOAYESThe LOA which is registed at the authorisation which allows usage of this service


ToDateYES

DateTime until the mandate for the service is valid

  • Can only be in the future
  • Must be in UTC format
    • Format "yyyy-MM-dd'T'HH:mm:ssZ"
    • Example "2027-02-22T11:43:01Z"

Processing rules for creating response

In case Service_Type in the request is OIN:

  • All services which are registed under this OIN will be part of the discovery request
  • The ServiceList MUST return serviceUUID's which are registerd to the requested OIN, if the Intermediary is authorized for these services. If there are no applicable services to return, the ServiceList will remain empty.

In case Service_Type is in the request ServiceUUID

  • Only the selected service is part of the discovery request
  • The ServiceList MUST return the same serviceUUID, if the Intermediary is authorized for these services. Otherwise the ServiceList will remain empty


WSDL example

XML
<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:etoegang="urn:etoegang:webservices"
 xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
 xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
 name="ChainInformationQuery"
 targetNamespace="urn:etoegang:webservices">
    <wsdl:types>
        <xsd:schema targetNamespace="urn:etoegang:webservices"
 attributeFormDefault="unqualified"
 elementFormDefault="qualified">
            <xsd:import namespace="http://www.w3.org/2000/09/xmldsig#" schemaLocation="http://www.w3.org/TR/xmldsig-core/xmldsig-core-schema.xsd"/>
            <xsd:element name="ChainInformationQueryRequest" type="etoegang:ChainInformationQueryRequestType">
                <xsd:annotation>
                    <xsd:documentation>Sends an information request
                    </xsd:documentation>
                </xsd:annotation>
            </xsd:element>
                
            <xsd:complexType name="ChainInformationQueryRequestType">
                <xsd:sequence>                                
                    <xsd:element name="RequestingEntityId" type="etoegang:EntityIDType" minOccurs="1" />
                    <xsd:element name="IntermediarySubjectID_Type" type="etoegang:ECTA" minOccurs="1" />
                    <xsd:element name="IntermediarySubjectID" type="etoegang:ECTAValueType" minOccurs="1" />
                    <xsd:element name="LegalSubjectID_Type" type="etoegang:ECTA" minOccurs="1" />
                    <xsd:element name="LegalSubjectID" type="etoegang:ECTAValueType" minOccurs="1" />
                    <xsd:element name="LegalSubjectIDServiceRestriction_Type" type="etoegang:ServiceRestrictionTypeType" minOccurs="0" />
                    <xsd:element name="LegalSubjectIDServiceRestriction" type="etoegang:ServiceRestrictionType" minOccurs="0" />
                    <xsd:element name="Service_Type" type="etoegang:ServiceTypeType" minOccurs="1" />
                    <xsd:element name="Service" type="etoegang:ServiceType" minOccurs="0" />
                    <xsd:element name="LOAmin" type="etoegang:LOA" minOccurs="1" />             
                </xsd:sequence>
                <xsd:attribute name="ID" type="xsd:ID" use="required"/>         
            </xsd:complexType>           
             <xsd:simpleType name="EntityIDType">
                <xsd:annotation>
                    <xsd:documentation>EntityID type.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string">
                    <xsd:maxLength value="100" />
                </xsd:restriction>
            </xsd:simpleType>
              
            <xsd:simpleType name="ECTA">
                <xsd:annotation>
                    <xsd:documentation>ECTA type.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string">
                    <xsd:maxLength value="100" />
                </xsd:restriction>
            </xsd:simpleType>
                
            <xsd:simpleType name="ECTAValueType">
                <xsd:annotation>
                    <xsd:documentation>ECTAValueType.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string">
                    <xsd:maxLength value="200" />
                </xsd:restriction>
            </xsd:simpleType>
               
            <xsd:simpleType name="ServiceRestrictionTypeType">
                <xsd:annotation>
                    <xsd:documentation>ServiceRestrictionTypeType.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string">
                  <xsd:enumeration value="vestigingsnummer"/>
                </xsd:restriction>
            </xsd:simpleType>
                
            <xsd:simpleType name="ServiceRestrictionType">
                <xsd:annotation>
                    <xsd:documentation>ServiceRestrictionType.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string">
                    <xsd:maxLength value="50" />
                </xsd:restriction>
            </xsd:simpleType>
            
            <xsd:simpleType name="ServiceTypeType">
                <xsd:annotation>
                    <xsd:documentation>ServiceTypeType.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string">
                  <xsd:enumeration value="OIN"/>
                  <xsd:enumeration value="ServiceUUID"/>
                  <xsd:enumeration value="GeneralAuthorization"/>
                </xsd:restriction>
            </xsd:simpleType>
                
            <xsd:simpleType name="ServiceType">
                <xsd:annotation>
                    <xsd:documentation>ServiceType.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string">
                    <xsd:maxLength value="50" />
                </xsd:restriction>
            </xsd:simpleType>
                
            <xsd:simpleType name="LOA">
                <xsd:annotation>
                    <xsd:documentation>LOA.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string">
                    <xsd:maxLength value="42" />
                                                          
                </xsd:restriction>
            </xsd:simpleType>
                
                
            <xsd:element name="ChainInformationQueryResponse" type="etoegang:ChainInformationQueryResponseType">
                <xsd:annotation>
                    <xsd:documentation>
 Response to a ChainInformationQueryRequest.
                    </xsd:documentation>
                </xsd:annotation>
            </xsd:element>
            <xsd:complexType name="ChainInformationQueryResponseType">
                <xsd:sequence>
                    <xsd:element ref="ds:Signature" minOccurs="1" />
                    <xsd:element name="InResponseTo" type="xsd:ID" minOccurs="1" maxOccurs="1" />                  
                    <xsd:element name="DateTime" type="xsd:dateTime" minOccurs="1" maxOccurs="1" />
                    <xsd:element name="IntermediarySubjectID_Type" type="etoegang:ECTA" minOccurs="1" />
                    <xsd:element name="IntermediarySubjectID" type="etoegang:ECTAValueType" minOccurs="1" />
                    <xsd:element name="LegalSubjectID_Type" type="etoegang:ECTA" minOccurs="1" />
                    <xsd:element name="LegalSubjectID" type="etoegang:ECTAValueType" minOccurs="1" />
                    <xsd:element name="LegalSubjectIDServiceRestriction_Type" type="etoegang:ServiceRestrictionTypeType" minOccurs="0" />
                    <xsd:element name="LegalSubjectIDServiceRestriction" type="etoegang:ServiceRestrictionType" minOccurs="0" />
                    <xsd:element name="ServiceList" type="etoegang:ServiceListType" minOccurs="1" maxOccurs="1"/>
                </xsd:sequence>
                <xsd:attribute name="ID" type="xsd:ID" use="required"/>         
  
            </xsd:complexType>
            <xsd:complexType name="EtoegangProvideResponseBasetype" abstract="true">
            </xsd:complexType>
            <xsd:complexType name="ServiceListType">
                <xsd:sequence>
                    <xsd:element name="Service" type="etoegang:ComplexServiceType" maxOccurs="unbounded" minOccurs="0" />
                </xsd:sequence>
            </xsd:complexType>
                
            <xsd:complexType name="ComplexServiceType">
                 <xsd:sequence>
                    <xsd:element name="ServiceUUID" type="etoegang:ServiceType" maxOccurs="1" minOccurs="1" />
                    <xsd:element name="LOA" type="etoegang:LOA" maxOccurs="1" minOccurs="1" />
                    <xsd:element name="ToDate" type="xsd:dateTime" maxOccurs="1" minOccurs="1" />
                </xsd:sequence>
            </xsd:complexType>
                
            <xsd:element name="ChainInformationQueryFault" type="etoegang:ChainInformationQueryFaultType">
                <xsd:annotation>
                    <xsd:documentation>
 Fault response to a ChainInformationQuery.
                    </xsd:documentation>
                </xsd:annotation>
            </xsd:element>
            <xsd:complexType name="ChainInformationQueryFaultType">
                <xsd:sequence>
                    <xsd:element name="FaultReason" type="etoegang:ChainInformationQueryFaultReasonType" />
                    <xsd:element name="FaultDescription" type="etoegang:FaultDescriptionType" maxOccurs="unbounded" />
                </xsd:sequence>
            </xsd:complexType>
            <xsd:simpleType name="ChainInformationQueryFaultReasonType">
                <xsd:union memberTypes="etoegang:FaultReasons etoegang:ChainInformationQueryFaultReasons" />
            </xsd:simpleType>
            <xsd:simpleType name="FaultReasons">
                <xsd:restriction base="xsd:string">
                    <xsd:enumeration value="AuthorizationError">
                        <xsd:annotation>
                            <xsd:documentation>Authentication invalid or access denied.
                            </xsd:documentation>
                        </xsd:annotation>
                    </xsd:enumeration>
                    <xsd:enumeration value="SyntaxError">
                        <xsd:annotation>
                            <xsd:documentation>Request invalid.
                            </xsd:documentation>
                        </xsd:annotation>
                    </xsd:enumeration>
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:simpleType name="ChainInformationQueryFaultReasons">
                <xsd:restriction base="xsd:string">
                    <xsd:enumeration value="AuthorizationError">
                        <xsd:annotation>
                            <xsd:documentation>Service is only accessable by other MR's
                            </xsd:documentation>
                        </xsd:annotation>
                    </xsd:enumeration>
                    <xsd:enumeration value="SyntaxError">
                        <xsd:annotation>
                            <xsd:documentation>Invalid syntax used
                            </xsd:documentation>
                        </xsd:annotation>
                    </xsd:enumeration>
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:complexType name="FaultDescriptionType">
                <xsd:simpleContent>
                    <xsd:extension base="xsd:string">
                        <xsd:attribute name="lang" type="xsd:language" />
                    </xsd:extension>
                </xsd:simpleContent>
            </xsd:complexType>
                
        </xsd:schema>
    </wsdl:types>
    <wsdl:message name="ETOEGANG_ChainInformationQueryRequest">
        <wsdl:part name="in" element="etoegang:ChainInformationQueryRequest" />
    </wsdl:message>
    <wsdl:message name="ETOEGANG_ChainInformationQueryResponse">
        <wsdl:part name="out" element="etoegang:ChainInformationQueryResponse" />
    </wsdl:message>
        <wsdl:message name="ETOEGANG_ChainInformationQueryFault">
        <wsdl:part name="ETOEGANG_ChainInformationQueryFault" element="etoegang:ChainInformationQueryFault"  />
    </wsdl:message>
    <wsdl:portType name="ETOEGANG_ChainInformationQuery_Port">
     <wsdl:operation name="ETOEGANG_ChainInformationQuery">
        <wsdl:input message="etoegang:ETOEGANG_ChainInformationQueryRequest" wsam:Action="urn:etoegang:webservices:ChainInformationQueryRequest" />
         <wsdl:output message="etoegang:ETOEGANG_ChainInformationQueryResponse" wsam:Action="urn:etoegang:webservices:ChainInformationQueryResponse" />
     <wsdl:fault message="etoegang:ETOEGANG_ChainInformationQueryFault" name="ETOEGANG_ChainInformationQueryFault"/>        
        </wsdl:operation>
    </wsdl:portType>
    <wsdl:binding name="ETOEGANG_ChainInformationQuery_SOAP" type="etoegang:ETOEGANG_ChainInformationQuery_Port">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
        <wsdl:operation name="ETOEGANG_ChainInformationQuery">
            <soap:operation soapAction="urn:etoegang:webservices:ChainInformationQueryRequest" />
            <wsdl:input>
                <soap:body use="literal" />
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal" />
            </wsdl:output>
            <wsdl:fault name="ETOEGANG_ChainInformationQueryFault">
                <soap:fault name="ETOEGANG_ChainInformationQueryFault" use="literal" />
            </wsdl:fault>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name="ETOEGANG_ChainInformationQuery_Service">
        <wsdl:port binding="etoegang:ETOEGANG_ChainInformationQuery_SOAP" name="ETOEGANG_ChainInformationQuery">
            <soap:address location="https://.../TODO/ChainInformationQuery" />
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.