link

# iDIN

# About iDIN

iDIN is a Dutch eID scheme controlled by the Dutch Payment Association (opens new window) (in Dutch: BVN, Betaalvereniging). It is a collaboration between all major Dutch banks to facilite electronic identity services which uses familiar secure authentication processes of the online banking environments. Everyone that has a personal bank account at one of the issuing banks can use iDIN, without the need of any additional registration.

iDIN enables natural persons who have been checked against the requirements of the Money Laundering and Terrorist Financing (Prevention) Act (Wwft) to provide one or several attributes directly from the bank records to Signicat merchants, through a secure channel specifically designed for this purpose. Merchants can use iDIN to onboard new users and authenticate recurring users without the need for new passwords. iDIN can also be used to sign legally binding documents.

Additionally, iDIN can be used in combination with Surepay lookups to enhance the user onboarding process. For more information about iDIN in combination with Surepay, please refer to SurePay API (opens new window)

# Demo

If you would like to see how iDIN works, you can either use the Signicat's demo service to simulate an iDIN transaction in our test environment or use the official iDIN demo website (opens new window). The official iDIN demo site faciliates transactions on a live environment and can be used to understand the flow from an end-user perspective.

# Method types

The iDIN scheme supports different method types, designed for different purposes. The available methods are listed below:

  • Identification: used to identify / onboard users
  • Login: used to authenticate recurring users
  • Age check: used to validate if the user passed the age of 18

# Available attributes

The attributes listed below can be obtained from an iDIN identification flow. When using the iDIN login flow, only the BIN is returned in the response. This BIN can be used to map the authentication to a previously performed initial identification, which also contains the BIN.

  • Consumer ID (“BIN”) – Bank Identification Number, unique for each Merchant
  • Initials of first name
  • Last name
  • Address
  • Date of birth
  • Gender
  • Email
  • Telephone
  • Age confirmation (18 years old: yes/no) – only available through the age check transaction

Because it often occurs that contact details like email / phone number are changed by the user, the iDIN scheme allows the user to either update these attributes during the transaction or to opt-out and not share those attributes.

The identity information is issued by a bank and is not linked to (or checked with) the central identity register (BRP – Basisregistratie Personen) in the Netherlands. The Dutch social number (BSN) cannot be obtained via iDIN. The governmental scheme DigiD can do this.

Important

The iDIN scheme and the issuers do not guarantee that they will be able to provide all the requested attributes.

# End-user experience

iDIN can be used to securely identify users electronically with validated attributes. Merchants can implement iDIN in their own client application and provide users the possibility to identify and/or authenticate through their own trusted bank environment.

Users typically go to a similar flow as illustrated below.

  • The user visits the merchant's website and proceeds to onboard / authenticate through iDIN.
  • The merchant redirects the user to the Signicat platform and Signicat starts an iDIN transaction for that specific user.
  • The user will be redirected to corresponding issuing bank and performs an authentication in the bank environment. After giving consent to share the attributes, the user will be redirected back again to the merchant's website.
  • Signicat then retrieves a confirmation of a successful authentication and returns the attributes to the merchant.

# Technical integration

Run in Postman (opens new window)

This section provides technical details how merchants can use each of the three iDIN methods on the Signicat platform. Signicat offers an OIDC identity hub, which requires merchants to start transactions through an authentication URL. For further information about the authentication URL, see the Authentication API.

# Using iDIN through OIDC

In the authentication URL, it's mandatory to provide a method name in the acr_values to trigger the required iDIN method. The method names for each of the three iDIN methods are listed below.

Value Description
idin-ident iDIN identification method
idin-login iDIN authentication method
idin-age iDIN age verification method

In order to fetch the attributes, you can use the following OIDC scope: signicat.idin, this make sure the corresponding iDIN attributes are part of the response.

An example of an authorisation URL for the idin-ident method is listed below.

https://eu01.preprod.signicat.com/oidc/authorize?response_type=code&scope=openid+signicat.idin&redirect_uri=https://labs.signicat.com/redirect&acr_values=urn:signicat:oidc:method:idin-ident&state=123&client_id=demo-preprod-basic

# Using the iDIN Directory Service

By default Signicat will display a banking selection screen. This banking selection screen displays the full list of participating issuing banks. The user can select the corresponding issuing bank and Signicat will then redirect the user to the chosen issuing bank. This banking selection screen can be customised with a graphical profile, for more information see graphical adjustments and customisation

