Concepts

The Secure Connect API is an OAuth 2.0 authentication and authorization API designed to implement two-factor authentication and access consensually shared MYDIGIPASS user data, which can be used by your application for various purposes.

The aim of this document is to clarify the endpoints and sequence shown in the diagram below. Each numbered step (1 - 10) corresponds to a separate section where we explain the properties, implementation and behavior of each call.

Note that your application endpoint must be able to sequentially handle steps 2 through 8 to ensure a correct functionality. Third-party OAuth 2.0 client libraries are available to implement steps 2 through 6. Steps 7 and 8 require some custom development on your part.

Steps 9 and 10 are optional user accounting calls that either may be included in your application’s endpoint code or in a separate script.

secure connect endpoint sequence diagram

Setting up OAuth 2.0

Before you start implementing the OAuth 2.0 Secure Connect API, you need to register your application on our developer site. There you will be required to enter basic information about your application, such as its name, logo and redirect_uri.

Client ID and Client Secret

After registration, a client_id and client_secret will automatically be assigned to your application. Both are required to authenticate your application against MYDIGIPASS when executing API calls. While the client_id is considered to be public information, the client_secret must be kept confidential at all times. If it is compromised, a new one must be generated and all your authorized applications will have to be updated with the new secret.

Redirect URI

When users initiate the Secure Connect API sequence from your application, they will be redirected to MYDIGIPASS to authenticate and will be asked to share data with your application. After users grant authorization to access their user data, MYDIGIPASS will redirect the user’s browser to the redirect_uri configured for your application.

As a security precaution, MYDIGIPASS will verify that the redirect_uri passed in the authorization request and the configured redirect_uri match before redirecting the user’s browser to your application’s redirection endpoint.

The MYDIGIPASS authentication experience includes an authentication popup and consent screen which describes the information that users are being asked to share with your application. Both screens present the company logo you configured for your application as shown in the example below.

Your company logo will also appear in the MYDIGIPASS marketplace if you decide to publish your application there as well. This allows users who already have a MYDIGIPASS account to discover, explore and sign up for your application.

mdp company logo

1. Redirecting users to the authorization endpoint

About the authorization endpoint

The OAuth 2.0 authorization endpoint is used by MYDIGIPASS to authenticate users and obtain their authorization to share data with your application. Your application makes an authorization request by redirecting user’s browser to the authorization endpoint.

After completing its interaction with the user, MYDIGIPASS redirects the user agent back to your application’s redirect_uri with the response to the initial authorization request, which consists of an authorization code and, optionally, a state parameter.

Authorization endpoint behavior

When a user initiates an authorization request from your application, the authorization endpoint will behave in one of four ways, depending on whether or not the user has an active MYDIGIPASS session:

  1. If the user is already logged in to MYDIGIPASS and granted permissions to share data with your application, (s)he will immediately be redirected to your application’s redirect_uri with a valid authorization code and state (if implemented).

  2. If the user is already logged in to MYDIGIPASS, but did not yet agree to share data with your application, (s)he will be invited to do so. If the user grants access, (s)he will be redirected to your application’s redirect_uri with a valid authorization code and state (if implemented).

  3. If the user is not logged in to MYDIGIPASS, (s)he will be invited to do so. After logging in, the user will be asked to share his/her data with your application. If the user grants access to his/her data, MYDIGIPASS will redirect the user’s browser to your application’s redirect_uri with a valid authorization code and state (if implemented).

  4. If the user does not have an MYDIGIPASS account, (s)he will be prompted to sign up. After signing up, the user will be invited to share his/her MYDIGIPASS data with your application before being redirected to your application’s redirect_uri with a valid authorization code and state (if implemented).

CSRF attack prevention

A Cross-Site Request Forgery or CSRF attack is an attack that tricks a victim into submitting a malicious request. The request inherits the identity and privileges of the victim to perform an undesired function on the victim’s behalf.

When your application receives an authorization code (2), you want to make sure that the authorization request (1) was actually initiated by a legitimate user and not by an attacker.

We therefore recommend that your application supports the generation and temporary storage of a random, unguessable state value when redirecting users to the MYDIGIPASS authorization endpoint.

After the user authenticates and grants access to his/her MYDIGIPASS user data, your application must compare the state parameter in the response (2) to the one of the initial authorization request (1).

If both match, your application can safely process the remaining OAuth 2.0 calls.

