• Created by Unknown User (servaasschramaadmin) on Dec 01, 2023

The most recent version of the technical BSNk specifications are available on https://wiki.bsn-koppelregister.nl/ or on request (beheerorganisatie BSNk through servicecentrum@logius.nl). The information below is for information only.


A MachtigingsRegister uses this interface to register the status the collection(s) of authorizations per person at the BSNk Inzageregister, every time when a new authorization is added or the status of the collection is changed. A MachtigingsRegister MUST register the status of every 'collection of authorizations' (with a description) BSNk Inzageregister that makes sense to the involved Person. A MachtigingsRegister MUST NOT register the status of every individual autorisation. As a minimum a MachtigingsRegister MUST make a distinction between autorisations with this Person as Representative and as Representee. At this moment ETD only supports Representee! As a maximum a MachtigingsRegister can register multiple collections of authorizations at the BSNk Inzageregister, for instance with a specific purpose eg "Business authorizations for administrative employees".


The interface described in this document is used to implement the use case AUC6 Activeren BSN and MUST be implemented by every MachtigingsRegister.

WSDL registerStatusEIM 
<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:bsnk="urn:nl-gdi-eid:1.0: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"
                  name="BSNK_registerStatusEIM"
                  targetNamespace="urn:nl-gdi-eid:1.0:webservices">

    <wsdl:types>
        <xsd:schema targetNamespace="urn:nl-gdi-eid:1.0:webservices"
                    attributeFormDefault="unqualified"
                    elementFormDefault="qualified">

            <xsd:element name="RegisterStatusEIMRequest" type="bsnk:RegisterStatusEIMRequestType">
                <xsd:annotation>
                    <xsd:documentation>Request message to register a EIM status.
                    </xsd:documentation>
                </xsd:annotation>
            </xsd:element>
            <xsd:complexType name="RegisterStatusEIMRequestType">
                <xsd:complexContent>
                    <xsd:extension base="bsnk:BSNkProvideRequestBasetype">
                        <xsd:sequence>
                            <xsd:element name="EncryptedPseudonym" type="bsnk:EncryptedPseudonymType" />
                            <xsd:element name="DeprecatedEP" type="bsnk:EncryptedPseudonymType" minOccurs="0"/>
                            <xsd:element name="MeansNumber" type="bsnk:MeansNumberType" />
                            <xsd:element name="StatusDateTime" type="xsd:dateTime" />
                            <xsd:element name="LevelOfAssurance" type="bsnk:LevelOfAssuranceType" />
                            <xsd:element name="MeansType" type="bsnk:MeansType" />
                            <xsd:element name="Domains" type="bsnk:DomainsType" minOccurs="0"/>
                            <xsd:element name="ReadableCardInfo" type="bsnk:ReadableCardInfoType" minOccurs="0" />
                            <xsd:element name="IDP" type="bsnk:OINType" minOccurs="0" />
                            <xsd:element name="Status" type="bsnk:StatusType" />
                            <xsd:element name="RevocationURL" type="bsnk:RevocationURLType" minOccurs="0" />
                        </xsd:sequence>
                    </xsd:extension>
                </xsd:complexContent>
            </xsd:complexType>
            <xsd:complexType name="BSNkProvideRequestBasetype" abstract="true">
                <xsd:sequence>
                    <xsd:element name="Requester" type="bsnk:OINType" />
                </xsd:sequence>
                <xsd:attribute name="DateTime" type="xsd:dateTime" use="required" />
                <xsd:attribute name="RequestID" type="xsd:ID" use="required" />
            </xsd:complexType>
            <xsd:simpleType name="MeansNumberType">
                <xsd:restriction base="xsd:string">
                    <xsd:maxLength value="16" />
<!--                     <xsd:pattern value="[0-9]+"></xsd:pattern> -->
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:simpleType name="LevelOfAssuranceType">
                <xsd:restriction base="xsd:anyURI">
