Best practices

Introduction

MYDIGIPASS is not a replacement for your application’s user management, nor can it handle the authorization part. You need your own user database so you can store and match the MYDIGIPASS UUID with the right user before authorizing access to your application’s premium content.

The Secure Connect API can be used to provide strong authentication only or to combine strong authentication with the possibility to access a user’s MYDIGIPASS data, i.e. to facilitate user registration. The behavior of the API is determined by the values configured for the data-scope attribute of the Secure Login Button.

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 OAuth Access Token is not used. To create an authenticated session, your application only needs to match the user in its database with the UUID received by MYDIGIPASS.

Therefore, your application must have the ability to store the UUID in the corresponding user record, e.g. after the user has been logged in to your application by means of an email/password combination.

To authenticate users, you don’t need to ask users to grant permissions to your application to access MYDIGIPASS user data. This behavior is triggered by assigning an empty value to the data-scope attribute of the Secure Login Button, i.e. data-scope="".

Authentication and data retrieval

To improve your application’s user sign-up experience and pre-populate your application’s sign-up form with MYDIGIPASS data, your application needs to be able to access a user’s MYDIGIPASS data.

The type of data which can be accessed by your application is defined in the data-scope attribute of the Secure Login Button. The user will have to grant permissions to your application before the OAuth Access Token can be used to retrieve user data within the granted scope. Data is retrieved on the following API endpoints: /oauth/user_data, /oauth/eid_data or /oauth/eid_photo_data.

The UUID obtained with the OAuth Access Token must be used to authenticate the corresponding user in your application’s database.

Account linking

Integrating the Secure Connect API is a straight forward task from a technical perspective. However, it is important to keep a close look on the User Experience (UX) for the different use cases.

mdp user management
Figure 1. Account Linking

Use cases

  • Login: the most regular and straightforward use case

  • Sign-up: a new user signs up for your application

  • Connect: an existing user wants to enable MYDIGIPASS for your application

Technically speaking, you use the same Secure Login Button code, but you need to adapt the data-style attribute to present a proper button layout that matches each use case.

When the OAuth Authorization Code is exchanged for an OAuth Access Token, your application receives the user’s UUID. It is up to your application to correctly handle known and unknown UUIDs.

Known UUIDs

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

Unknown UUIDs

If a user’s UUID is unknown to your application, you need to consider whether or not the user has an authenticated session for your application.

In case of an authenticated session

When your application receives the user’s UUID from MYDIGIPASS, it must be stored it in the user’s database record to allow future logins with MYDIGIPASS.

When the UUID has been stored, your application must call the connect endpoint to notify MYDIGIPASS that the user has been linked.

In case of an unauthenticated session

In this case there are 2 possible situations:

  • The user already has an account, but isn’t logged in to your application (existing user).

  • The user does not have an account for your application (new user).

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).

In the sign-up scenario, you have the option to pre-populate your sign-up form with MYDIGIPASS user and eID data (if available and configured in the Secure Login Button’s data-scope attribute). This reduces typing when users sign up for your application.

In both cases, your application must store the UUID in the user’s database record and call the connect endpoint to notify MYDIGIPASS that the user has been linked.

Marketplace

When upgrading to Plus, you also have the option to publish your application on the MYDIGIPASS marketplace. This allows users with a MYDIGIPASS account to discover, explore and sign up for your application. We therefore recommend that you build a dedicated landing where you promote your application and explain the security benefits of logging in with MYDIGIPASS.

Users will be redirected to this page when they click on your application icon in the MYDIGIPASS marketplace. You need to provide exit lanes for users who want to sign up (new user) or log in if they already have an account for your application.