BSNk: activate
The most recent version of the technical BSNk specifications are available on Logius | BSNk PP documentatie or on request (beheerorganisatie BSNk through servicecentrum@logius.nl). The information below is for information only.
This interface between a Machtigingenregister 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 Machtigingenregister.
WSDL
WSDL activate
<?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 Machtigingenregister. |
<RequesterKeySetVersion> | 1 | Key set version of the requesting Machtigingenregister . |
<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. |
<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. |
<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. Nota Bene 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. |
Nota Bene
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:
|
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. |