Data scope and API behavior

The scope parameter configured in the authorization request determines which MYDIGIPASS user data can be accessed by your application with a valid access token and also directly affects the API’s behavior.

Authentication only

If you are only interested in providing strong authentication for your application, you do not need access to a user’s MYDIGIPASS data; the access token is not used. This behavior is triggered by assigning an empty value to the data-scope attribute of the MYDIGIPASS button, i.e. data-scope="".

Authentication and data retrieval

The type of user data which can be accessed by your application is defined in the data-scope attribute of the MYDIGIPASS button. The user will have to grant permissions to your application before the access token can be used to retrieve user data within the granted scope.

See the MYDIGIPASS button developer reference for a list of supported data scopes.

Implementing the authorization request

The easiest and recommended method to implement the authorization request is to use the MYDIGIPASS button and Javascript When a user clicks the button, a GET request is issued with the configured parameters to the MYDIGIPASS authorization endpoint. An alternative method, which uses a POST request, is explained further in this section.

MYDIGIPASS button and Javascript

The MYDIGIPASS button and Javascript button automatically takes care of redirecting the user’s browser to the MYDIGIPASS authorization endpoint and requesting an authorization code for your application.

As a security precaution, MYDIGIPASS will verify and validate the redirect_uri passed in the authorization request before redirecting the user’s browser to your application’s redirection endpoint.

To implement the authorization request, include our JavaScript in your application’s landing page and configure the href URL of the button with the appropriate language code (en, fr, de, nl or it). Place the <script> tag at the end of your application’s login page right before its closing </body> tag to prevent page load interruptions.

Example for English language
<script src="https://static.mydigipass.com/en/dp_connect.js" type="text/javascript"></script>

Add an <a href="#"></a> tag and set its CSS class to dpplus-connect. The MYDIGIPASS JavaScript will automatically add CSS styles to render it as as our MYDIGIPASS button.

Secure Login with MYDIGIPASS.COM Secure Login with MYDIGIPASS.COM Secure Login with MYDIGIPASS.COM

Include the type of MYDIGIPASS user data your application should be able to access in the button’s data-scope attribute. Configure an empty data-scope, i.e. data-scope="", if you intend to use the Secure Connect API for strong authentication only. See our developer reference for additional information about this parameter. Specify the data-client-id and data-redirect-uri assigned to your application. See our developer reference for additional information about this parameter.

To protect your application against CSRF attacks, your application must have a method to generate and verify CSRF tokens. You should use this functionality to set the data-state value. See our developer reference for additional information about this parameter.

Example for data-scope email, phone and eid_profile
<a href="#" class="dpplus-connect" data-scope="email phone eid_profile" data-client-id="5tebn0q12kv52mqnwcdhk0mu9" data-redirect-uri="http://yourapp.com" data-state="{generate_csrf_token}" data-is-sandbox="true" href="#">Signup with MYDIGIPASS.COM</a>

When users click on the MYDIGIPASS button, they will be redirected to the MYDIGIPASS authorization endpoint to request an authorization code. Based on the example above, the user’s browser will execute the following call:

GET

https://www.mydigipass.com/en/oauth/authenticate.html?response_type=code&client_id=5tebn0q12kv52mqnwcdhk0mu7&popup=1&redirect_uri=http%3A%2F%2Fyourapp.com&is_sandbox=true&state=YOUR_CSRF_PREVENTION_CODE&scope=email%20phone%20eid_profile%20eid_photo

POSTing to the authorization endpoint

The MYDIGIPASS authorization endpoint also supports POST requests to streamline user enrollment from your application towards the MYDIGIPASS platform. POST requests are typically implemented on your application’s user enrollment or profile page by means of an HTML form and are suitable to submit sensitive user enrollment data. GET requests are not suitable in this case, because the application/x-www-form-urlencoded user enrollment data would end up in browser histories and application logs.

When users sign up for your application and enter their personal details, the user information entered in your application’s user registration HTML form is automatically parsed in the MYDIGIPASS user signup form.

mdp signup form

After enrollment, MYDIGIPASS will redirect the user agent to your application’s redirection endpoint and initiate the Secure Connect API flow.

To redirect the user with a POST request, your application needs an HTML form that is submitted to the MYDIGIPASS authorization endpoint when users sign up for your application or when they connect their account to MYDIGIPASS. You can also make this transparent for end-users by using a hidden form and submit it when users connect their account to MYDIGIPASS.