<!--                     <xsd:maxLength value="128" /> -->
                    <xsd:enumeration value="http://eidas.europa.eu/LoA/substantial" />
                    <xsd:enumeration value="http://eidas.europa.eu/LoA/high" />
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:complexType name="DomainsType">
                <xsd:sequence>
                    <xsd:element name="Domain" type="bsnk:DomainType" minOccurs="1" maxOccurs="2"/>
                </xsd:sequence>
            </xsd:complexType>
            <xsd:simpleType name="DomainType">
                <xsd:restriction base="xsd:token">
                    <xsd:enumeration value="Private" />
                    <xsd:enumeration value="Public" />
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:simpleType name="MeansType">
                <xsd:restriction base="xsd:string">
                    <xsd:maxLength value="25" />
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:simpleType name="StatusType">
                <xsd:restriction base="xsd:string">
                    <xsd:maxLength value="64" />
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:simpleType name="EncryptedPseudonymType">
                <xsd:annotation>
                    <xsd:documentation>Pseudonym encrypted as an EncryptedPseudonym
                        according to Polymorphic Pseudonimization.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:base64Binary" />
            </xsd:simpleType>
            <xsd:simpleType name="ReadableCardInfoType">
                <xsd:restriction base="xsd:string">
                    <xsd:maxLength value="40" />
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:simpleType name="RevocationURLType">
                <xsd:restriction base="xsd:anyURI">
                    <xsd:maxLength value="1024" />
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:simpleType name="OINType">
                <xsd:annotation>
                    <xsd:documentation>OIN type.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string">
                    <xsd:length value="20" />
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:element name="RegisterStatusEIMResponse" type="bsnk:RegisterStatusEIMResponseType">
                <xsd:annotation>
                    <xsd:documentation>
                        Response to a RegisterStatusEIMRequest.
                    </xsd:documentation>
                </xsd:annotation>
            </xsd:element>
            <xsd:complexType name="RegisterStatusEIMResponseType">
                <xsd:complexContent>
                    <xsd:extension base="bsnk:BSNkProvideResponseBasetype">
                        <xsd:sequence>
                            <xsd:element name="Status" type="bsnk:StatusType" />
                        </xsd:sequence>
                    </xsd:extension>
                </xsd:complexContent>
            </xsd:complexType>
            <xsd:complexType name="BSNkProvideResponseBasetype" abstract="true">
                <xsd:attribute name="DateTime" type="xsd:dateTime" use="required" />
                <xsd:attribute name="ResponseID" type="xsd:ID" use="required" />
                <xsd:attribute name="InResponseTo" type="xsd:NCName" use="required" />
            </xsd:complexType>
            <xsd:element name="RegisterStatusEIMFault" type="bsnk:RegisterStatusEIMFaultType">
                <xsd:annotation>
                    <xsd:documentation>
                        Fault response to a RegisterStatusEIMRequest.
                    </xsd:documentation>
                </xsd:annotation>
            </xsd:element>
            <xsd:complexType name="RegisterStatusEIMFaultType">
                <xsd:sequence>
                    <xsd:element name="FaultReason" type="bsnk:RegisterStatusEIMFaultReasonType" />
                    <xsd:element name="FaultDescription" type="bsnk:FaultDescriptionType" maxOccurs="unbounded" />
                </xsd:sequence>
            </xsd:complexType>
            <xsd:simpleType name="RegisterStatusEIMFaultReasonType">
                <xsd:union memberTypes="bsnk:FaultReasons bsnk:RegisterStatusEIMFaultReasons" />
            </xsd:simpleType>
            <xsd:simpleType name="FaultReasons">
                <xsd:restriction base="xsd:string">
                    <xsd:enumeration value="NotFound">
                        <xsd:annotation>
                            <xsd:documentation>Provided information results in
                                zero matches.
                            </xsd:documentation>
                        </xsd:annotation>
                    </xsd:enumeration>
                    <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:enumeration value="TemporarilyUnavailable">
                        <xsd:annotation>
                            <xsd:documentation>Request could temporarily not be
                                processed. A new request for activation MAY be send
                                at a later moment by the requesting party.
                            </xsd:documentation>
                        </xsd:annotation>
                    </xsd:enumeration>
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:simpleType name="RegisterStatusEIMFaultReasons">
                <xsd:restriction base="xsd:string">
                    <xsd:enumeration value="NotUnique">
                        <xsd:annotation>
                            <xsd:documentation>Provided information results in
                                more than one match.
                            </xsd:documentation>
                        </xsd:annotation>
                    </xsd:enumeration>
                    <xsd:enumeration value="RegistrationRefused">
                        <xsd:annotation>
                            <xsd:documentation>Registration refused for other
                                (non-disclosed) reason.
                            </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="BSNK_RegisterStatusEIMRequest">
        <wsdl:part name="in" element="bsnk:RegisterStatusEIMRequest" />
    </wsdl:message>

    <wsdl:message name="BSNK_RegisterStatusEIMResponse">
        <wsdl:part name="out" element="bsnk:RegisterStatusEIMResponse" />
    </wsdl:message>
 
    <wsdl:message name="BSNK_RegisterStatusEIMFault">
        <wsdl:part name="fault" element="bsnk:RegisterStatusEIMFault" />
    </wsdl:message>

    <wsdl:portType name="BSNK_RegisterStatusEIM_Port">
        <wsdl:operation name="BSNK_RegisterStatusEIM">
            <wsdl:input message="bsnk:BSNK_RegisterStatusEIMRequest" wsam:Action="urn:nl-gdi-eid:1.0:webservices:RegisterStatusEIMRequest" />
            <wsdl:output message="bsnk:BSNK_RegisterStatusEIMResponse" wsam:Action="urn:nl-gdi-eid:1.0:webservices:RegisterStatusEIMResponse" />
            <wsdl:fault message="bsnk:BSNK_RegisterStatusEIMFault" name="BSNK_RegisterStatusEIM_Fault"/>
        </wsdl:operation>
    </wsdl:portType>

    <wsdl:binding name="BSNK_RegisterStatusEIM_SOAP" type="bsnk:BSNK_RegisterStatusEIM_Port">
        <soap:binding style="document"
            transport="http://schemas.xmlsoap.org/soap/http" />
        <wsdl:operation name="BSNK_RegisterStatusEIM">
            <soap:operation soapAction="urn:nl-gdi-eid:1.0:webservices:RegisterStatusEIMRequest" />
            <wsdl:input>
                <soap:body use="literal" />
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal" />
            </wsdl:output>
            <wsdl:fault name="BSNK_RegisterStatusEIM_Fault">
                <soap:fault name="BSNK_RegisterStatusEIM_Fault" use="literal" />
            </wsdl:fault>
        </wsdl:operation>
    </wsdl:binding>
 
    <wsdl:service name="BSNK_RegisterStatusEIM_Service">
        <wsdl:port binding="bsnk:BSNK_RegisterStatusEIM_SOAP" name="BSNK_RegisterStatusEIM">
            <soap:address location="https://.../TODO/RegisterStatusEIM" />
        </wsdl:port>
    </wsdl:service>

