BSNk: transform
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.
In order to realize step 7 in the AUC3.1 Registreren bevoegdheid eenmanszaken an interface is necessary beween the MR and BSNk. This interface wil implement AUC6 Activeren BSN for the MR. In order to facilitate the transformation of the PI this interface will also implement AUC10 Transformeren. This will allow the MR to transform the PI to the VI of the owner of the sole trader for the DV who requested this information.
This interface describes the message exchange between MR and BSNk. It fulfills two functions: obtaining a Polymorphic Pseudonym and Polymorphic Identity for a newly registered user with the MR (activate) and transforming a Polymorphic Pseudonym or Polymorphic Identity to an Encrypted Pseudonym or Encrypted Identity specialized for a Relying Party.
Interface Transform
This interface between an Machtigingenregisterand BSNk transforms a given Polymophic Pseudonym to a Relying Party specific Encrypted Pseudonym or Polymorphic Identity to an Encrypted Identity. An Machtigingenregister uses this interface after authenticating an User.
WSDL transform
<?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"
name="BSNk_transform"
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="ProvideEPRequest" type="bsnk:ProvideEncryptedRequestType">
<xsd:annotation>
<xsd:documentation>Request message to provide an encrypted
pseudonym of a user for a specific relying party
(service provider).
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="ProvideEIRequest" type="bsnk:ProvideEncryptedRequestType">
<xsd:annotation>
<xsd:documentation>Request message to provide an encrypted
identity of a user for a specific relying party
(service provider).
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:complexType name="ProvideEncryptedRequestType">
<xsd:complexContent>
<xsd:extension base="bsnk:BSNkProvideRequestBasetype">
<xsd:sequence>
<xsd:element name="RelyingParty" type="bsnk:OINType" />
<xsd:element name="RelyingPartyKeySetVersion" type="bsnk:KeyVersionType" />
<xsd:element name="PolymorphicPseudonym" type="bsnk:PolymorphicPseudonymType" />
<xsd:element name="Role" type="bsnk:RoleType" minOccurs="0" />
<xsd:element name="TransactionID" type="bsnk:TransactionIDType" 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:complexType name="PolymorphicPseudonymType">
<xsd:simpleContent>
<xsd:extension base="xsd:base64Binary"/>
</xsd:simpleContent>
</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="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="RoleType">
<xsd:annotation>
<xsd:documentation>Role type.
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:integer"/>
</xsd:simpleType>
<xsd:simpleType name="TransactionIDType">
<xsd:annotation>
<xsd:documentation>TransactionID Type.
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:string">
<xsd:length value="128" />
</xsd:restriction>
</xsd:simpleType>
<xsd:element name="ProvideEPResponse" type="bsnk:ProvideEncryptedResponseType">
<xsd:annotation>
<xsd:documentation>
Response to a ProvideEPRequest.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="ProvideEIResponse" type="bsnk:ProvideEncryptedResponseType">
<xsd:annotation>
<xsd:documentation>
Response to a ProvideEIRequest.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:complexType name="ProvideEncryptedResponseType">
<xsd:complexContent>
<xsd:extension base="bsnk:BSNkProvideResponseBasetype">
<xsd:sequence>
<xsd:element name="EncryptedPseudonym" type="bsnk:EncryptedPseudonymType" />
</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:simpleType name="EncryptedPseudonymType">
<xsd:restriction base="xsd:base64Binary" />
</xsd:simpleType>
<xsd:element name="ProvideEncryptedFault" type="bsnk:ProvideEncryptedFaultType">
<xsd:annotation>
<xsd:documentation>
Fault response to a ProvideEPRequest of ProvideEIRequest.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:complexType name="ProvideEncryptedFaultType">
<xsd:sequence>
<xsd:element name="FaultReason" type="bsnk:ProvideEncryptedFaultReasonType" />
<xsd:element name="FaultDescription" type="bsnk:FaultDescriptionType" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
<xsd:simpleType name="ProvideEncryptedFaultReasonType">
<xsd:union memberTypes="bsnk:FaultReasons bsnk:ProvideEncryptedFaultReasons" />
</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 provisioning MAY be
send at a later moment by the requesting party.
</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="ProvideEncryptedFaultReasons">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="ProvisioningRefused">
<xsd:annotation>
<xsd:documentation>Transformation 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_ProvideEPRequest">
<wsdl:part name="in" element="bsnk:ProvideEPRequest" />
</wsdl:message>
<wsdl:message name="BSNk_ProvideEIRequest">
<wsdl:part name="in" element="bsnk:ProvideEIRequest" />
</wsdl:message>
<wsdl:message name="BSNk_ProvideEPResponse">
<wsdl:part name="out" element="bsnk:ProvideEPResponse" />
</wsdl:message>
<wsdl:message name="BSNk_ProvideEIResponse">
<wsdl:part name="out" element="bsnk:ProvideEIResponse" />
</wsdl:message>
<wsdl:message name="BSNk_ProvideEncryptedFault">
<wsdl:part name="fault" element="bsnk:ProvideEncryptedFault" />
</wsdl:message>
<wsdl:portType name="BSNk_Transform_Port">
<wsdl:operation name="BSNk_ProvideEP">
<wsdl:input message="bsnk:BSNk_ProvideEPRequest" wsam:Action="urn:nl-gdi-eid:1.0:webservices:ProvideEPRequest" />
<wsdl:output message="bsnk:BSNk_ProvideEPResponse" wsam:Action="urn:nl-gdi-eid:1.0:webservices:ProvideEPResponse" />
<wsdl:fault message="bsnk:BSNk_ProvideEncryptedFault" name="BSNk_ProvideEncrypted_Fault"/>
</wsdl:operation>
<wsdl:operation name="BSNk_ProvideEI">
<wsdl:input message="bsnk:BSNk_ProvideEIRequest" wsam:Action="urn:nl-gdi-eid:1.0:webservices:ProvideEIRequest" />
<wsdl:output message="bsnk:BSNk_ProvideEIResponse" wsam:Action="urn:nl-gdi-eid:1.0:webservices:ProvideEIResponse" />
<wsdl:fault message="bsnk:BSNk_ProvideEncryptedFault" name="BSNk_ProvideEncrypted_Fault"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="BSNk_Transform_SOAP" type="bsnk:BSNk_Transform_Port">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http" />
<wsdl:operation name="BSNk_ProvideEP">
<soap:operation soapAction="urn:nl-gdi-eid:1.0:webservices:ProvideEPRequest" />
<wsdl:input>
<soap:body use="literal" />
</wsdl:input>
<wsdl:output>
<soap:body use="literal" />
</wsdl:output>
<wsdl:fault name="BSNk_ProvideEncrypted_Fault">
<soap:fault name="BSNk_ProvideEncrypted_Fault" use="literal" />
</wsdl:fault>
</wsdl:operation>
<wsdl:operation name="BSNk_ProvideEI">
<soap:operation soapAction="urn:nl-gdi-eid:1.0:webservices:ProvideEIRequest" />
<wsdl:input>
<soap:body use="literal" />
</wsdl:input>
<wsdl:output>
<soap:body use="literal" />
</wsdl:output>
<wsdl:fault name="BSNk_ProvideEncrypted_Fault">
<soap:fault name="BSNk_ProvideEncrypted_Fault" use="literal" />
</wsdl:fault>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="BSNk_Transform_Service">
<wsdl:port binding="bsnk:BSNk_Transform_SOAP" name="BSNk_Transform">
<soap:address location="https://.../TODO/Transform" />
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
Request
Consists of a transformation request message <ProvideEPRequest> or <ProvideEIRequest> 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. |
<RelyingParty> | 1 | EntityID (OIN) of the intended relying party. |
<RelyingPartyKeySetVersion> | 1 | Key set version to be used for relying party. |
<PolymorphicPseudonym> | 1 | Polymorphic Pseudonymization structure for the user to be transformed to an encrypted pseudonym or identity. Only one (non-signed) Polymorphic Pseudonym / Identity MUST be present, depending on the request type. |
<Role> | 0..1 | Optional "persoonsrol". Reserved for future use where the same user can act in different roles, e.g. private, volunteer and employee. |
<TransactionID> | 0..1 | Optional "transactie ID". Reserved for future use where privacy prohibits use of a persistent pseudonym. TransactionID can be used to create a transaction-, session- or case- specific pseudonym. Also for guarantees for the 4-eyes principle, TransactionID can be used in combination with the default Role (otherwise a person could break a 4-eyes signature by using two different Roles). Another example is eIDAS that requires a pseudonym per EU country, for which a countryID can be used als TransactionID to make the resulting pseudonym specific and persistent per country. |
Rules for processing a Transformation Request
A requesting MachtigingsRegister:
- MUST authenticate a User at the requested Level of Assurance before requesting a transformation.
- MUST check the relying party is listed in the Autorisatielijst BSN as authorized before requesting transformation of a PI.
- For ETD this requirement is implemented via the (aggregation) of the ServiceCatalog (by the BO ETD).
- MUST only provide a PP for a <ProvideEPRequest> and MUST only provide a PI for a <ProvideEIRequest>.
- SHOULD randomize the PP/PI to be transformed before requesting a transformation, to enhance the privacy of the User.
Response
Consists of a response message <ProvideEPResponse> or <ProvideEIResponse> in the SOAP body of the response message, containing an Encrypted Pseudonym or Encrypted Identity for the requested Relying Party. 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) |
<EncryptedPseudonym> | 1 | Resulting encrypted form Polymorphic Pseudonymization structure resulting from the transformation. One Signed Encrypted Pseudonym or Signed Encrypted Identity structure for the User for the RelyingParty MUST be present, depending on the request type. |
For encoding of the (Signed) Encrypted Pseudonym / Identity, see Polymorphic Pseudonymization Notation.
Rules for processing a Transformation Response:
A receiving MachtigingsRegister:
- SHOULD pass the resulting Signed Encrypted Pseudonym or Signed Encrypted Identity structure unaltered to the relying party.
FaultReasons
The following response codes are used to indicate the status of a response.
ResponseCode | Description |
---|---|
ProvisioningRefused | Request rejected. Transformation of a Polymorphic Pseudonym refused for 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 transformation of a Polymorphic Pseudonym or Polymorphic Identity MAY be sent at a later moment by the requesting party. |