However, through Signicat it's also possible to skip the banking selection screen and redirect the user directly from your own client application to the corresponding issuing bank. This requires implementing the iDIN Directory Service API.

The iDIN Directory Service returns the list of all participating issuing banks in the iDIN scheme. Each of the issuing banks returns a unique issuerID which can be appended on the authorisation URL. In order to append the issuerID on authorisation URL, the login_hints parameter needs to be filled with the issuerID.

An example of such an authorisation URL is defined below.

https://eu01.preprod.signicat.com/oidc/authorize?response_type=code&scope=openid+signicat.idin&redirect_uri=https://labs.signicat.com/redirect&acr_values=urn:signicat:oidc:method:idin-ident&state=123&login_hint=issuer-RABONL2U&client_id=demo-preprod-basic

A good example of such an implementation is the official iDIN demo site (opens new window), where a dropdown menu is integrated in the frontend.

# Using iDIN in the Sign API

iDIN can also be used as a signing method in the Sign API. The Sign API requires a different integration than OIDC. For more information about the electronic signature service and the required technical integration, see Sign API.

In the Sign API, it's possible to define the required signing method. In case iDIN needs to be used as a signing method, the following object can be used on task level in the Sign API.

"signatureMethods": {
    "handwritten": false,
    "name": "idin-ident",
    "type": "AUTHENTICATION_BASED"
}

# iDIN QR

The iDIN scheme provides a QR code scanning service, called iDIN QR. The purpose of this service is to increase the conversion rate by using a superior mobile experience. iDIN QR in itself does not provide any additional attributes compared to the regular iDIN methods, it's only intended to improve the UX for the existing methods.

In certain cases, issuing banks require users to authenticate through hardware tokens in web flows. On full mobile flows, this is not the case when the user has the mobile banking application installed. iDIN QR is aimed to make use of these mobile flows, by redirecting the user away from the desktop to a mobile device by scanning a QR-code. In this case the user can simply finalise the iDIN transaction with the regular mobile authentication method (Face ID / Touch ID, passcode, etc).

If you incorporate the iDIN QR code in the desktop web flow, end-users can scan their QR code with their mobile device and finalise the iDIN transaction itself on their mobile banking application, before being redirected back to a landing page on the desktop web flow. Users can scan QR codes either in two ways:

  1. Via a generic QR code scanning application. This leads to a banking selection page where the user can select the bank.
  2. Directly from the mobile banking application itself. This only applies if the issuing bank supports scanning iDIN QR codes.

During an iDIN QR transaction, the user can see the status page on the mobile device. This mobile page can have the following statuses:

  • Cancelled: During the process, the user tapped the Cancel button.
  • Failed: The iDIN transaction failed and the user may try again.
  • Success: The iDIN transaction was successful and the user gets redirected to the specified URL.

# iDIN QR integration details

iDIN QR is available at Signicat through the same OIDC flow as regular iDIN transactions. All the existing iDIN methods are supported through iDIN QR. Similar to the regular iDIN flows, you need to specify the required iDIN method in the acr_values. The following method names can be used in the acr_values for iDIN QR.

# Using iDIN QR through OIDC

Similar as to regular iDIN transactions, also for iDIN QR it's mandatory to provide a method name in the acr_values to trigger the required iDIN method. The method names for each of the three iDIN methods are listed below.

Value Description
idin-ident-qr iDIN QR flow of the identification method
idin-login-qr iDIN QR flow of the authentication method
idin-age-qr iDIN QR flow of the age verification

An example of an authorisation URL for the idin-ident-qr method is listed below.

https://eu01.preprod.signicat.com/oidc/authorize?response_type=code&scope=openid+signicat.idin&redirect_uri=https://labs.signicat.com/redirect&acr_values=urn:signicat:oidc:method:idin-ident-qr&state=123&client_id=demo-preprod-basic

Other login_hints, such as the iDIN Directory Service cannot be used in combination with iDIN QR.

# iDIN QR Parameters