HTML form example
<form action="http://www.mydigipass.com/oauth/authenticate"
	    method="post"
	    accept-charset="UTF-8">
  <!-- OAuth parameters -->
  <input type="text" name="response_type" value="code" />
  <input type="text" name="client_id" value="your-application_client_id" />
  <input type="text" name="redirect_uri" value="http://yourapp.com" />
  <input type="text" name="state"
         value="{generate_csrf_token}" />
  <!-- enrollment-data parameters -->
  <input type="text" name="enrollment_data[first_name]" value="first_name_of_the_user" />
  <input type="text" name="enrollment_data[last_name]" value="last_name_of_the_user" />
  <input type="text" name="enrollment_data[email]" value="user@domain.com" />
  <input type="text" name="enrollment_data[birth_date_year]" value="YYYY" />
  <input type="text" name="enrollment_data[birth_date_month]" value="MM" />
  <input type="text" name="enrollment_data[birth_date_day]" value="DD" />
  <input type="text" name="is_sandbox" value="true" />
  <input type="submit" value="Sign up with MYDIGIPASS">
</form>

2. Receiving the authorization code

About the redirection endpoint

The redirection endpoint of your application is where users are redirected to (see step 2 in the sequence diagram) after authenticating and granting authorization to access their MYDIGIPASS user data at the authorization endpoint. There your application receives an authorization code and, if configured, a state parameter.

Your application’s redirection endpoint corresponds to the redirect_uri configured for your application and the value set for the data-redirect-uri in your application’s MYDIGIPASS button configuration.

When your application’s redirection endpoint is called, your application’s endpoint code must be able initiate the required back-channel requests (steps 2 - 8 in the sequence diagram) towards the token and subsequent API endpoints. OAuth 2.0 client libraries are available to facilitate the implementation of steps 2 through 6.

Even though steps 7 and 8 are not an intrinsic part of the OAuth 2.0 protocol flow, they must be supported by your redirection endpoint code to ensure the correct functionality of the API. See sections 7 and 8 for additional information.

Steps 9 and 10 are optional user accounting calls may be included in your application.

About the authorization code and state parameter

The authorization response contains the authorization code needed to obtain an access token and the MYDIGIPASS UUID of the user.

For example, if your application’s redirect_uri is set to http://yourapp.com, MYDIGIPASS will redirect the user’s browser to http://yourapp.com with a one-time authorization code in the code parameter of the GET request and a state parameter, if configured:

GET /?code=Bl7wYc7Tydn5qcm0flrz613in&state=YOUR_CSRF_PREVENTION_CODE HTTP/1.1
Host: yourapp.com

The code parameter contains the authorization code.

A state parameter is only received if the data-state attribute of the MYDIGIPASS button has been set and configured.

Security precautions

Any value received in the state parameter must be evaluated by your application to ensure it’s the same one you passed in the data-state attribute of the MYDIGIPASS button.

Error messages

If an error was made in the configuration of the MYDIGIPASS button, e.g. in case of a missing or wrong parameter, MYDIGIPASS will redirect the user’s browser to your application’s redirection endpoint and include information about the error in the error & error_description parameters:

http://yourapp.com/?error=redirect_uri_mismatch&error_description=Parameter+redirect_uri+does+not+match+a+registered+URI

3. Exchanging the authorization code for an access token

Token endpoint

The MYDIGIPASS token endpoint is the endpoint where your application exchanges the authorization code for a time-limited access token and the UUID of the user, using its client_id, client_secret, redirect_uri and other parameters.

To exchange the authorization code for a time-limited access token, your application must send a POST request to https://www.mydigipass.com/oauth/token with the required parameters. OAuth 2.0 client libraries are available to support this functionality. A curl example is provided in the developer reference guide.

Error messages

An attempt to exchange an invalid, malformed or expired authorization code will result in an error. See the developer reference for a list of possible error messages.

4. Receiving the access token and the UUID of the user

Introduction to the UUID

The UUID is an attribute which uniquely identifies a MYDIGIPASS user.

MYDIGIPASS is not a replacement for your application’s user management, nor can it handle the authorization part. Your application needs its own user database so it can handle a UUID received by MYDIGIPASS, regardless of whether your are using the API for strong authentication only or strong authentication combined with the retrieval of MYDIGIPASS user data.

mdp user management

Using the API for authentication only

