Terms and conditions

Terms and conditions for provision of the iDIN Merchant Implementation Guidelines:

• Currence Services BV (also referred to as ‘Currence’) provides these iDIN Merchant Implementation Guidelines to Merchant Banks that distribute it to (potential) Merchants and Digital Identity Service Providers (DISPs) to enable them to implement iDIN;

• Currence reserves the right to deny access to the iDIN Merchant Implementation Guidelines to (potential) Merchants and DISPs on reasonable grounds, in consultation with the Merchant Bank with which the Merchant/DISP has a contract;

• These Implementation Guidelines are explicitly and exclusively provided for the purpose mentioned above, and no other use is permitted. No rights can be derived from the information provided in this document or the accompanying notes. Currence is in no way liable for the consequences of later changes to the iDIN Standards or the iDIN Merchant Implementation Guidelines. If banks or other interested parties take decisions and/or make investments on the basis of the information that they obtain via the iDIN Merchant Implementation Guidelines, Currence accepts no liability for this in any way;

• These implementation Guidelines are based on the information in the iDIN Standards documents. In the event of any discrepancy between the iDIN Merchant Implementation Guidelines and the iDIN Standards documents, the text in the iDIN Standards documents prevails.

For any questions concerning this document or requests for further information, please contact your Bank or DISP. 

Contents

1. General Introduction 

2 Overview

This chapter gives a description of the general elements of iDIN.

2.1 The four-corner model

The iDIN system is based on the ‘four-corner’ model. Figure 1 shows the roles in this model, along with their mutual primary relationships in the context of iDIN. The roles are those of Consumer, Merchant, Acquirer, Issuer, Routing Service and Validation Service and the Digital Identity Service Provider (DISP)[1]:

• The role of Consumer is fulfilled by a natural person, holding credentials provided by the Issuer;

• The role of Merchant must be fulfilled by a legal entity that wishes to identify its Consumers in an authentic manner;

• The role of Acquirer must be fulfilled by a legal entity, providing iDIN services to its Merchants;

• The role of Issuer must be fulfilled by a legal entity, providing digital identities and credentials to its Consumers;

• The role of Routing Service must be fulfilled by an Acquirer or by a third party endorsed and contracted by an Acquirer;

• The role of Validation service must be fulfilled by an Issuer or by a third party endorsed and contracted by an Issuer;

• The role of Digital Identity Service Provider (DISP) must be fulfilled by a third party, which is endorsed and contracted by the Acquirer as well as the Merchant.

  • The role of DISP /Ondertekendienst: a DISP certified for iDIN Ondertekenen. Within the iDIN Scheme we refer to such a party "DISP / Ondertekendienst" because it is a special (sub-) form of a DISP. Signing Service Provider (SSP) is used in the external communication and in the remainder of this document.

2.1.1 The relations between these roles

Both contractual and technical relations exist between the roles. These are described below.

Contractual relations:

• Merchant - Acquirer: The Merchant has a contract with an Acquirer;

• Consumer - Issuer: The Consumer has a contract with the Issuer. The identity related to this contract is used for identification, authentication, signing and provisioning of attributes of the Consumer;

• Consumer - Merchant: The Consumer may use iDIN services at the Merchant domain to access the service supplied by the Merchant;

• Acquirer - Issuer: Bound by a license agreement with the iDIN scheme.

Technical relations:

• Merchant - Routing Service: The Merchant has a technical relation with the Routing Service. The Routing Service offers the Merchant the possibility of sending iDIN requests to a Validation Service. They exchange messages to this end;

• Routing Service – Validation Service: The Routing Service and Validation Service have an iDIN solution relationship. They exchange messages in this context;

• Consumer – Validation Service: The Validation Service offers the Consumer the possibility of using their iDIN towards Merchants, by using the credentials issued by the Issuer.

Open

^{Figure 1: Four-corner model}

2.1.2 Exceptions for DISPs or SSPs

In a model where a Merchant outsources its iDIN activities to a SSP or DISP[1] the contractual relation between Merchant - Acquirer is replaced by the following relations:

• Merchant – SSP or DISP: The Merchant has a contract with a DISP;

• SSP or DISP - Acquirer: The SSP or DISP has a contract with an Acquirer.

The technical relation between Merchant - Acquirer is replaced by the following relations:

• Merchant – SSP or DISP: The Merchant has a technical relation with the SSP or DISP. The SSP or DISP offers the Merchant the possibility of sending iDIN requests to a Routing and Validation Service. They exchange messages to this end;

• SSP or DISP - Routing Service: The SSP or DISP has a technical relation with the Routing Service. The Routing Service offers the SSP or DISP the possibility of sending iDIN requests to a Validation Service. They exchange messages to this end.

[1] For due diligence reasons, the SSP or DISP may be subject to extra audits

2.2 iDIN services

This paragraph introduces the iDIN services offered to both Merchants and Consumers.

iDIN facilitates the following services:

• Identification of Consumers based on Issuer issued credentials

• Age verification of Consumers based on Issuer issued credentials

• Login of Consumers using Issuer issued credentials

• Signing of documents by Consumers using Issuer issued credentials

Note: In this document the iDIN process of providing one of the above services is referred to as an iDIN transaction.

The services provided by iDIN can be used by the Merchant, amongst others, to:

• Set-up new user accounts for Consumers in the Merchant’s domain based on the identification and/or attributes provided by the Issuer;

• Login of existing users that created their account with iDIN, or connected an existing account with iDIN;

• Age verification.

• Signing of documents

The level of assurance for iDIN is “Substantial”. This has been determined in accordance with the iDIN Rules & Regulations and is based on the eIDAS EU Regulation 2015 / 1502. The EU Regulation sets requirements for, among other things, identifying the consumer, the authentication tools and the use thereof. These requirements have been included in the iDIN Rules & Regulations. This roughly corresponds to the older STORK assurance level LOA3, which is still used in this technical standard. The level of assurance doesn’t relate to interoperability or cross border acceptance of iDIN.

2.3 iDIN process

At the Merchant website the Consumer initiates the process by selecting iDIN for authentication/provisioning of attributes and/or signing of documents, and subsequently selects an Issuer from the Issuer list. The Consumer will then be forwarded to his/her Issuer’s secure environment where he/she can continue with the Issuer’s authentication process (based on the credentials that were issued to the Consumer by the Issuer). After successfully authenticating at the Issuer, the Consumer can approve or cancel the iDIN transaction. The Consumer will then be redirected back to the Merchant website. The Merchant receives the requested authentication/attributes and or the consumers' signature if the Consumer has approved the transaction.

2.4 iDIN transaction

The result of an iDIN transaction can be delegated authentication, provisioning of attributes (including age verification), signing of documents or a combination.

2.4.1 Delegated authentication

In an iDIN transaction, the Merchant can request a unique, Merchant-specific persistent identifier (BIN) of the Consumer. This allows the Merchant to link the Consumer session to an already existing user account at the Merchant’s system that contains the same BIN, or offer the option to create a new account for the Consumer when the BIN is not yet present in the Merchant’s system. By approving the transaction, the Consumer consents to logging in at the Merchant’s website.

2.4.2 Providing consumer attributes

In an iDIN transaction, the Merchant can request attributes, possibly used in the context of signing a document, of the Consumer. To this end, at the Issuer website the Consumer explicitly consents to provide the requested attributes to the Merchant. Attributes cannot be requested (and provided) individually, but only as bundled in one of the three[3] attribute groups that are specified as: name, address and age related. See Section 5.3.1 and Section 5.4 for more details. Consent is always given for all requested attributes as a whole, not per data set or per attribute. However, the Merchant is free to ask the Consumer on its website/application, before initiating the transaction, which attribute groups the Consumer would like to give to the Merchant.

Note: Due to possible movement of Consumers it is advised to Merchant to always check the correctness of the address. Also, when dealing with a delivery, the Consumer might want to deliver to another address then his/her residential address.

Consumer attributes can be requested on a one-time basis, without linking the Consumer session to previous or future sessions, or to an existing user account.  In that case, the Merchant will request and receive a transient identifier (transient meaning temporary), generated by the issuer for this session. In case attribute provisioning is combined with delegated authentication, the Merchant requests and receives the persistent BIN.