</wsdl:definitions>


Request

Consists of a registration request message <RegisterStatusEIMRequest> in the SOAP body of the request message. SOAP should be implemented accoording to the Web services requirements .

Element/@Attribute

0..n

Description

@DateTime

1

Time of issuing of the request.
@RequestID1Unique identifier for this request
<Requester>1EntityID (OIN) of the requesting MachtigingsRegister.

<EncryptedPseudonym>

1

Encrypted Pseudonym of the user to be transformed to a pseudonym for the BSNk Inzageregister

<LevelOfAssurance>1

Choice http://eidas.europa.eu/LoA/substantial or http://eidas.europa.eu/LoA/high. Specifies the (highest) LoA of any active registered authorization (either as "Representative" or "Representee"). 

<MeansNumber>1

For a MachtigingsRegister MeansNumber identifies the 'collection of authorizations' to which the status applies.  As a minimum a MachtigingsRegister MUST make a distinction between (a collection with) autorisations with this Person as Representative and as Representee. At this moment ETD only supports Representee! As a maximum a MachtigingsRegister can register multiple collections of authorizations at the BSNk Inzageregister, that makes sense for this specific Person. A MachtigingsRegister MUST NOT register the status of every individual autorisation.   MeansNumber MUST be unique per user , but MUST not be usable to identify the user. For privacy reasons this MeansNumber MUST have a low entropy, preferably 01, 02 ...09, so that many users have the same MeansNumber(s).