This behavior is triggered by assigning an empty value to the data-scope attribute of the MYDIGIPASS button, i.e. data-scope="". The result is an empty scope value in the JSON response, which means the access_token cannot be used to retrieve data.

{"access_token":"d9nmffswyr09fwlw516o6maki","scope":"","uuid":"02864f80-1265-0133-5181-00163e6e36d9"}

To create an authenticated session, your application needs to be able to handle the MYDIGIPASS UUID received in the JSON response.

Handling a known UUID

If the user’s UUID already exists in your database and has been correctly connected to MYDIGIPASS, your application can simply compare the UUID in the user’s record to the UUID received by MYDIGIPASS. If both match, your application can create an authenticated user session and allow access to its premium content.

Handling an unknown UUID

If a user’s UUID is unknown to your application, it needs to verify whether or not the user has an authenticated session for your application.

In case of an authenticated session, your application must store the received UUID in the user’s database record to allow future MYDIGIPASS logins. Your application must then notify MYDIGIPASS that the UUID has been successfully stored by calling the connect endpoint. This call is required at least once for every user of your application to prevent MYDIGIPASS authentication lockouts.

In case of an unauthenticated session there is no other option than to ask users if they already have an account for your application. Depending on the answer, your application should either redirect the user to your application’s login page (existing user) or to your application’s sign-up page (new user).

After enrollment (new user) or authenticating the user (existing user), your application must store the UUID in the matching user database record and call the connect endpoint to notify MYDIGIPASS that the UUID has been successfully stored. This call is required to prevent MYDIGIPASS authentication lockouts.

Using the API for authentication and data retrieval

If you specified a data-scope for the MYDIGIPASS button, the granted scope will be shown in the JSON response. Your application must use the access token in this response to retrieve the MYDIGIPASS user data.

{"uuid":"d61ef2e0-0b60-0133-4853-00163e43cad9","access_token":"cGmrDxRQLiz8kJJFfjzwGj7HFg48WhNCHevlGOZ4","scope":"email phone eid_profile eid_photo"}

5. Retrieving eID and other user data

eID data and photograph

The eID card data and the eID photo are obtained by MYDIGIPASS via an electronic authentication process that reads the user’s eID card. This data can be used by your application in a TDI context. See section 7 for examples and use cases.

Other user data

This data is provided by the user as is, which means it is not verified in any way by MYDIGIPASS. For example, the first and last name provided by users during sign-up.

The only exception is the user’s e-mail address, which can only be retrieved by your application after it has been confirmed by the user.

Granted scopes

The data which may be accessed by your application is determined by the initial authorization request where the data-scope is set. This data-scope translates to a granted scope in the JSON response.

Once the user has granted your application access to parts of his data, your application will be able to retrieve that data, even when you do not ask for it by passing the data-scope parameter.

{"uuid":"d61ef2e0-0b60-0133-4853-00163e43cad9","access_token":"cGmrDxRQLiz8kJJFfjzwGj7HFg48WhNCHevlGOZ4","scope":"email phone eid_profile eid_photo"}

Note that your application will only be able to retrieve data within the granted scope. Attempting to retrieve data outside the granted scope will be denied. See the developer reference for a complete list of available data scopes.

Data endpoints

To retrieve data within the granted scope, such as a user’s eID data, your application must be able to send a GET request to the associated MYDIGIPASS data endpoint(s) with the access token received in the previous JSON response.

  • eID data endpoint (TDI context): https://www.mydigipass.com/oauth/eid_data

  • eID photo data endpoint (TDI context): https://www.mydigipass.com/oauth/eid_photo_data

  • Other user data: https://www.mydigipass.com/oauth/user_data

The access token of the previous response must be included as a Bearer Token in the Authorization header of the request. OAuth 2.0 client libraries are available to support this functionality. See the developer reference for a curl example and the required parameters.

Error messages

Your application will only be able to retrieve existing user data within the granted scope. Attempting to retrieve data outside the granted scope or using an expired access_token to retrieve data will result in an error.

If your application attempts to access non-existing user data with a valid access_token, e.g. if the user does not have an eID profile or deletes his/her eID profile from MYDIGIPASS, an error will also be returned. A list of error messages is available in the developer reference.

6. Receiving eID and other user data

MYDIGIPASS will return the requested eID and user data in a JSON hash, similar to the examples shown below. Note that the eID photo data will be returned as a binary representation of the user’s eID photograph. See the reference guide for additional details.