The Merchant can easily set up a new account for the Consumer in the Merchant’s domain based on the BIN and attributes provided by the Issuer.

Note that the consumer should always be aware when using iDIN to create a new Consumer account, in order to prevent the Consumer from connecting whilst already having another account at the Merchant. When connecting a Consumer to an existing account, simply matching consumer attributes with the entire database of the Merchant is an erroneous method, because certain Consumers can share the same attributes (e.g. first and last name). First letting the Consumer log in the Consumer to the existing account before connecting the account with iDIN, or connecting with additional unique Consumer information (not provided by Issuer e.g. email address), should counteract this Issue.

2.5 Merchant registration

When registering for iDIN, the Acquirer issues a Merchant.MerchantID and a Merchant.LegalID to the Merchant that is associated with the Merchant.Name. If required, the Merchant also receives a Merchant.SubID to register one or more Merchant.TradeName. This is the case when a Merchant performs iDIN transactions under different trade names. Only the Merchant.MerchantID and Merchant.SubID are relevant to the Merchant, that is, the Merchant only has to use these to fulfil a successful iDIN process. The other identifiers are allocated by the Acquirer and used within the Acquirer-Issuer and Issuer-Consumer domain.

2.6 Dispute management

In case of a dispute, the Issuer must be able to provide the identity of the Consumer. During such a dispute the following steps must be executed:

• The Merchant must supply the original SAML iDIN message that holds the Consumer identity to the Merchant’s Acquirer. To ensure the Issuer can read the encrypted attributes, the Merchant must decrypt the AES keys with his private key. The AES keys have to be provided along with the original message;

• The Acquirer forwards this information to the Issuer, with contact information of the Merchant;

• The Issuer must use the certificate from the message to verify the electronic signature, thereby establishing the authenticity and integrity of the iDIN message. The Issuer must take into account the need for an application to be able to perform these checks;

• By using the AES keys provided by the Merchant, it can be easily verified whether these keys are in fact the correct keys;

• In case a message is authentic, the Issuer must provide Consumer details to the Merchant and/or Consumer directly. This can only be done if the Consumer has given his/her consent;

• Providing the details has to be done via telephone[4] where:

• The Acquirer must provide the telephone number of the Merchant to the Issuer;

• The Issuer must initiate the call to the Merchant/Consumer to prevent misuse.

3 iDIN protocols

This chapter gives a general description of the iDx protocols, which are used as a messaging standard for iDIN.

3.1 Basic technical principles

• All iDIN processes are initiated on the Merchant website by the Consumer;

• iDIN uses the iDx standards as a messaging standard. It uses the generic information container in the iDx protocol to embed SAML 2.0 messages for iDIN specific elements;

• Consumers will be persistently identified using a Bank Identification Number (BIN), see Section 0, which will be Issuer generated (so not shared among Issuers) and unique per Consumer-Merchant combination;

• A Consumer has only one identity per Issuer, regardless of the number of credentials;

• Consumer information in messages will be shielded from Acquirers (Routing Service) by means of end-to-end encryption.

3.2 iDx protocols

The iDIN process (request-/response-XML messaging and browser redirects) consists of the following protocols:

• The Directory protocol: used to retrieve the most recent Issuer list from the Routing Service.

• The Transaction protocol: the iDIN-transaction process from beginning to end.

• The Status protocol: used to request the status of a transaction from the Validation Service (via the Routing Service).

• The Error protocol: used to inform when errors have occurred.

A specific name (letter) has been assigned to identify each message. The following table applies:

^{Table 4: Message names and description}

The sequence of the protocols is shown in Figure 2. In order to retrieve the services provided by iDIN both the Transaction and Status Protocol have to be completed. The Directory protocol is not indicated, because it follows a simple request and response from the Merchant to the Acquirer.

Open

3.2.1 Directory protocol

By using the Directory protocol, the Merchant sends a DirectoryReq to the Routing Service. This is a request in XML format to obtain the list of participating Issuer Banks from the Routing Service. The Routing Service will provide this list to the Merchant by sending back the DirectoryRes. The Merchant will show the list of banks, which were sent in the DirectoryRes to the Merchant. The Consumer will choose his bank from this list at the beginning of the iDIN process. The Directory protocol is explained in more detail in Chapter 6.

3.2.2 Transaction protocol

By using the Transaction protocol the Merchant sends an AcquirerTrxReq to the Routing Service, containing the ID of the Issuer Bank chosen by the Consumer, iDIN information (requesting consumer authentication, attributes or age verification) and other transaction details. This message also contains the merchantReturnURL. This URL is used by the Validation Service to redirect the Consumer back to the Merchant’s website when he has completed the iDIN transaction in the Issuer domain. After the Routing Service has received the message from the Merchant the message is send to the Validation Service of the Issuer that was selected by the Consumer (after adding some information which is beyond the scope of the Merchant).

In return, the Validation Service responds with the IssuerTrxRes message that contains amongst others the issuerAuthenticationURL. The Routing Service forwards this issuerAuthenticationURL together with a unique Transaction.TransactionID back to the Merchant in an AcquirerTrxRes.

3.2.2.1  Redirect

The Merchant now redirects the Consumer to the issuerAuthenticationURL, which refers to the page of the online banking portal. This takes the Consumer to his internet-banking environment where he can continue the iDIN transaction (i.e. logging in and approve the transaction).

The Issuer adds Consumer information (consumer authentication, attributes or age verification) to the iDIN transaction which can be later retrieved with the AcquirerStatusReq. The Consumer approves the iDIN request and receives a confirmation from the Issuer. The Consumer is then redirected back to the website of the Merchant via the merchantReturnURL. The entire Transaction protocol and the 2 redirects are described in more detail in Chapter 7.

3.2.3 Status protocol

Finally the Merchant initiates the Status protocol by sending an AcquirerStatusReq message to the Routing Service. The Routing Service will request the transaction status from the appropriate Issuer and returns the status to the Merchant in the AcquirerStatusRes. If all steps in the transaction are successful this status message contains the iDIN consumer authentication, attributes and/or age verification. Chapter 8 contains more detailed information on the Status protocol.

3.2.4 Error protocol

Instead of a regular response to the messages mentioned above, it is also possible that an AcquirerErrorRes is returned. This can be the case if a request (DirectoryReq, AcquirerTrxReq or AcquirerStatusReq) contains an error, or if an error occurs during the processing of the request. The AcquirerErrorRes messages are discussed in Chapter 9.

3.3 SAML V2.0

iDIN uses the iDx standards as a messaging standard. However, it uses the generic information container in the iDx protocol to embed SAML 2.0 messages for iDIN specific elements. This container is only used in the AcquirerTrxReq, AcquirerStatusRes and sometimes in AcquirerErrorRes. For the other messages the container is left empty.

4 iDIN Message format 

4.1 General

This chapter contains a description of the general message structure for the Directory, Transaction, Status, and Error protocol. The subsequent sections will describe the specific fields within the XML messages for each protocol in more detail. A list of the data elements and their format can be found in the data dictionary in Chapter 5.

The following conventions are used to indicate whether a message element is mandatory:

• Yes The element must occur exactly once;

• Yes (1..∞) The element must occur one or more (unlimited) times;

• No The element may be left out or may occur exactly once;

• No (0..∞)    The element may be left out or may occur more (unlimited) times.

4.2 Character set

• In all iDIN messages the Unicode character set must be used. Only the MES-2 subset must be supported;

• Encoding must be used as indicated in the HTTP and XML headers UTF-8 (Unicode Transformation Format);

• The use of characters that are not part of the Unicode character set will not lead to a refusal of a post, but the character may be changed to a space, question mark or asterisk in transit;

• The Byte Order Mark (BOM) must not be used. The UTF-8 representation of the BOM is the byte sequence 0xEF,0xBB,0xBF.

4.3 HTTP

• All messages must comply with the HTTP 1.1 standard, as defined in RFC 2616 of W3C. For more information: http://www.w3.org/Protocols/rfc2616/rfc2616.html;

• Each XML request message must be sent as the body of a HTTP POST message;