<StatusDateTime>1

DateTime of status change, MUST not be after @DateTime of this request. The resolution of this field MUST be between (inclusive) minutes and milliseconds.

<MeansType>1

String max 25 chars. MeansType represents a – for the user – readable version of the type of authorizations'. For the ETD MachtigingsRegister the type SHOULD always be "Machtiging". Note, other authorization types (not ETD) could be "Wettelijke Vertegenwoordiging" or "Volmacht".

<Domains>0..1The domains where the autorisations can be used, optional.
    <Domain>1..nOne element per domain for which the autorisations can be used. Allowed values are 'Public' and 'Private'.
<ReadableCardInfo>0..1

String max 60 chars. ReadableCardInfo is text that – combined with the MeansType – has just enough information for a user to recognise the specific 'collection of authorizations' in the domain of the MachtigingsRegister. ReadableCardInfo MUST be unique per user, but MUST not be usable to identify the user. For privacy reasons this ReadableCardInfo MUST have a low entropy so that many users have this same ReadableCardInfo. 

 For Autorisations a second part has to be added with the date of the last added Autorisation eg "Last Authorization added at 31-01-2018". Therefor the MR has to register a new status with every new autorisation. For MachtigingsRegister this element is required for every registration to have the most actual "Last Autorisation" (any new will overwrite the old text).

<Status>1

MUST contain one of the specified statusses: Activated (as long as any authorization in this collection is active in the BSN Domain), Suspended  (if the last active authorization in this collection is suspended), Expired (if the last active authorization in this collection is expired) or Revoked (if the last active authorization in this collection is Revoked). This element is required for every registration to have the most actual status. Any new status will overwrite the old status.

<RevocationURL>0..1

String max 1024 chars. RevocationURL is a valid URL which can be used by mijnoverheid (when providing the user an overview of electronic identification means) to redirect the user to the MachtigingsRegister for managing this collection of autorisations, for instance suspending authorizations. For privacy reasons this RevocationURL can have a random collection-specific unique-ID (not a userid!), but otherwise MUST consist of low entropy data. The URL could use other elements from this registration request message (except EncryptedPseudonym). 

In the Metadata the RoleDescriptor for MachtigingsRegister already has a generic URL to the MachtigingsRegister authorization management function. That URL will be default unless a RevocationURL is provided. This RevocationURL could be used to direct the user directly to the appropriate collection of authorizations. Or a RevocationURL with a random collection-specific unique-ID could me used to immediately Suspend the collection for a short period of time , possibly even without authenticating the user.

 

Any new will overwrite the old text and empty string can be used to cancel the (working of this) RevocationURL. 


Processing rules for Status Registration Request

A requesting MachtigingsRegister

  • MUST await a successful response or retry to send the request. Requests MUST be buffered and retried during 7 days.
  • SHOULD adhere to a maximum of 1 status update per unit of the resolution of the StatusDateTime, otherwise the MU SHOULD increase the resolution of the StatusDateTime.
  • MUST log and investigate failures.

Response

Consists of a response message <RegisterStatusEIMResponse> in the SOAP body of the request message. In case a response is received, the request resulted in new or a unique and valid match of an existing electronic identification means. In case an error occurs a SOAP fault will be used. The SOAP fault will contain error codes as <FaultReason> as described below, with one (or more) localized <FaultDescription>.

Element/@Attribute

0..n

Description

@DateTime

1

Time of issuing of the response.
@ResponseID1Unique identifier of the response
@InResponseTo1Unique identifier of the request this is a response to (@RequestID of request)

  

FaultReasons

The following response codes are used to indicate the status of a response.

ResponseCode

Description

NotUniqueRequest rejected. Provided information results in more than one match.
NotFoundRequest rejected. Provided information results in zero matches.
RegistrationRefusedRequest rejected. Registration refused for other non-disclosed reason.
AuthorizationErrorRequest rejected. Authentication invalid or access denied. A HTTP 403 status response MAY be given instead of a SOAP-fault with this response.
SyntaxErrorRequest rejected. Request invalid.
TemporarilyUnavailableRequest could temporarily not be processed. A new request for registration MAY be sent at a later moment by the requesting party.