Quick start

This document is a quick start guide intended for developers looking to integrate the MYDIGIPASS OAuth 2.0 Secure Connect API illustrated below. The integration consists of the following steps:

  • Implement the MYDIGIPASS Secure Login Button to redirect your users to the MYDIGIPASS authorization endpoint.

  • Write the code for your application’s redirection endpoint so that it can sequentially execute steps (2) - (8) of the sequence diagram.

  • Configure your application so that it can execute the remaining, optional user accounting actions (see disconnecting users and getting a list of connected users at the end of this document).

secure connect endpoint sequence diagram

Prerequisites

To implement the MYDIGIPASS OAuth 2.0 Secure Connect API, you first need to register your application. There you can give your application a name, provide the required callback OAuth redirect_uri and upload a logo for the MYDIGIPASS Marketplace.

The client_id, client_secret and the callback redirect_uri of your application are required to successfully integrate the API.

Tip

Each numbered step of the sequence diagram above is explained separately in the following sections. Please note that steps (2) to (8) must be handled sequentially by your redirection endpoint code. Even though step 8 is not an intrinsic part of the OAuth 2.0 protocol flow, it must be present in your redirection endpoint code to ensure a correct functionality. Third-party OAuth 2.0 libraries are available to implement steps (2) - (7).

1. Redirecting users to the authorization endpoint

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

To implement this step, you must include the Secure Login Button JavaScript in your application’s landing page and configure the URL with the appropriate language code (en, fr, de, nl or it). Place the <script> tag at the end of your login page right before its </body> tag, in order to avoid page load interruptions when a user’s browser loads the MYDIGIPASS JavaScript.

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 Secure Login Button.

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.

Specify the data-client-id and data-redirect-uri configured for your application.

Finally, set the button’s data-is-sandbox attribute to true. This is required to test your application (sandbox mode). You must change this value to false when putting your application into production.

Please note that we only mention the minimal, required button attributes in this example. See the concept guide and the Secure Login Button reference for information about other, more advanced attributes such as CSRF prevention.

Example for data-scope email, phone and eid_profile
<a class="dpplus-connect" data-scope="email phone eid_profile" data-client-id="5tebn0q12kv52mqnwcdhk0mu9" data-redirect-uri="http://yourapp.com" 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 using a GET request, for example:

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&scope=email%20phone%20eid_profile

2. Receiving the authorization code

The authorization response contains the authorization code needed to obtain an access token.

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 OAuth Authorization Code in the code parameter of the GET request, for example:

GET /?code=i4tFBL7Ts3YRH1YzgBWonMtDo HTTP/1.1
Host: yourapp.com

Your application must be able to handle this authorization code, so that it can exchange it for an OAuth Access Token and the user’s MYDIGIPASS UUID in the next step.

3. Exchanging the authorization code for an access token

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:

POST /oauth/token HTTP/1.1
Host: www.mydigipass.com
Content-Type: application/x-www-form-urlencoded
Accept: */*

code=5bx5vq39nr35ctx954im1g314&
client_id=5tebn0q12kv52mqnwcdhk0mu9&
client_secret=808b8fw4kjmn23441iezbupmm&
redirect_uri=https://your-site.com/callback&
grant_type=authorization_code

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

A successful response contains the following fields in a JSON hash:

HTTP/1.1 200 OK
Content-Type: application/json

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

If you are using the Secure Connect API for strong authentication only (in case of an empty scope), your application can consider the user as successfully authenticated based on the UUID in the response. In this case, your application must store the UUID and call the connect endpoint to allow future MYDIGIPASS logins.

If your application also requires access to a user’s MYDIGIPASS data, it must retrieve this data by calling the associated data endpoint(s) with the received access_token. 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.

5. Retrieving eID and other user data

To retrieve user data within the granted scope, your application must send a GET request to the appropriate data endpoint(s):

  • https://www.mydigipass.com/oauth/user_data

  • https://www.mydigipass.com/oauth/eid_data

  • https://www.mydigipass.com/oauth/eid_photo_data

The access_token of the previous response must be included as a Bearer Token in the Authorization header of the request, for example:

HTTP example request for eID data scope
GET /oauth/eid_data HTTP/1.1
Host: www.mydigipass.com
Accept: */*
Authorization: Bearer 5GQZ7ibaaGhPRP8CYm5am1EtyLGaVqFrpOrJn4fs
HTTP example request for user data scope
GET /oauth/user_data HTTP/1.1
Host: www.mydigipass.com
Accept: */*
Authorization: Bearer 5GQZ7ibaaGhPRP8CYm5am1EtyLGaVqFrpOrJn4fs

6. Receiving eID and other user data

MYDIGIPASS will return the requested user data in a JSON hash, for example:

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",
     "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 that the user’s home address is not included in the response above. 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

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 store and match the MYDIGIPASS UUID with the right user before authorizing access to your application’s premium content.

The eID and other user data can optionally be used by your application for various purposes, for example to streamline user enrollment by pre-populating your application’s sign-up form or to verify a user’s electronic identity (eID). See the concept guide for in-depth information about this subject.

8. Connecting users

After your application has successfully stored the UUID in its user database, it must notify MYDIGIPASS by calling its connected endpoint. This step is required at least once for every MYDIGIPASS user in your application’s database. Unconnected users are limited to 5 MYDIGIPASS logins. Users who exceed this limit will no longer be able to log in to your application with MYDIGIPASS. To lift this limitation, your application must call the connected endpoint as explained below.

Create a request that uses Basic Authentication. Use your application’s client_id and client_secret as credentials for the connect endpoint. Store the MYDIGIPASS UUID in a JSON array and POST the resulting request on https://www.mydigipass.com/api/uuids/connected.

The Authorization header shown in the example below is the base64-encoded string for <client_id>:<client_secret>.

HTTP example request
POST /api/uuids/connected HTTP/1.1
Host: www.mydigipass.com
Authorization: Basic YTF0eWFmdnU2bWtiZXV2M3p0bzMzZW85YzpjeTZyZGJ4bGdxaTRyaHhvYmJkbm03OG5h
Accept: */*
Content-type: application/json
Content-Length: 53

{"uuids" : ["d61ef2e0-0b60-0133-4853-00163e43cad9"] }

A successful call will return a 201 Created HTTP status code.

9. Disconnecting users

The disconnected endpoint must be called by your application in case users cancel their account or if you wish to revert to your own authentication platform.

Create a request that uses Basic Authentication. Use your application’s client_id and client_secret as credentials for the disconnected endpoint. Store the MYDIGIPASS UUID in a JSON array and POST the resulting request on https://www.mydigipass.com/api/uuids/disconnected.

The Authorization header shown in the example below is the base64-encoded string for <client_id>:<client_secret>.

POST /api/uuids/disconnected HTTP/1.1
Host: www.mydigipass.com
Authorization: Basic YTF0eWFmdnU2bWtiZXV2M3p0bzMzZW85YzpjeTZyZGJ4bGdxaTRyaHhvYmJkbm03OG5h
Accept: */*
Content-type: application/json
Content-Length: 53

{"uuids" : ["d61ef2e0-0b60-0133-4853-00163e43cad9"] }

A successful call will return a 201 Created HTTP status code.

10. Getting a list of connected users

Call the connected endpoint to get a list of connected UUIDs for your application. The result can be compared to your own user database to correct problems.

Create a GET request that uses Basic Authentication. Use your application’s client_id and client_secret as credentials for the connected endpoint. Send the GET request to https://www.mydigipass.com/api/uuids/connected.

The Authorization header shown in the example below is the base64-encoded string for <client_id>:<client_secret>.

HTTP example request
GET /api/uuids/connected HTTP/1.1
Host: www.mydigipass.com
Authorization: Basic YTF0eWFmdnU2bWtiZXV2M3p0bzMzZW85YzpjeTZyZGJ4bGdxaTRyaHhvYmJkbm03OG5h
Accept: */*
Content-type: application/json
Content-Length: 53
HTTP example response
HTTP/1.1 200 OK
Content-Type: application/json
Connection: close

{"uuids":["d61ef2e0-0b60-0133-4853-00163e43cad9", "57ca859e-0b57-4d2b-bfb7-303b72596324""]}