• Each XML response message must be sent as the body of a HTTP 200 OK message.

The following HTTP header must be used for all messages:

^{Table 5: HTTP header}

4.4 XML header

The following XML header must be used for all messages:

^{Table 6: XML header}

4.5 XML namespaces

iDIN uses the iDx standards as a messaging standard. It uses the generic information container (an XML element) in the iDx protocol to embed SAML 2.0 messages for iDIN specific elements. In addition to the namespaces of the iDx messages, several namespaces are declared in the SAML message.

The namespaces for all messages described in this document is as follows:

Table 7: iDx namespaces

Namespace declaration can be done in any way allowed by the XML standards (default namespace declaration or namespace qualification/prefixes) with only a few exceptions as discussed in Section 10.3 where all namespace declaration must be present inside the encrypted parts of the message.

4.6 XML Schemas

All messages must be validated against the iDIN, SAML 2.0 and W3C Schemas. The schemas names and locations are shown in the following table:

^{Table 8: XML schemas}

5 iDIN data dictionary 

This chapter describes the data elements and ID’s that are used in iDIN.  First, two attributes for all iDx messages are described in Section 5.1. All iDx data elements are described in Section 5.2. Subsequently, in Section 5.3 the iDIN specific data elements are described, which are either located in the SAML message, or differ from the normal iDx formatting. Section 5.4 provides a list of all consumer attributes.

5.1 iDx attributes

The following two attributes are given to the root of each message to ensure proper identification of the correct service and version:

^{Table 9: iDx attributes}

5.2 iDx data elements

iDIN relies on the identifiers described in Table 10. If the element must be generated as an input in one of the three request messages (DirectoryReq, AcquirerTrxReq, AcquirerStatusReq) it is indicated in the description in bold.

^{Table 10: iDx data elements}

5.3  iDIN data elements

These elements are the iDIN specific data elements that are either located in the SAML 2.0 message, or, differ from the normal iDx standard. If the element must be generated as an input in one of the three request messages (DirectoryReq, AcquirerTrxReq, AcquirerStatusReq) it is indicated in the description in bold.

^{Table 11: iDIN data elements in SAML message}

5.3.1 iDIN Requested- and DeliveredServiceID

iDIN provides services that can be requested by the Merchant. Each transaction request can only supply one set of data, based on a single RequestedServiceID. The returned consumer attributes can differ per Issuer and request, therefore some of these elements that are part of a group are optional e.g. some consumers do not have a last name prefix. The DeliveredServiceID is used to indicate which attributes are delivered conform the minimal set as defined in Section 8.5. In most cases the RequestedServiceID shall be equal to the DeliveredServiceID. If the Issuer cannot provide all attributes conform the minimal set the DeliveredServiceID is not equal to the RequestedServiceID. This is discussed in more detail in Section 15.4.

The Excel ‘1711289A_ServiceID_Calculator’ provided along this Implementation Guidelines provides an easy method to calculate the ServiceID.

The Requested- and DeliveredServiceID are short integers translated from a binary format. The binary numbers are separated into groups. These groups represent the categories of attributes the Merchant may request. Please be aware that this is a bit pattern instead of a number, and that the first bit is on the left not on the right.

Table 12 provides an overview of which attributes are included and what value it should represent on binary level in order to receive the correct attributes, as defined in Section 8.2.

^{Table 12: Overview of Requested- and DeliveredServiceID}

The service IDs are included in the SAML request message to specify part of the Merchant’s request. For example, if the Merchant wishes to do an authentication (by requesting the BIN), only the second bit should be equal to one, which leads to an integer value of 16384.

5.4  Consumer attributes

The consumer attributes are located in the SAML 2.0 message as a result of the requested service with the BankID.RequestedServiceID. The consumer.bin and consumer.transientid are not defined as consumer attributes and are located at a different place in the SAML 2.0 message. iDIN can provide the following attributes about a Consumer in a SAML Response message AttributeStatement. Where possible, the consumer attributes have formatting rules in line with the NEN-ISO 8601 standard. All attributes use the UTF-8 character set.

^{Table 13: Consumer attributes}

Notes:

• Consumer attributes are located in the SAML Attribute element. In the @Name attribute the Name indicated above is prefixed with the following “nl:bvn:bankid:1.0:attribute:”. This results in attribute names containing only small-caps letters e.g. “nl:bvn:bankid:1.0:attribute:consumer.city”;

• If one of the attributes is longer than the NEN-prescribed maximum length, then the name is truncated and the last character is replaced by a dash “-” (NEN 1888_2002, p14);

• Some of the name or address related attributes might not be available at all Issuers, e.g., Consumer’s partner last name. In that case the Issuer shall not include the attribute in the attribute statement provided. Example of SAML Attribute:

5.5 Guaranteed minimal set of requested attributes

Table 14 shows the minimal set of attributes that must be provided by the Issuer for the name and address attributes when these are requested by the Merchant. The other categories (Consumer IDs, age related and gender) are requested and provided individually, and therefore must always be delivered to the Merchant upon request conform the specified format (i.e. when the Merchant requests a date of birth the Issuer must provide this, and not some other form of age verification).

If the Issuer is unable to provide the attribute groups conform this minimal set, or cannot provide one or more of the individually requested ID, gender and/or an age related attributes, it fails to respond with a complete success. When this occurs the Issuer returns all attributes and/or an ID it can deliver (which are part of the categories requested by the Merchant), but indicates with a status code that the request could not be performed with a complete success, see Section 15.4 for more detail. For this scenario the DeliveredServiceID is not equal to the RequestedServiceID.

^{Table  14: Minimal set of attributes provided by Issuer per requested attribute group}

5.5.1 Optional deselecting/changing of telephone nr. or email address by the Consumer

Consumers are given the option to deselect and optionally change their email address and/or telephone number when they are approving the transaction at the Issuer. This is only possible for the telephone number and or email and of course only if these attributes are requested by the Merchant.

If the Consumer deselects his/her telephone number and/or email address this is indicated to the Merchant in the DeliveredServiceID and the 2^nd SAML StatusCode, see Section 15.4 for more detail.  

If the Consumer changes his/her telephone number and/or email address this is not indicated to the Merchant. However, if Consumers change their telephone number and/or email address the attributes do abide to the formatting requirements as described in Table 13.

6 iDIN Directory protocol 

6.1 General

The Directory protocol allows a Merchant to retrieve an up to date list of participating Consumer Banks (Issuers) from his Routing Service, which can be presented to the Consumer. In case of changes in the list of Issuers, the Directory protocol will supply the Merchant with the update of this list.

It is not allowed to perform the Directory protocol for each transaction. Since the list of Issuers only changes occasionally, it is sufficient to execute the Directory protocol on a weekly basis and check if the list has changed based on the directoryDateTimestamp. If the Issuer list has changed, the latest version has to be saved and used for any subsequent transaction. Routing Services will normally also inform all Merchants (e.g. by email) about changes in their Issuer list. The Directory protocol should at least be executed once a week.

The Directory protocol (like the Transaction protocol and the Status protocol) consists of a HTTP POST request from the Merchant to the Routing Service, followed by a HTTP response. The DirectoryReq is sent to the URL that is provided to the Merchant by the Routing Service for this specific purpose. This URL can be different from the one that is used for the AcquirerTrxReq and the AcquirerStatusReq, but it can also be the same URL.

The Routing Service validates the authenticity of the message sent by the Merchant by verifying the signature in the message. To do this, the Routing Service needs the public part of the Merchant’s Certificate, including the public key. The way in which the Merchant’s certificate is communicated with the Routing Service varies per bank.

Please refer to Chapter 10 for more information on authentication and security. APPENDIX B shows an example of a DirectoryReq and DirectoryRes.

6.2 Directory Request (DirectoryReq)

The DirectoryReq consists of an XML message that is sent to the Routing Service with HTTP POST.

Table 15 shows all elements and attributes of the DirectoryReq:

^{Table 15: Elements/attributes of the DirectoryReq}

6.3 Directory Response (DirectoryRes)

