View Source

This interface between a MachtigingsRegister and BSNk is used to activate a user's social security number (BSN) for government related electronic services. The activation requires a BSN and validation data and will result in the provisioning of one or more Polymorphic Pseudonymization structures (e.g. Polymorphic Identity and Polymorphic Pseudonym) by the BSNk.

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

WSDL

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<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"
                  xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                  name="BSNK_activate"
                  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:import namespace="urn:oasis:names:tc:SAML:2.0:assertion" schemaLocation="saml-schema-assertion-2.0.xsd"/>
                    
            <xsd:element name="ProvidePPRequest" type="bsnk:ProvidePolymorphicRequestType">
                <xsd:annotation>
                    <xsd:documentation>Request message to provide PP for a
                        specific user, for future use via ProvideEP queries.
                        The 'BSNk' will generate one or more
                        polymorphic pseudonym(s) for the identified user.
                    </xsd:documentation>
                </xsd:annotation>
            </xsd:element>
            <xsd:element name="ProvidePP_PPCAOptimizedRequest" type="bsnk:ProvidePolymorphicRequestType">
                <xsd:annotation>
                    <xsd:documentation>Request message to provide PP for a
                        specific user, for future use via ProvideEP queries.
                        The 'BSNk' will generate one or more
                        polymorphic pseudonym(s) for the identified user. This
                        request will result in one-or-more polymorphic
                        pseudonyms in a form optimized for usage as a PPCA.  
                    </xsd:documentation>
                </xsd:annotation>
            </xsd:element>
            <xsd:complexType name="ProvidePolymorphicRequestType">
                <xsd:complexContent>
                    <xsd:extension base="bsnk:BSNkProvideRequestBasetype">
                        <xsd:sequence>
                            <xsd:element name="RequesterKeySetVersion" type="bsnk:KeyVersionType" />
                            <xsd:choice>
                                <xsd:element name="BSN" type="bsnk:BSNType" />
                                <xsd:element name="EncryptedBSN" type="bsnk:EncryptedBSNType"/>
                                <xsd:element name="EncryptedIdentity" type="bsnk:EncryptedIdentityType" />
                                <xsd:sequence>
                                    <xsd:element name="eIDAS-UniquenessID" type="bsnk:eIDAS-UniquenessIDType"/>
                                    <xsd:element name="EncryptedBSN" type="bsnk:EncryptedBSNType" minOccurs="0"/>
                                </xsd:sequence>
                            </xsd:choice>
                            <xsd:element name="DocumentType" type="bsnk:DocumentTypeType" minOccurs="0" />
                            <xsd:element name="DocumentID" type="bsnk:DocumentIDType" minOccurs="0" />
                            <xsd:element name="GivenNames" type="bsnk:GivenNamesType" minOccurs="0" />
                            <xsd:element name="SurName" type="bsnk:SurNameType" minOccurs="0" />
                            <xsd:element name="DateOfBirth" type="bsnk:BirthDateType" minOccurs="0" />
                            <xsd:element name="PlaceOfBirth" type="bsnk:PlaceOfBirthType" 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="KeyVersionType">
                <xsd:annotation>
                    <xsd:documentation>Key(set) version type.</xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:positiveInteger"/>
            </xsd:simpleType>
            <xsd:simpleType name="BSNType">
                <xsd:annotation>
                    <xsd:documentation>In case a BSN consists of a number of
                       only 8 digits, the BSN shall be padded with a preceding
                       '0' (digit zero).
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string">
                    <xsd:length value="9" />
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:simpleType name="EncryptedIdentityType">
                <xsd:annotation>
                    <xsd:documentation>Identity encrypted as an EncryptedIdentity
                        according to Polymorphic Pseudonimization.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:base64Binary" />
            </xsd:simpleType>
            <xsd:simpleType name="eIDAS-UniquenessIDType">
                <xsd:annotation>
                    <xsd:documentation>To be used only in eIDAS context.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string" />
            </xsd:simpleType>
            <xsd:complexType name="EncryptedBSNType">
                <xsd:annotation>
                    <xsd:documentation>BSN encrypted in the form of a
                        SAML2 EncryptedID.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:sequence>
                    <xsd:element ref="saml2:EncryptedID" />
                </xsd:sequence>
            </xsd:complexType>
            <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:simpleType name="DocumentIDType">
                <xsd:annotation>
                    <xsd:documentation>Document ID as appearing on the Identity
                        Document referenced
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string">
                    <xsd:maxLength value="15" />
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:simpleType name="DocumentTypeType">
                <xsd:annotation>
                    <xsd:documentation>Type of Identity Document referenced.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string">
                    <xsd:enumeration value="NL-Paspoort" />
                    <xsd:enumeration value="NL-Identiteitskaart" />
                    <xsd:enumeration value="NL-Rijbewijs" />
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:simpleType name="GivenNamesType">
                <xsd:annotation>
                    <xsd:documentation>Given names as these appear on the
                        Identity Document referenced. If given names are not
                        fully known than must contain all known initials.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string">
                    <xsd:maxLength value="200" />
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:simpleType name="SurNameType">
                <xsd:annotation>
                    <xsd:documentation>Surname as appears on the
                        Identity Document referenced.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string">
                    <xsd:maxLength value="210" />
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:simpleType name="BirthDateType">
                <xsd:union>
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:date" />
                    </xsd:simpleType>
                    <xsd:simpleType >
                        <xsd:restriction base="xsd:gYearMonth" />
                    </xsd:simpleType>
                    <xsd:simpleType >
                        <xsd:restriction base="xsd:gYear" />
                    </xsd:simpleType>
                </xsd:union>
            </xsd:simpleType>
            <xsd:simpleType name="PlaceOfBirthType">
                <xsd:annotation>
                    <xsd:documentation>For Dutch places of birth this value
                        must correspond to the exact value as listed in table
                        33 of the logic design of the BRP. MUST NOT be used for
                        foreign places of birth.
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:restriction base="xsd:string">
                    <xsd:maxLength value="40" />
                </xsd:restriction>
            </xsd:simpleType>
            <xsd:element name="ProvidePPResponse" type="bsnk:ProvidePolymorphicResponseType">
                <xsd:annotation>
                    <xsd:documentation>
                        Response to a ProvidePPRequest or
                        ProvidePP_PPCAOptimizedRequest.
                    </xsd:documentation>
                </xsd:annotation>
            </xsd:element>
            <xsd:element name="ProvidePP_PPCAOptimizedResponse" type="bsnk:ProvidePolymorphicResponseType">
                <xsd:annotation>
                    <xsd:documentation>
                        Response to a ProvidePP_PPCAOptimizedRequest.
                    </xsd:documentation>
                </xsd:annotation>
            </xsd:element>
            <xsd:complexType name="ProvidePolymorphicResponseType">
                <xsd:complexContent>
                    <xsd:extension base="bsnk:BSNkProvideResponseBasetype">
                        <xsd:sequence>
                            <xsd:element name="PolymorphicPseudonym" type="bsnk:PolymorphicPseudonymType" maxOccurs="unbounded" />
                        </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:complexType name="PolymorphicPseudonymType">
                <xsd:simpleContent>
                    <xsd:extension base="xsd:base64Binary" />
                </xsd:simpleContent>
            </xsd:complexType>
            <xsd:element name="ProvidePolymorphicFault" type="bsnk:ProvidePolymorphicFaultType">
                <xsd:annotation>
                    <xsd:documentation>
                        Fault response to a ProvidePPRequest or
                        ProvidePP_PPCAOptimizedRequest.
                    </xsd:documentation>
                </xsd:annotation>
            </xsd:element>
            <xsd:complexType name="ProvidePolymorphicFaultType">
                <xsd:sequence>
                    <xsd:element name="FaultReason" type="bsnk:ProvidePolymorphicFaultReasonType" />
                    <xsd:element name="FaultDescription" type="bsnk:FaultDescriptionType" maxOccurs="unbounded" />
                </xsd:sequence>
            </xsd:complexType>
            <xsd:simpleType name="ProvidePolymorphicFaultReasonType">
                <xsd:union memberTypes="bsnk:FaultReasons bsnk:ProvidePolymorphicFaultReasons" />
            </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="ProvidePolymorphicFaultReasons">
                <xsd:restriction base="xsd:string">
                    <xsd:enumeration value="NotEnoughInfo">
                        <xsd:annotation>
                            <xsd:documentation>Provided information may resolve
                                to a unique match, but not enough assurance
                                (e.g. against typos) can be established.
                            </xsd:documentation>
                        </xsd:annotation>
                    </xsd:enumeration>
                    <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="DocumentRejected">
                        <xsd:annotation>
                            <xsd:documentation>Document not accepted.
                            </xsd:documentation>
                        </xsd:annotation>
                    </xsd:enumeration>
                    <xsd:enumeration value="ProvisioningRefused">
                        <xsd:annotation>
                            <xsd:documentation>Activation 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_ProvidePPRequest">
        <wsdl:part name="in" element="bsnk:ProvidePPRequest" />
    </wsdl:message>

    <wsdl:message name="BSNK_ProvidePP_PPCAOptimizedRequest">
        <wsdl:part name="in" element="bsnk:ProvidePP_PPCAOptimizedRequest" />
    </wsdl:message>
 
    <wsdl:message name="BSNK_ProvidePPResponse">
        <wsdl:part name="out" element="bsnk:ProvidePPResponse" />
    </wsdl:message>

    <wsdl:message name="BSNK_ProvidePP_PPCAOptimizedResponse">
        <wsdl:part name="out" element="bsnk:ProvidePP_PPCAOptimizedResponse" />
    </wsdl:message>
 
    <wsdl:message name="BSNK_ProvidePolymorphicFault">
        <wsdl:part name="fault" element="bsnk:ProvidePolymorphicFault" />
    </wsdl:message>

    <wsdl:portType name="BSNK_Activate_Port">
        <wsdl:operation name="BSNK_ProvidePP">
            <wsdl:input message="bsnk:BSNK_ProvidePPRequest" wsam:Action="urn:nl-gdi-eid:1.0:webservices:ProvidePPRequest" />
            <wsdl:output message="bsnk:BSNK_ProvidePPResponse" wsam:Action="urn:nl-gdi-eid:1.0:webservices:ProvidePPResponse" />
            <wsdl:fault message="bsnk:BSNK_ProvidePolymorphicFault" name="BSNK_ProvidePolymorphic_Fault"/>
        </wsdl:operation>
        <wsdl:operation name="BSNK_ProvidePP_PPCAOptimized">
            <wsdl:input message="bsnk:BSNK_ProvidePP_PPCAOptimizedRequest" wsam:Action="urn:nl-gdi-eid:1.0:webservices:ProvidePP_PPCAOptimizedRequest" />
            <wsdl:output message="bsnk:BSNK_ProvidePP_PPCAOptimizedResponse" wsam:Action="urn:nl-gdi-eid:1.0:webservices:ProvidePP_PPCAOptimizedResponse" />
            <wsdl:fault message="bsnk:BSNK_ProvidePolymorphicFault" name="BSNK_ProvidePolymorphic_Fault"/>
        </wsdl:operation>
    </wsdl:portType>

    <wsdl:binding name="BSNK_Activate_SOAP" type="bsnk:BSNK_Activate_Port">
        <soap:binding style="document"
            transport="http://schemas.xmlsoap.org/soap/http" />
        <wsdl:operation name="BSNK_ProvidePP">
            <soap:operation soapAction="urn:nl-gdi-eid:1.0:webservices:ProvidePPRequest" />
            <wsdl:input>
                <soap:body use="literal" />
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal" />
            </wsdl:output>
            <wsdl:fault name="BSNK_ProvidePolymorphic_Fault">
                <soap:fault name="BSNK_ProvidePolymorphic_Fault" use="literal" />
            </wsdl:fault>
        </wsdl:operation>
        <wsdl:operation name="BSNK_ProvidePP_PPCAOptimized">
            <soap:operation soapAction="urn:nl-gdi-eid:1.0:webservices:ProvidePP_PPCAOptimizedRequest" />
            <wsdl:input>
                <soap:body use="literal" />
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal" />
            </wsdl:output>
            <wsdl:fault name="BSNK_ProvidePolymorphic_Fault">
                <soap:fault name="BSNK_ProvidePolymorphic_Fault" use="literal" />
            </wsdl:fault>
        </wsdl:operation>
    </wsdl:binding>
 
    <wsdl:service name="BSNK_Activate_Service">
        <wsdl:port binding="bsnk:BSNK_Activate_SOAP" name="BSNK_Activate">
            <soap:address location="https://.../TODO/Activate" />
        </wsdl:port>
    </wsdl:service>