In addition to regular iDIN transactions, iDIN QR provides some additional parameters that can be applied for specific configurations. In order to apply such a specific configuration, please contact support@signicat.com.

  • Expiry time of the QR code: The QR code is valid until the expiry time. The default value is 15 minutes. The default value can be adjusted to a value between 10-20 minutes.

  • Service URL: After the users are identified, they are redirected to the Service URL. You may customise this URL to your own landing page or another page of your choice.

  • Size of QR code: The size of the QR code is shown in pixels. The default value is 300, which can be adjusted to a value between 200 and 2000 pixels.

  • Language texts: You may adjust the language text that is displayed on both the web and the mobile screen. Note that the chosen language will be applied to all iDIN methods on your service.

# Sandbox environment

Signicat offers an open and free access pre-production test environment, eu01.preprod.signicat.com. All iDIN methods can be used in the test environment and this also accounts for the iDIN Directory Service and the Sign API. This test environment can be used to start integrating with iDIN.

# Connecting to the sandbox environment

In order to integrate with the open test environment, you can use the following endpoint and credentials.

Value Description
https://eu01.preprod.signicat.com Endpoint of the test environment
demo-preprod-basic Client ID of the test environment
KmcxXfuttfBGnn86DlW8Tg3_dYu6khWafkn5uVo7fGg Client Secret of the test environment

Please note that this is an open and test environment. Therefore it's not possible to apply any custom configurations on this service. However, in case you already have your own client credentials and service, you can re-use that connection to make an integration with iDIN. Then we also have the possibility to:

  • Add custom test users in case it's required to test specific data sets
  • Add a graphical profile to the service

In case you would like to make use of these possibilities, please contact us at support@signicat.com

Furthermore it's possible to test unhappy iDIN flows through Signicat. In case it's required to test those flows, you can select the required scenario in the banking selection screen, by either selecting; Expired, Cancelled or Failure. This will result in the requested unhappy flow.

iDIN simulator

In the Signicat pre-production environment, all iDIN transactions are simulated as there is no connection to the banking applications in this environment. This means that you will not be redirected to the actual bank environment, these steps are simulated with a spinner. Actual iDIN transactions can be tried out at iDIN demo (opens new window)

# Example response

An example of an iDIN response from the identification flow from the test envrironment is illustrated below.

{
    "sub": "lu01zO18hi9JLXzPH0YAKzYMlofmSp15",
    "idin.requestedserviceid": "21974",
    "bankid.deliveredserviceid": "21974",
    "consumer.bin": "FANTASYBANK1234567890",
    "consumer.postalcode": "0000AA",
    "consumer.initials": "VJ",
    "consumer.partnerlastnameprefix": "de",
    "consumer.telephone": "+31203051900",
    "consumer.dateofbirth": "19750725",
    "consumer.gender": "1",
    "consumer.preferredlastnameprefix": "de",
    "consumer.partnerlastname": "Jansen",
    "consumer.houseno": "19",
    "consumer.city": "Aachen",
    "consumer.legallastnameprefix": "de",
    "consumer.preferredlastname": "Vries-Jansen",
    "consumer.street": "Pascalstreet",
    "consumer.country": "DE",
    "consumer.email": "info@equensworldline.nl",
    "consumer.legallastname": "Vries"
}

For a full list of the attributes that can be returned when using iDIN, refer to this section (opens new window) of the iDIN documentation.

# Deployment to production

Once the integration in the test environment is completed and you are ready to deploy the integration to the production environment, please make sure that you have provided Signicat with the following information, so that the service can be correctly configured before your go-live.

  1. Which iDIN methods you would like to use. The options are idin-ident, idin-login, idin-age (or the QR-code variants). In case applicable, please also indicate if you would like to use iDIN in combination with the Sign API.
  2. In case you would like to use a subdomain for the iDIN flow, make sure to follow the steps on establishing a subdomain
  3. If you would like to make use of the iDIN Directory Service. This service needs to be enabled on your service by Signicat.
  4. if the Signicat hosted iDIN banking selection screen is part of the flow, please make sure that the graphical profile is configured correctly. This also includes the name to be displayed in the title of the browser tab.
  5. The name of the company that should be displayed in the IDIN flow. This is the company name, the end user will see when giving consent to share the data.
  6. The preferred language to be applied to your specific iDIN service

# References

Below a list of useful references to video's and demo's:

# Support

If you have any further questions, contact us at support@signicat.com.

Last updated: 8/16/2021, 10:57:51 AM