The Merchant will receive the DirectoryRes as a reply to the DirectoryReq. This XML message contains a list of pairwise Issuer.Name and Issuer.IssuerID. Issuers are grouped by country. The Issuers in the Consumer’s country of choice may be presented at the top in the Issuer selection list, the rest is sorted alphabetically, first by country, then by name. Table 16 shows all elements and attributes that appear in the DirectoryRes message.

^{Table 16: Elements/attributes of the DirectoryRes}

6.4 Presentation of the Issuer Bank selection list

The Merchant bears primary responsibility for initiating the iDIN process and for the communication to the Consumer regarding the status of this process. Merchants who offer iDIN to their customers must include iDIN in their lists of authentication methods, methods to log on, age verifications methods and/or methods for signing of documents (if any). iDIN must be presented in the list of methods in such a way that it receives at least the same amount of attention as all other competitors. It must be clear for the Consumer that he is about to authenticate with iDIN. The Merchant must clearly indicate to the Consumer what iDIN service he is about to initiate for the Consumer.

To ensure that the Consumer experience of an iDIN transaction is consistent and recognisable through all Merchant websites; all Merchants have to comply with certain presentation standards.

Merchants are not allowed to remove Issuers temporarily from the Issuer selection list or to grey them out. An exception is made for the presentation of the Issuer list in case of iDIN Signing. The SSP may only present to the Consumer Issuers who offer iDIN Signing. A list of Issuers who have implemented the product type Signature can be requested at iDIN B.V. (idin@betaalvereniging.nl). 

If a Merchants learns via the iDIN Notification System (Central Reporting tool for iDIN Validation Services and Routing Services to state system non-availability) or via error messages received from the Acquiring bank that a particular Validation Service is currently not available, the Merchant may display a message on its website informing Consumers that the particular bank is currently not available. In other words, it is permissible to display a message conveying such information but it is not permissible to temporarily remove or grey out the Issuer concerned from the Issuer selection list.

7 iDIN Transaction protocol 

7.1 General

The Transaction protocol initiates the exchange of messages of the actual iDIN process. After the Consumer has chosen iDIN as an identification method and has selected his bank, the Merchant sends a Transaction Request to the Routing Service. Within the iDIN standards this message is referred to as the AcquirerTrxReq. The Routing Service replies to the AcquirerTrxReq with a Transaction Response (AcquirerTrxRes). This AcquirerTrxRes will also (among other fields) contain the issuerAuthenticationURL. This URL will redirect the browser of the Consumer to the Issuer in order to let him authorise the iDIN transaction.

The Transaction protocol consists of a HTTP POST request from the Merchant to the Routing Service, followed by a HTTP response. The AcquirerTrxReq is sent to the URL that is provided to the Merchant by the Routing Service for this specific purpose. This URL can be different from the one that is used for the DirectoryReq and the AcquirerStatusReq, but it can also be the same URL.

The Routing Service validates the authenticity of the message sent by the Merchant by verifying the signature in the message. To do this, the Routing Service needs the public part of the Merchant’s Certificate, including the public key. The way in which the Merchant’s certificate is communicated with the Routing Service varies per bank.

Please refer to Chapter 13 for more information on authentication and security. APPENDIX B shows an example of an AcquirerTrxReq and AcquirerTrxRes.

7.2 Transaction Request (AcquirerTrxReq)

The XML message sent by the Merchant to the Routing Service to initiate the transaction contains the elements and attributes shown in Table 17. The iDIN product specific information (SAML 2.0 message) is put inside the container element in the AcquirerTrxRes in the form of an AuthnRequest, as shown in Table 18.

^{Table 19: Elements/attributes of AcquirerTrxReq}

As explained, the SAML 2.0 AuthnRequest message is embedded in the container element. The AuthnRequest message is a standardised message, so it contains elements that are not used in iDIN. This elements and attributes inside the container are shown in Table 18.

^{Table 18: Elements/attributes inside the container of the AcquirerTrxReq}

7.3 Transaction Response (AcquirerTrxRes)

If everything goes well the Routing Service will reply to the AcquirerTrxReq with the AcquirerTrxRes. Table 19 shows all fields of the AcquirerTrxRes message. The AcquirerTrxRes has no container, so there is no SAML 2.0 message in this response (this is different in case of an Error Response, see Chapter 9 on error handling).

^{Table 19: Elements/attributes of AcquirerTrxRes}

7.4 Errors when executing Transaction Protocol

A number of errors may occur when executing the iDIN Transaction Protocol. These may be related to unavailability or an error within your own web environment (Merchant), the Routing Service environment or the Validation Service environment.

The following situations may occur:

• You receive an error response (message B’(X) ) from your Routing Service within the set time-out period;

• You do not receive any response within the set time-out period.

In all of the above cases, the Transaction protocol cannot be successfully executed. This means it is not possible for the iDIN transaction to take place at that time. Error handling is explained in more detail in Chapter 12.

7.5 Redirect to the online banking environment

After receiving the AcquirerTrxRes the Merchant has to redirect the Consumer to the issuerAuthenticationURL of the selected Issuer, as stated in the AcquirerTrxRes message. If the Merchant’s page contains HTML frames, these will be removed by the Issuer (‘frame busting’). If and when the Consumer returns to the Merchant’s website (with the merchantReturnURL), the Merchant will have to completely rebuild its own page to show confirmation of iDIN reception.

7.6 Redirect to the Merchant environment

After the Consumer has performed the necessary steps at the Issuer he/she will be presented with a ‘Continue’ button that must redirect him back to the website of the Merchant with the merchantReturnURL as supplied in the AcquirerTrxReq.

Two GET parameters are appended to this URL: the entranceCode (see Table 10) with ‘ec’ as GET parameter name, and the Transaction.TransactionID (see Table 10) with ‘trxid’ as GET parameter name. It is also possible for a Merchant to add additional parameters. For example, if the Merchant defines the merchantReturnURL as follows:

http://www.webshop.nl/processtransaction?producttype=electronics

The final URL will look something like:

http://www.webshop.nl/processtransaction?producttype=electronics&trxid=0010123456789012&ec=4hd7TD9wRn76w6gGwGFDgdL7jEtb

The entranceCode field should contain a unique value, with the object of preventing message ‘sniffing’. Use of the same entranceCode each time would allow malevolent individuals to intercept the data from the merchantReturnURL and make fraudulent use of this information. This is why using unique values for the entranceCode is extremely important.

Note that a Consumer may not always use the redirect back to the Merchant environment that is offered by the Issuer. Also note that in exceptional cases the Issuer may be unable to match the Transaction.TransactionID in its system or another error occurs, which makes it impossible to redirect the Consumer back to the Merchant. In all other cases the Consumer is redirected with the parameters defined above, regardless of the final status of the transaction (success, cancelled, failed). The Merchant must then use the Status protocol (see Chapter 11) to determine the status of the transaction.

The following errors may occur during execution of the redirect to the online banking environment (Issuer), the execution of the iDIN transaction at the Issuer and/or the redirect back to your (Merchant) environment:

1. The bank page is unavailable, resulting in the Consumer being unable to approve the iDIN request, and thus the Consumer cannot be properly redirected to your confirmation page;

2. The bank page is available but the Consumer cannot (after approving the iDIN request or otherwise) be properly redirected to your confirmation page.

In both situations the Consumer cannot (as the result of a disturbance) return to your confirmation page in the normal way. In that case the Consumer can return to your website by using the ‘back’ button or entering the URL, for example. Considering the short validity of the Assertion the Merchant would be unable to retrieve the status of the transaction. More precisely, the Merchant is only allowed to request the status when the Consumer is successfully returned to the Merchant’s website using the return URL, see Section 11.5. Therefore, the Merchant has to make a new transaction when something has gone wrong in the redirections.

7.9 Performance and time-out of transaction message

The performance of the Issuer and Routing Service systems has a direct influence on the Consumer’s user experience. Therefore, iDIN sets a target time and time-out for the Transaction Response message. For a Merchant the relevant target time and time-out concerning the communication with its iDIN Routing Service is: 

^{Table 25: Performance requirements (for the 95th percentile[7])}

The target time is the time (in seconds) in which the Merchant should receive a AcquirerTrxRes message after sending a AcquirerTrxReq. The time-out is the length of time after which the Merchant should no longer expect a response (most likely an error has occurred) and should act accordingly (for example by displaying an appropriate error message to the Consumer).