</wsdl:definitions>

Request

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

Element/@Attribute	0..n	Description
@DateTime	1	Time of issuing of the request.
@RequestID	1	Unique identifier for this Request
<Requester>	1	EntityID (OIN) of the requesting MachtigingsRegister.
<RequesterKeySetVersion>	1	Key set version of the requesting MachtigingsRegister .
<BSN>	0..1	Sector ID for Dutch citizens. String of 9 characters, in case a BSN consists of a number of only 8 digits, the BSN shall be padded with a preceding '0' (digit zero). As verification data at least DocumentID and one or more other identity supporting elements (those other than DocumentType) MUST be provided. Either a BSN, EncryptedBSN, EncryptedIdentity or eIDAS-uniquenessID MUST be provided.
<EncryptedBSN>	0..1	An encrypted BSN. This BSN MUST be encrypted using XML-encryption, as per (XML/SAML) Encryption. Either a BSN, EncryptedBSN, EncryptedIdentity or eIDAS-uniquenessID MUST be provided.
<EncryptedIdentity>	0..1	Identity (typically BSN) encrypted as EncryptedIdentity under Polymorphic Pseudonimization. Either a BSN, EncryptedBSN, or EncryptedIdentity MUST be provided.
<EncryptedBSN>	0..1	At this moment an encryptedBSN is for exclusive use by an eIDAS-berichtenservice.
<DocumentType>	0..1	String max 20 chars. Value represents the type of government-issued document that was used. Possible values are "NL-Paspoort", "NL-Identiteitskaart" and "NL-Rijbewijs".
<DocumentID>	0..1	String max 15 chars. Value represents the ID of a government-issued document that was used. MUST be present together with <DocumentType>.
<GivenNames>	0..1	String max 200 chars. Must contain all given names, if given names are not fully known than MUST contain all known Initials. MUST be present together with <SurName>. An empty value can be used to specify the current subject has not registered a given name in the BRP.
<SurName>	0..1	String max 210 chars. Surname including prefixes, as stated on the Identity Document. MUST be present together with <GivenNames>.
<DateOfBirth>	0..1	Date of birth of the user. In XML-schema a choice between 'date', 'gYear' or 'gYearMonth' format. In case the specific day or month is unknown (also expressed as 1900-00-00 or 1900-03-00), the value MUST be expressed as a gYear or gYearMonth.
<PlaceOfBirth>	0..1	String max 40 chars. NB For Dutch places of birth this value MUST correspond to the exact value as listed in table 33 of the logic design of the BRP (see https://publicaties.rvig.nl/) MUST NOT be used for foreign places of birth.

N.B. Only providing the BSN is not deemed to identify a subject with sufficient assurance, additional information must be provided for verification. In general: the more information is provided in the request, the more chance of a unique match with sufficient assurance.

DocumentType and DocumentID will be deprecated and removed in future revisions of this interface.

Response

Consists of a response message <ProvidePPResponse> in the SOAP body of the response message, containing one or more Polymorphic Pseudonyms. In case a response is received, the request resulted in a unique and valid match and the cryptographic transformation of the specified BSN to a Polymorphic Pseudonym and/or Polymorphic Identity. 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>s.

Element/@Attribute	0..n	Description
@DateTime	1	Time of issuing of the response.
@ResponseID	1	Unique identifier of the Response
@InResponseTo	1	Unique identifier of the Request this is a response to (@RequestID of request)
<PolymorphicPseudonym>	1..n	One or more signed Polymorphic Pseudonymization structure(s) for the User. At least one structure MUST be provided, the exact number depends on the request and requester: A <ProvicePPRequest> will receive one Signed Polymorphic Identity and one Signed Polymorphic Pseudonym. A <ProvidePP_PPCAOptimizedRequest> will receive one Signed PIP and one Signed Polymorphic Pseudonym.

For encoding of the Signed Polymorphic Identity / Pseudonym / PIP, see Handreiking Polymorphic Pseudonimization Notation.

FaultReasons

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

ResponseCode	Description
NotEnoughInfo	Request rejected. Provided information may resolve to a unique match, but not enough assurance (e.g. against typos) can be established.
NotUnique	Request rejected. Provided information results in more than one match.
NotFound	Request rejected. Provided information results in zero matches.
DocumentRejected	Request rejected. Document not accepted.
ProvisioningRefused	Request rejected. Activation refused for other non-disclosed reason.
AuthorizationError	Request rejected. Authentication invalid or access denied. A HTTP 403 status response MAY be given instead of a SOAP-fault with this response.
SyntaxError	Request rejected. Request invalid.
TemporarilyUnavailable	Request could temporarily not be processed. A new request for activation MAY be sent at a later moment by the requesting party.