Your application can use the retrieved data for various purposes, in and outside a TDI context, as explained in the next section.

HTTP example response for eID data scope
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Connection: close

{
            "first_name": "John",
          "first_name_3": "F",
             "last_name": "Doe",
                "gender": "M",
           "nationality": "Belg",
         "date_of_birth": "1980-05-19",
         "raw_date_of_birth": "19 Mai 1980",
     "location_of_birth": "Berchem",
       "noble_condition": "",
  "issuing_municipality": "Dilbeek",
           "card_number": "581560104102",
           "chip_number": "8367237881102019148136319518924559",
    "validity_begins_at": "2012-01-26",
      "validity_ends_at": "2017-01-26",
            "created_at": null,
                 "photo": null
}

Please note :

  • the user’s home address is not included in the response above

  • in addition to the date of birth, a raw date of birth field is returned. The Belgian eID standard allows for an incomplete date of birth to be present on the chip. It is not possible for us to reliably deliver a formatted date of birth in such conditions. This raw date of birth field will contain the unprocessed value held in the card, regardless of wether it is a valid date or not.

Include eid_address in the data-scope parameter of the MYDIGIPASS button to retrieve the eID address. Note also that we currently do not provide a way to retrieve the national number.

HTTP example response for user data scope
HTTP/1.1 200 OK
Content-Type: application/json
Connection: close

{
         "email": "johndoe@gmail.com",
    "updated_at": "2015-07-14T06:36:31Z",
  "phone_number": "+32475555444",
          "uuid": "d61ef2e0-0b60-0133-4853-00163e43cad9"
}

7. Storing the UUID and retrieved user data

Using eID data

By accessing consensually shared eID card data, your application can use a user’s electronic identity and combat online identity fraud. In this section we provide some real-life examples which you may find useful.

Age restrictions

Depending on the type of content and activities offered by your application and your geographic location, you may want to implement minimal age restrictions.

For example, if your are running a gambling site, you may want to have a robust customer identity verification process to ensure that customers are over the legal age to gamble.

This can be achieved by verifying the date of birth in the user’s eID profile.

Access to sensitive data

For healthcare providers, government portals and other various platforms, the growing demands for the protection of identities and control over sensitive data can be daunting.

The eID profile information is perfectly suitable to verify a user’s electronic identity and restrict the access to sensitive information.

Pre-populating your sign-up forms

A user’s eID profile can also be used to streamline your application’s user enrollment process, for example by pre-populating your application’s sign-up form with the retrieved eID profile data.

Using other data

The remaining user data can also be used by your application for various purposes, albeit outside a TDI context. For example, to streamline your application’s user enrollment process or to store the user’s contact information in your customer database, such as the user’s confirmed e-mail address and phone number.

8. Connecting users

Whether or not you are using the Secure Connect API to retrieve a user’s MYDIGIPASS data (6) or for strong authentication only (4), your application must always notify MYDIGIPASS when it receives and stores a new UUID by calling the connected endpoint.

Even though this step is not an intrinsic part of the OAuth 2.0 protocol flow, it must be included in your redirection endpoint code to ensure the correct functionality of the API.

By calling the connected endpoint, your application notifies MYDIGIPASS that a user’s UUID has been properly stored and linked (connected) to your application’s user records. This prevents authentication lockouts, as unconnected users won’t be able to log in to your application with MYDIGIPASS after 5 unconnected logins. The limitation of 5 unconnected logins is lifted once your application has successfully called the connected endpoint.

In order to connect a user, your application must POST the user’s UUID on https://www.mydigipass.com/api/uuids/connected. See the api reference for a curl example, required parameters and possible error codes.

9. Disconnecting users

The API’s disconnected endpoint should only be called by your application when users cancel their account or if you wish to revert to your own authentication platform.

In order to disconnect a user, your application must be able to must be able to POST the user’s UUID on https://www.mydigipass.com/api/uuids/disconnected. See the developer reference for a curl example, required parameters and possible error codes.

10. Getting a list of connected users

If you want to fix errors, correct discrepancies or simply verify which of your users have already been successfully connected to MYDIGIPASS, you can send a GET request to the API’s connected endpoint: https://www.mydigipass.com/api/uuids/connected.

The result can then be compared to your own user database to fix discrepancies, if any. See the developer reference for a curl example, required parameters and possible error codes.