8 iDIN Status protocol

8.1 General

To verify whether an iDIN transaction was successful the Merchant will start the Status protocol by sending a Status Request to the Routing Service. Within the iDIN standards this message is referred to as the AcquirerStatusReq.

To avoid unnecessary system load status requests should not be made unnecessarily, see Section 11.5 for more details on what is allowed. The AcquirerStatusReq message can be sent after the return of the Consumer to the Merchant’s website (after the redirect from the Issuer).

Status protocol consists of a HTTP POST request from the Merchant to the Routing Service, followed by a HTTP response. The AcquirerStatusReq is sent to the URL that is provided to the Merchant by the Routing Service for this specific purpose. This URL can be different from the one that is used for the DirectoryReq and the AcquirerTrxReq, but it can also be the same URL.

The Routing Service validates the authenticity of the message sent by the Merchant by verifying the signature in the message. To do this, the Routing Service needs the public part of the Merchant’s Certificate, including the public key. The way in which the Merchant’s certificate is communicated with the Routing Service varies per bank.

Please refer to Chapter 13 for more information on authentication and security. Appendix B shows an example of an AcquirerStatusReq and AcquirerStatusRes.

8.2 Status Request (AcquirerStatusReq)

Table 26 contains all fields that are part of the AcquirerStatusReq XML message. The Merchant sends this message to the Routing Service. The AcquirerStatusReq does not contain a container with a SAML 2.0 message.  

^{Table 26: Elements/attributes of AcquirerStatusReq}

8.3 Status Response (AcquirerStatusRes)

The reply to the AcquirerStatusReq is the AcquirerStatusRes. This message and the SAML Response inside the container are created by the Validation Service and sent to the Merchant via the Routing Service. The AcquirerStatusRes contains the elements and attributes as listed in Table 27. This message communicates the status of the transaction (related to the Transaction.TransactionID which was sent in the AcquirerStatusReq) to the Merchant. If the status equals “Success”, the container element is included in the response. Inside the container element is the SAML 2.0 message containing the consumer data elements. The elements and attributes in the optional container are shown in Table 28.

^{Table 27: Elements/attributes of AcquirerStatusRes}

As explained, the SAML 2.0 Response message is embedded in the container element. The Response message is a standardised message, and therefore it contains elements that are not used in iDIN. However, because it is up the Validation Service to omit these values it is not indicated in Table 28. The elements and attributes inside the container are shown in Table 28.

^{Table 28: Elements/attributes inside the container of AcquirerStatusRes}

8.4 Errors during execution of Status Protocol

When using the Status Protocol to request an iDIN transaction status, errors can occur which can lead to the Merchant not obtaining the status of the transaction at that moment. It is therefore not possible to show the Consumer the final status of the transaction at that moment. Recommended messages to show to Consumers are defined further on in this document.

8.5 Restrictions on AcquirerStatusReq

A Merchant may only initiate an AcquirerStatusReq in the following case:

• It is triggered by a Redirect to Merchant (E) as part of the Transaction protocol.

The SAML Assertion issued by the Validation Service is only valid for 30 seconds. From the moment the Consumer has been successfully redirected to the Merchant up to the time the Assertion is expired, the Merchant can make status requests. However, the Merchant should only perform more than one status request if it has received a timeout from the Routing Service. The Merchant is not allowed to perform any more status requests once it received notification from the Validation Service that the Assertion is expired, see Chapter 12 for the details.

Merchants will be perceived as committing undesirable actions if they use the Status Request more than the above described limitation, as doing so places unnecessarily heavy demands on the Acquirer’s and Issuer’s system.

8.6 Performance and time-out of status messages

The performance of the Issuer/Validation Service and Routing Service systems has a direct influence on the Consumer’s user experience. Therefore iDIN sets a target time and time-out for the status response message. For a Merchant the relevant target time and time-out concern the communication with its iDIN Routing Service is:

^{Table 29: Performance requirements (for the 95th percentile[8])}

The target time is the time (in seconds) in which the Merchant should receive a AcquirerStatusRes after sending a AcquirerStatusReq. The time-out is the length of time after which the Merchant should no longer expect a response (most likely an error has occurred) and should act accordingly (for example by displaying an appropriate error message to the Consumer).

9 Error handling

9.1 General

If an error occurs while processing a DirectoryReq, AcquirerTrxReq or AcquirerStatusReq, for example because a request contains an invalid value, an AcquirerErrorRes will be returned instead of the regular response. Also, for certain special cases an error is returned to the Merchant e.g. when the Assertion is expired. This is discussed in more detail in Appendix A.

The AcquirerErrorRes has the same main structure as indicated in Table 30 for all three types of requests. The container is only present when receiving an error after an AcquirerStatusReq. Appendix B shows an example of an AcquirerErrorRes.

9.2 Error Response (AcquirerErrorRes)

Instead of the regular response (DirectoryRes, AcquirerTrxRes or AcquirerStatusRes) the Routing Service will return an AcquirerErrorRes if an error occurs during the reception or processing of the request, or if the request contains values that are not allowed or do not comply with the required format. Table 30 lists the fields that appear in the AcquirerErrorRes and Table 31 lists the elements and attributes that appear inside the container.

^{Table 30: Elements/attributes of the AcquirerErrorRes}

^{Table 31: Elements/attributes inside the container of AcquirerErrorRes}

9.3 Non-availability

It might be possible that one of the Issuers is temporarily unavailable. In this case, transactions that have to be processed by this Issuer will generate an AcquirerErrorRes. When the Routing Service has determined unavailability of an Issuer it will communicate this to the Issuer immediately. This means that Merchant will never have to contact the Issuer directly.

It might also be possible that the Routing Service itself is temporarily unavailable. In this case, unless the Merchant has more than one Routing Service, no iDIN transactions can be processed and the Routing Service will generate an AcquirerErrorRes or time-out.

Lastly, the Merchant return-webpage might not be working properly.

For all three cases we recommend displaying a clear error message to the Consumer.

10 Security and certificates 

10.1 General principles of certificates

For asymmetric encryption two keys are used: one public key and one private key. The public key is linked to the certificate and can be shared with anyone. The owner of the certificate must keep the private key confidential at all times. The specific characteristics of the private and public part of the certificates will allow the encryption of a message with the public part while the result can be decrypted with the private part, and vice versa. The certificates should have RSA keys of 2048 bit long. It is not possible to decrypt a text with the same key that was used to encrypt it.

These specific characteristics enable two applications of a certificate:

• Encryption of a message. By encrypting a message with the public key of the receiving party the information can only be read by the recipient (who has sole knowledge of the private key);

• Creating an electronic signature of a message. By encrypting the (hash) message with the private key, the recipient can determine the authenticity of the (sender of the) message by verifying the signature with the public part of the certificate. The recipient will also verify the integrity of the message to make sure the contents of the message was not changed by a third party.

The TLS connection that is used within iDIN between the Merchant and the Routing Service is based on the first application. The TLS connection uses at least 128-bit encryption based on a server side certificate of the Routing Service.

Merchant MUST use a minimum TLS version of 1.2. Earlier versions have become out-dated.

Since iDIN does not put any constraints on the communication between the Consumer and the Merchant, this can be either with or without a TLS connection. Merchants are however strongly advised to always use TLS on the transaction pages of their website. The iDIN standard also uses electronic signatures to ensure the authenticity, integrity and non- repudiation of all messages with the exception of redirects. The electronic signature of the Routing Service in the AcquirerStatusRes message, for example, enables the Merchant to verify the authenticity of the transaction confirmation.

10.2 Signing iDIN messages

All messages that are sent by the Merchant to the Routing Service (DirectoryReq, AcquirerTrxReq and AcquirerStatusReq) have to be signed by the Merchant. Messages are signed in accordance with the "XML Signature Syntax and Processing”, with the following settings and restrictions applied:

• The entire XML message[10] must be signed;

• For the purpose of generating the digest, the exclusive[11] canonicalization algorithm must be used;

• For the purpose of generating the signature value, the exclusive[12] canonicalization algorithm must be used;

