Get started

There are 5 main steps to integrate a MiTrust sharing flow:

1. 🛠️ Set up the scope and state
2. 🚀 Start the MiTrust sharing flow
3. 🔗 MiTrust calls your redirect URI
4. 🪙 Convert the authorization code into an access token
5. 👤 Fetch the user info and user content

1. 🛠️ Set up the scope and state

In order to initialize a MiTrust session (called “sharing flow”), you will need to setup two important parameters: the scope and the state.

In OAuth2, a scope is a string that may represent a resource the client requests access to. Each scope returns a set of user attributes, which are called claims. You should design a scope which suit your business needs – MiTrust usually assists you on this through several data workshops. The full list of claims will be shared with you in the course of the set-up project.

📘

If you have multiple claims

They must be separated by a space (i.e. separated by '%20' or '+' a er encoding). These claims (or a subset of them) will be provided in the Start Sharing Flow URL :

scope=name address ⇒ scope=name%20address

The state is a unique identifier for the MiTrust sharing flow, which you have to set up beforehand. It is very important that you set up state parameters which are unique, otherwise it will be very difficult for MiTrust to provide you with technical support (state – or user_name – is a mandatory information for any support request). You may also encounter serious bugs and security issues if your state parameters are not unique.

The state is a string, so you may encode information in it (in JSON format), like a customer ID or other information which will be passed end to end throughout the sharing flow.

2. 🚀 Start the MiTrust sharing flow

A typical URL to start a MiTrust Sharing Flow for an End User should look like this: (See our integration example for starting a Sharing Flow)

https://sbx-app.m-itrust.com/v2/sp/sharingflow/start?client_id=myClientId&scope=someScope&state=uniqueState&redirect_uri=encodedRedirectUri

Each url params is explained in the table below:

Variable	Description
client_id	Provided on application registration. You can request it @ [email protected]
redirect_uri	The End User will be redirected to this URL in case of success / error. (See redirect_uri) You have to properly encode the parameters (especially the scope and redirectUri). In Javascript, you should rely on encodeURIComponent
scope	The scope determining which information you ask the End User to share with your application. (See scope)
state	The state value is mandatory in MiTrust integration(even if it is not mandatory in OAuth2 protocol). You can use it to specify a user_id. (See state) Example : state { st: "randomUUID", user_id: "someUserId" }
language	(Optional) Used to defined the language of the SharingFlow. (By default, will be the language of the SP)

We advise redirecting to Mitrust through a popup. You can open a Mitrust popup with the following javascript code by adding a window.open :

> window.open('<https://sbx-app.m-itrust.com/v2/sp/sharingflow/start?client_id='> + client_id + '&scope=' + scope + '&state=' + encodeURIComponent(state) + '&redirect_uri=' + encodeURIComponent(redirectUri), 'newwindow', 'width=414,height=736');

3. 🔗 MiTrust calls your redirect URI

If the End User consents to share his data with your application, the End User will be redirected towards the provided redirect_uri with additionnal parameters.

https://example.com/mitrust_redirect_redirect_uri?state=generatedUniquesState&code=authorization_code

The state value (generatedUniqueState) should be the same value provided when you have started the sharing flow

4. 🪙 Convert the authorization code into an access token

The authorization_code given back in the URL, should be converted into an access_token with your client_id and your secret_key with a POST request.

This request should be done from the backend to prevent having your secret_key publicly visible in your FrontEnd.

📘

The secret_key is provided on application registration. It is a private information, it shall remain known by your BackEnd only.

It is very important not to convert the authorization_code from a web GUI or a mobile application.

It implies your secret_key will not be private anymore. Contact [email protected] for any issues concerning your secret key.

The POST request needs to be authenticated with BASIC (See our integration example for converting an authorization code)

JavaScript

{ 
  body: { 
     code: "sOmEcOdE", 
    grant_type: "authorization_code", 
    redirect_uri: "encodedRedirectUri" 
  }, 
  headers: { 
    Authorization: "Basic + 'Base64(client_id:secret_key)'", 
    Content-Type: "application/x-www-form-urlencoded" 
  }, 
  method: "POST", 
  url: "<https://sbx-app.m-itrust.com/oauth/token"> 
}

More info about x-www-form-urlencoded Content-type specifications ⇒ https://tools.ietf.org/html/rfc6749#appendix-B

Once the POST request is made, the response should be a status: 200 with a JSON like this:

JSON

{
  access_token: "someAccessToken", 
  expires_in: 43199, 
  jti: "6cfbf7c7-f62f-403d-9ee2-968cd41726dd", 
  scope: "all", 
  token_type: "bearer" 
} 

A status 200: Means everything is ok, a JSON is provided as a response containing the access token

A status 401: Means your client_id or client_secret is invalid.

A status 400: Something is wrong maybe the code is already used.

JSON

{ 
 error: "invalid_grant", 
 error_description: "Invalid authorization code: someCode" 
} 

Now that you have your access token you can query our entrypoint to get your /userinfo by using your access_token as a Bearer token.

The access token is a JWS object that contains several fields in a payload:

• client_id: Your client id
• user_name: also called SharingFlow ID – the unique identifier to a MiTrust transaction as defined by MiTrust
• exp: Contains the expiry time of a session of the current Sharing Flow
• scope: Contains scope for the current Sharing Flow

JSON

{ 
  aud: [ 
    "oauth2-resource" 
  ], 
  authorities: [ 
  "ROLE_TRANSIENT" 
  ], 
  client_id: "some-client-id", 
  exp: 1568080662, 
  jti: "df97370b-70b4-4711-9068-106e6b589d16", 
  scope: [ 
    "all" 
  ], 
  user_name: "4ffcbf4d-aa3e-4354-95d4-f6c23ee63e5f" 
} 

❗️

For security reasons, it is very important to confirm at this stage that the scope produced is identical to the scope initially requested, in order to prevend any attempt to temper with the scope.

5. 👤 Fetch the user info and user content

Make a request on https://sbx-app.m-itrust.com/user_data/v1/userinfo.

JavaScript

{ 
  Headers: { 
    Authorization: "Bearer 'converted_access_token'" 
  } 
} 

As a response, you will receive a JSON that contains user_info and the associated user_consent.

JSON

{ 
	data: { 
    user_consent: { 
      jwe: "encryptedUserConsent" 
    },
    user_info: { 
      address: { 
        locality: "Paris" 
      }, 
      name: "John DOE"
    }
  }    
  message: " some message ", 
  status: "succes" 
} 

In some cases, some enrichments will be applied to the data (e.g. address normalization). These enrichments are not mixed with the data from the Data Provider: they are provided in the key post_processed, sibling of user_info.

The user_consent is an encrypted piece of data. As a Service Provider, you can decrypt only a subset of data with the help of <https://app.m-itrust.com/service_provider/v1/userconsent>

JSON

{ 
  post_processed: { 
    address: { 
      route: "rue Bellini", 
      street_address: "3 rue Bellini", 
      street_number: "3" 
    }
  }  
  user_consent: { 
    jwe: "encryptedUserConsent"
  }
  user_info: { 
    address: { 
      formatted: "3 rue Bellini 92800 Puteaux", 
      locality: "Puteaux", 
      postal_code: "92800" 
    }, 
    name: "John DOE" 
  } 
}