• The syntax for an enveloped[13] signature must be used. The signature itself must be removed from the XML message using the default transformation prescribed for this purpose;

• For hashing purposes the SHA-256[14] algorithm must be used;

• For signature purposes the RSAWithSHA256[15] algorithm must be used. RSA keys must be 2,048 bits long;

• The public key must be referenced using a fingerprint of an X.509 certificate. The fingerprint must be calculated according to the following formula HEX(SHA-1(DER certificate)) [16].

In general Merchants don’t need to have extensive knowledge of RSA since most programming languages have libraries with functionalities that implements XML Digital Signature processing. It is strongly recommended to use these standard libraries.

Standard functionality for creation and verification of RSAWithSHA256 digital signatures is available in commonly used software platforms, from the following versions and higher:

• PHP 5.5;

• Microsoft .NET 4,5;

• Java SE 7.

This functionality may also be available in earlier versions of these platforms and in other platforms (e.g. Python, Ruby).

To further support Merchants, software libraries have been developed for iDIN in .NET, PHP and Java. Please contact your bank about this for more information.

For information about creating the public and private key pair please refer to paragraph 13.5.

10.2.1 Signing of the SAML 2.0 Assertion

Next to the regular signing of the entire XML message in the iDx protocol, the Validation Service signs the SAML Assertion separately. This Assertion is passed along the Merchant via the Routing Service in the AcquirerStatusRes (only for the Transaction.status ‘Success’). This signing in the SAML Assertion follows the same requirements that apply to signing as discussed before except for the following:

• Instead of referring to the certificate of the Issuer to be used for verifying the signature by fingerprint, the entire certificate is included. The KeyName element is replaced by an X509Data element containing an X509Certificate element containing the entire X509 certificate of the Validation Service, See Table 33. The X509SubjectName element may be included inside the X509Data element. Other elements in KeyInfo shall not be used. This is done to guarantee availability of the certificate of the Validation Service for the Merchant in an easy manner, without synchronization with a scheme directory for example;

• The attribute Reference@URI must contain the value of the of @ID attribute of Assertion to make the reference to the object being signed;

• Merchants shall only trust and process SAML Assertions signed with a valid Validation Service certificate issued under the trusted root for iDIN Issuers.

10.3 SAML EncryptedID and EncryptedAttribute

For privacy reasons the Routing Service is prevented to see the consumer attributes in readable form. Hence, all consumer data inside the SAML 2.0 assertion are encrypted. Note that the Merchant is allowed to use a different certificate to sign the messages than it uses to decrypt the attributes. For the encryption of both the EncryptedID element and the EncryptedAttribute elements within the SAML Assertion the following requirements apply:

• Encryption of the attributes will be based on a 256 bit AES key;

  • Encryption of the attributes will be performed using the http://www.w3.org/2001/04/xmlenc#aes256-cbc algorithm;

  • Standard XML padding is used[18];

• A Validation Service generates a new AES key for each EncryptedAttribute and EncryptedID elements;

• The AES keys are encrypted with the public key of the Merchant, which the Validation Service received from the Routing Service. Encryption of the AES keys is done with RSA in combination with OAEP: http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p;

• XML contents in the encrypted element have all relevant namespace definitions;

• xsi:type definitions MAY be included in the AttributeValue element e.g. <saml:AttributeValue xsi:type=”xs:int>.

The NameID element containing either the Consumer.BIN or Consumer.TransientID is entirely encrypted (for the corresponding namespaces see Table 7). The following element containing the Consumer.BIN is encrypted:

Encrypting the NameID element yields an EncryptedID in the following fashion. The placeholders (between % signs) indicate where the encrypted AES key and where the encrypted NameID can be found. The EncryptedKey element is embedded inside the EncryptedData element.

In a similar fashion the consumer attributes in the SAML Assertion are encrypted. An example below shows how the consumer.dateofbirth is encrypted. Depending on the request of the Merchant, zero or more EncryptedAttributes are returned in the SAML Assertion.

The entire attribute is encrypted which yields the following:

10.4 Authentication of iDIN messages

To ensure the status of a transaction, the Merchant has to verify the signature of the Routing Service in all Response messages. Furthermore it has to verify the signature of the Validation Service on the Assertion. To verify the signature in the SignatureValue field, it is recommended that Merchants use standard XML Digital Signature libraries, which are available in most (web) programming languages.

10.5 Creating a key pair

If you want to use a so-called “self signed certificate” this paragraph will explain how to do so. It is also possible to purchase a certificate at a company specialized in this field (Certificate Authority), see paragraph 0.

In order to create a public and a private key execute the following steps:

1. Download the “OpenSSL Library” from http://www.openssl.org. You can find more information on the “certificate generating utility” at: http://www.openssl.org/docs/apps/req.html. You may also generate the key pair using other software. If so please use the manual that comes with your software.

2. Generate an “RSA private key” using the following command
   (choose your own password for the field [privateKeyPass]): 
   openssl genrsa –aes128 –out priv.pem –passout pass:[privateKeyPass] 2048

3. Create a certificate based on the “RSA private key”
   (use the same password as in the previous step for the field [privateKeyPass]): 
   openssl req –x509 –sha256 –new –key priv.pem –passin pass:[privateKeyPass]
-days 1825 –out cert.cer

4. The previous OpenSSL command will generate a certificate in X.509 format, with a validity period of 5 years (1825 days), the maximum for iDIN signing certificates.

5. The file priv.pem contains the private key. The file cert.cer contains the certificate with the public key. The Merchant has to keep the priv.pem file private, which is used in the RSA encryption. The cert.cer file has to be communicated to the Routing Service. The method of communication will depend on the Routing Service.

10.5.1 Buying a certificate from a Certificate Authority

When buying a certificate from a Certificate Authority (CA), rather than generating the certificate yourself, it is important to note the following: the CA signing certificate (and the rest of the certificate chain) must use hashing algorithms and key lengths that are at least as secure or better than those of the Merchant certificate. Therefore CA-certificates used to sign certificates for electronic signatures must use at least SHA-256 for hashing and 2,048 bits for RSA keys.

Signing certificates should also have a maximum validity period of 5 years.

10.6 Signature data elements

All messages, including the error messages, with the exception of redirects, are signed using an electronic signature. The electronic signature guarantees the authenticity of the sender, non-repudiation and the integrity of the message. The digital signature is an XML Signature data element that is defined in the XML-Signature Syntax and Processing W3C Recommendation 12 February 2002. See Table 8 for the Schema location. All attributes and elements of the Signature element are listed in the Table 32. The elements and attributes relevant for creating the signature in all iDx messages and SAML Signature are described below; other elements should not be used.

^{Table 32: Elements/attributes of the Signature}

The signing of the SAML 2.0 Assertion is different that instead of the fingerprint of the X.509 certificate the entire certificate of the Issuer is added. Also the @URI attribute of the Reference element should reference to the @ID attribute of the Assertion. This yields to the following change with respect to the Signature, while all other elements and attributes are the same as in Table 32:

^{Table 34: Signature changes with respect to signing the SAML Assertion}

11 Presentation of iDIN 

11.1 General

There are some requirements regarding the presentation of iDIN on the Merchant’s website. The main purpose of these requirements is to create a uniform user experience for Consumers whenever they use iDIN, regardless of which Merchant’s website they use. The requirements are further explained in the following paragraphs.

The Merchant bears primary responsibility for initiating the iDIN process and for the communication to the Consumer regarding the status of this process. Merchants who offer iDIN to their customers must include iDIN in their lists of authentication methods (if any). iDIN must be presented in the list of methods in such a way that it receives at least the same amount of attention as all other competitors.

In addition, an iDIN transaction (of any kind) must always be recognisable as such to the Consumer. This means that a Merchant must make sure in the design of their implementation of iDIN that iDIN and the start of an iDIN process are recognisable as such. The Merchant must also distinguish clearly between the processes (authentication, gather attributes or age verification) of different iDIN services. If a Merchant offers iDIN to Consumers to sign, the Merchant must indicate this clearly to the Consumer.

11.2 Transaction flow

When the Consumer chooses to use iDIN, the Consumer should immediately be presented with the Issuer selection list without any intermediate screens being displayed by the Merchant (e.g. Consumer login and/or registration screens). And when the Consumer has selected the required Issuer, he or she should be immediately redirected to the online bank environment of the selected Issuer (based on the issuerAuthenticationURL the Merchant has received in the AcquirerTrxRes).

11.3 Redirect to Issuer

The Merchant needs to perform the redirect to the Issuer, from the browser window where the Consumer selected the Issuer. The complete page of the Merchant will be replaced by the complete page of the selected bank. Therefore it is not allowed to open the redirect to the Issuer in a new browser window. However, it is allowed to open a new window, with visible address bar, before the Consumer selects his bank from the Issuer list.

11.4 Frames

Frames used on the Merchant’s site are allowed. The page of the Issuer will remove these frames using a frame busting technique. This will allow the Consumer to verify whether the transaction is really taking place at the bank chosen from the Issuer list. After the redirect to the Merchant, the Merchant must completely rebuild the Merchant page to show the Merchant’s confirmation of reception of the iDIN Authentication/attributes.

11.5 New Window

The iDIN authentication may take place in a new browser window, as long as the Merchant makes this window appear at (or before) the moment the Consumer chooses the authentication method. A new window is only allowed if initiated by the Consumer (no pop-ups are allowed). The complete transaction flow must take place in this window, including the Merchant’s confirmation of receiving the iDIN authentication/attributes. The new window must also contain an address bar that allows the Consumer to check the Internet address URL and SSL-certificate of the Issuer. During the transaction flow it should not be possible for the Consumer to initiate another transaction through the Merchant’s original browser window.

11.6 Issuer list

The Issuer list has to be presented as described in Section 9.4.

11.7 Banners and logo's

This information shall be made available on idin.nl.

11.8 Requirements and recommendation for Merchant screens

This section describes requirements and recommendations for iDIN related texts on the Merchant website. Note that some information is only available in Dutch.

11.8.1 Display last login

If a Consumer logs into the website of the Merchant using iDIN, the Merchant is strongly recommended to show the date and time of the previous login (in general, so not specifically the last iDIN login), e.g. ‘Welcome, the last time you were logged in was on October 5 2015 at 15:41’. The Merchant may determine the exact text. This makes it possible for the Consumer to verify if this matches the moment of his/her last visit.

11.8.2 Explaining iDIN to Consumers

Merchants can use the following texts to explain iDIN to their users. These texts are only available in Dutch.

Explanation of iDIN to the Consumer

• Short version: Makkelijk en veilig online identificeren met uw bank.
  Long version (preferred): Met iDIN kunt u zich online identificeren bij een bedrijf of instelling. Gemakkelijk, vertrouwd en veilig met de inlogmethode van uw bank.

Explanation of the advantages of iDIN

1. Makkelijk en veilig online identificeren.

2. Met de vertrouwde inlogmethode van uw bank.

3. Eén manier van inloggen bij bedrijven en instellingen.

4. Geen aparte gebruikersnamen en wachtwoorden meer onthouden.

5. Zelf invullen van persoonlijke gegevens is niet meer nodig.

11.8.3 Recommended texts on Merchant website per RequestedServiceID

iDIN provides different types of services, which have been divided into the following three product types:

1. Gegevens verstrekken: The Consumer chooses iDIN to provide attributes and/or an ID to the Merchant, with or without the creation of a user account. The Merchant requests this service, either with or without the BIN. This also includes for example the provisioning of the date of birth or name/address attributes with/without BIN;

2. Inloggen: The Consumer uses iDIN to login. No attributes are provided to the Merchant, just the BIN;

3. Leeftijd bevestigen: Verification that the age is above 18 year (the attribute 18orOlder is requested, with or without the BIN). This can also be used for verification of the age below 18 years.

4. Ondertekenen: The Consumer chooses iDIN to sign documents using Issuer issued credentials. 

Table 34 shows the recommended texts for the Merchant website. The referral page is the webpage where the Consumer chooses to use iDIN. The returnpage is the webpage to which the Consumer returns, after he has approved the iDIN transaction at his own bank.

^{Table 34: Recommendation Merchant texts per product type}

11.9 Validation Service front-end

The following described process is outside the scope of the Merchant implementation. It is provided in this document to give insight in the Consumer’s experience of iDIN.

The Issuer (Validation Service) bears primary responsibility for handling the iDIN process and for communicating with the Consumer regarding the status of the process of the iDIN transaction. The page sequence and layout (from redirect from Merchant to Issuer until redirect back to Merchant) are determined by the Validation Service. The following conditions must be met:

• After selecting his Issuer at the Merchant website, the Consumer is redirected to the selected Issuer’s Validation Service website. In the active browser window, the complete page of the Merchant is replaced by the complete page of the selected Validation Service. Alternatively the Validation Service can choose, based on the header information received from the Consumer, to automatically redirect the Consumer to its mobile payment website or mobile payment app. Criteria for choosing which Consumers/devices are redirected to which channels are left to the Validation Service;

• Optionally, the Validation Service may allow the Consumer to choose a different channel from the one chosen automatically, if the Validation Service offers multiple channels available to the Consumer. If this option is offered and used by the Consumer a second redirect takes place to the authentication website or application of choice;

• At all times during an iDIN process, it must be clear to the Consumer that he is about to start an iDIN transaction. Therefore, the Validation Service must display the iDIN logo on every Validation Service web/mobile application page shown in the iDIN process;

• The Validation Service will not display any information unrelated and irrelevant to the iDIN transaction, that could distract the Consumer from completing the process on the website or in the mobile application. Information that is considered relevant is:

  • A help function offered by the Validation Service, providing the Consumer with an explanation or additional information regarding the iDIN service(s);

  • If the Issuer has a mobile application available then this may be offered for immediate download and activation during the iDIN process to Consumers that have been detected as using a mobile device but who have not yet downloaded the app. Note: downloading an application during the iDIN process may very well result in the process expiring if it exceeds the expiration period set by the Merchant;

• The Validation Service facilitates all services of iDIN. The Validation Service must clearly indicate to the Consumer what iDIN service the Consumer is about to consent to;

• The Validation Service will guarantee that the integrity and layout of the Validation Service website/mobile application is not altered when displaying the contents of textual fields (e.g. due to possible malicious content of the transaction information provided by a malicious Merchant);

• All iDIN transaction related information (i.e. Transaction information, Consumer information and Merchant information, must be presented to the Consumer for approval;

• During the iDIN transaction process, the Consumer can either consent to the provision of all attributes (so not per attribute set or individual attribute) or reject the entire request, with the exception of the telephone and email attributes which may be deselected by the Consumer, see Section 0;

• During the iDIN transaction process, the Consumer is not allowed to change any of the information in the transaction details nor is he/she allowed to give partial consent, with the exception of the telephone and email attributes which may be deselected by the Consumer, see Section 0;

• The Validation Service indicates clearly how the Consumer can approve and give his/her consent for the iDIN transaction;

• The Consumer must be able to see all attributes and their values in order to give informed consent for providing the attributes to the Merchant. In order to retrieve this information, the Consumer must first be logged into Validation Service system. This enables the Validation Service to identify the Consumer and retrieve the right information;

• The Validation Service indicates clearly how the Consumer can cancel the iDIN process;

• As an option, the Validation Service iDIN application may show a message to the Consumer when he/she tries to cancel the iDIN transaction by using the browser close button or tries to navigate backwards or forwards by using the browser arrow buttons. The message may be shown because this can be considered undesired Consumer behaviour. In this message, the Consumer can be advised to cancel or complete the iDIN transaction in a proper way, using the cancel or confirmation facilities of the Validation Service iDIN application;

• In case the Validation Service cannot suffice to the minimal requested attribute set, it may state to the Consumer what attributes are missing that are required to successfully complete the transaction and shorty explains which procedure must be followed to add in the missing information. The Validation Service is free, in choice and implementation, to provide instructions on how the Consumer can change his/her attributes;

• After approval of the iDIN transaction, the Consumer must have the opportunity to instantaneously return to the Merchant where the iDIN transaction was initiated. This is achieved by incorporating a ‘Continue’ button. Clicking on this button takes the Consumer to the Merchant’s return URL provided during transaction initiation by the Merchant.

11.9.1 Approval information

iDIN offers different services that can be requested by the Merchant with the RequestedServiceID. Each service is coupled to one of three product types. Depending on the requested service, the Issuer presents a different text to the Consumer. Table 35 shows these texts, with the following remarks:

• Texts and elements that are always shown are indicated in bold. For illustrative purposes an example is given, however the exact formulation of the sentences can be different for each Issuer;

• ‘Voor/Inzake TradeName’ is only shown when the trade name is present;

• The mandatory texts and elements are shown before and/or after the Consumer has logged into the Issuer domain;

• The Validation Service shows all Consumer attributes (for product type 1 and 3) that are requested by the Merchant. Subsequently, the Consumer can approve that the Issuer provides these attributes to the Merchant. The TransientID, Consumer.BIN and Consumer.DeprecatedBIN shall not be presented to the Consumer. All other Consumer attributes are always shown.

^{Table 35: Mandatory texts on the Issuer screens per product type}

The following screenshot provides an example of the iDIN approval website or mobile application screen for authentication service plus providing attributes.

12 Appendix A: Error codes and cases 

In case something goes wrong on iDx level an AcquirerErrorRes with the appropriate errorCode is returned to the Merchant. If there is an error within the SAML messages an iDx errorCode AP3000 is return and a container is present with an SAML (error) Response, as outlined in Section 12.2.

12.1 iDx error codes

The Error.errorCode is composed of:

• A category (two letters)

• A number (four digits)

The following categories are distinguished:

^{Table 36: Error code categories}

The following iDx error codes exist:

^{Table 37: Error codes}

The field errorDetail in the table above contains one of the values shown in the table below.  The italic printed words will be replaced by actual values, as indicated.

^{Table 38: errorDetail}

12.2 SAML error codes

To communicate to the Merchant that an error has occurred in the SAML message, the SAML Status element is used which has the following structure:

AML defines two level of status codes. The first level status code can have the values as shown in the Table below.

^{Table 39: First level SAML status codes}

The second level status code is present for the cases as discussed in Section 12.2. There are several standard values for the SAML second level status code, and some defined values that are only used within the iDIN domain. The possible values for the second level status code within iDIN are listed in the Table below.

^{Table 40: Second level SAML status codes}

12.3   SAML error cases

There are two cases where a SAML Response is returned with a first level status code not equal to “urn:oasis:names:tc:SAML:2.0:Success” but equal to “urn:oasis:names:tc:SAML:2.0:Requester”.

1. There is some type of error in the AuthnRequest between the Merchant and the Routing Service. This AuthnRequest is embedded inside the container of the AcquirerTrxReq (B):
   For this case on iDx level an AcquirerErrorRes (B’(X)) is returned to the Merchant with a SAML Response in the container. The iDx errorCode equals AP3000 with an errorMessage ‘Product specific error’. The second level status code depends on the type of error that has occurred, see above table.

2. The Merchant has requested the Status, however the Assertion is expired. This can occur when the Consumer has successfully authenticated and approved the transaction, however the Merchant has not succeeded in requesting the status within 30 seconds from the moment the Consumer has returned to the website of the Merchant.
   For this case a normal AcquirerStatusRes is returned to the Merchant. The iDx Transaction.status of this message equals “Success”. However the SAML Response does not contain an Assertion, but has the structure as discussed in Table 28: Elements/attributes inside the container of AcquirerErrorRes. It has a second level status code value of “urn:oasis:names:tc:SAML:2.0:status:RequestDenied”.

12.4 Issuer cannot provide all attributes conform minimal set or deselection of telephone or email

When the Issuer cannot deliver all requested attributes conform the minimal set (or the telephone and or email address are deselected by the Consumer), the following shall be done:

• A normal SAML Response is returned. The first level status code is “urn:oasis:names:tc:SAML:2.0:Success”;

• If the Consumer de-selects his/her telephone number and/or email address, then these are not returned to the Merchant;

• The Issuer returns all other attributes that are available in the requested categories;

• Instead of the second SAML status code “urn:nl:bvn:bankid:1.0:status:Success” the second SAML status code “urn:nl:bvn:bankid:1.0:status:IncompleteAttributeSet” is used;

• The DeliveredServiceID shall indicate which attribute categories are delivered conform the minimal set as defined in Section 5. If the Issuer cannot determine the DeliveredServiceID it must use the value ‘0’.

Example:

• The Merchant has requested the date of birth and all address attributes of a Consumer with RequestedServiceID 1472;

• When the Issuer processes the request, its systems detects the address attributes cannot be delivered conform the minimal set as defined in Section 5 (it has the consumer.postalcode, consumer.city, consumer.streetname but is missing the consumer.houseno. Therefore, it cannot match any of the five possible options as defined in Section 8.5.

• The Issuer calculates the DeliveredServiceID that corresponds to the requested attributes categories it can deliver conform the minimal set (in this case 448 which indicates the date of birth is delivered conform the minimal set);

• The Issuer returns all requested attributes (date of birth and all attributes in the incomplete address category), and uses the second SAML status code “urn:nl:bvn:bankid:1.0:status:IncompleteAttributeSet” and the DeliveredServiceID equal to 448.

12.5 Consumer message

The Error.consumerMessage can contain one of four different standardised texts that are sent to the Merchant by the Routing Service, see Table 41. The Merchant must show the Error.consumerMessage to the Consumer on his website. The value of Error.consumerMessage is specified in the AcquirerErrorRes by the Acquirer.

13   Appendix B: Message examples

Most of the example messages given here only use the default method of namespace declaration. At the end of the appendix one example is given of a message with namespace prefixes (this message does not contain an information container, it is merely meant to signify the use of namespace prefixes). NB:

• Signatures are examples and don’t validate against the messages;

• The examples are not necessarily related to each other.

13.1 DirectoryReq (A)

13.2 DirectoryRes (A’)

13.3 AcquirerTrxReq (B)

13.4 AcquirerTrxRes (B’)

13.5 AcquirerStatusReq (F)

13.6 AcquirerStatusRes (F’) Unencrypted

13.7 AcquirerStatusRes (F’) Encrypted

3.8 AcquirerErrorRes (B’(X))

14 Appendix C: iDx Merchant-Acquirer Schema

[1] Some of these terms map as follows to Identity Access Management terms: Consumer - Subject, Merchant - Relying Party/Service Provider, Acquirer / Routing Service - Broker and Issuer / Validation Service - Identity Provider.

[2] For due diligence reasons, the DISP may be subject to extra audits

[3] Because the BIN is in another place in the SAML message, namely the subject, it is not considered an attribute in this context.

[4] If the disputes are more common than expected, the process can be automated in the future.

[5] This represent the group as defined in Table 12. Some attributes are not part of any group but can be requested and provided individually depending on the Requested- or DeliveredServiceID

[6] Characters = any UTF-8 character. Numbers = 0-9. Letters = a-Z. Capital letters = A-Z. Letter-based characters like ligatures or digraphs (e.g. á, ç, Æ) are allowed.

[7] 95^th percentile is a statistical term indicating that 95% of transactions in a tested sample should be within the set target time.

[8] 95^th percentile is a statistical term indicating that 95% of transactions in a tested sample should be within the set target time.

[9] http://www.w3.org/TR/xmldsig-core/

[10] XML Signature reference to the signed info URI is left blank, see example messages in APPENDIX B

[11] https://www.w3.org/TR/xml-exc-c14n/

[12] https://www.w3.org/TR/xml-exc-c14n/

[13] http://www.w3.org/TR/xmldsig-core/#sec-EnvelopedSignature

[14] https://www.w3.org/TR/xmlenc-core/#sec-SHA256

[15] https://www.w3.org/TR/xmlenc-core/#sec-SHA256

[16] DER (Distinguished Encoding Rules), SHA-1 (Secure Hash Algorithm – 1), HEX (Hexidecimal)

[17] http://tools.ietf.org/html/rfc2045#section-6.8

[18] http://www.w3.org/TR/xmlenc-core/#sec-Alg-Block