Popup vs full-screen integration

MiTrust supports various integration modes (popup, full screen, new tab). However, popup is very, very strongly recommended if you don't want to lose users.

In order to open a Mitrust popup, it is recommend to use window.open call:

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), 'name of your popup', 'width=414,height=736');  

The size of the popup is defined as a params of window.open. We recommend a size of width 414px & height 736px

Opening a popup with a HTML anchor tag is not recommended, because you will be unable to define the popup size.

📘

About popup blockers

Some browsers may block the opening of the popup or new tab

🚧

Warning

The call to window.open should be done on the user click event. Any delay (like the use of setTimeout, XHR call or Promises) may lead to popup being blocked by the browser.

Therefore, the MiTrust start flow URL must be integrated directly into the page, or retrieved on page load, but not after the user has clicked on the MiTrust button, as this would be considered lazy loading and blocked by some browsers.

You need to test your integration with the appropriate configuration (Android, iOS, Chrome, Safari, Edge) to make sure it's not blocked by the browser.

See Popups reference links:

Google Chrome: https://support.google.com/chrome

Apple Safari: https://support.apple.com/guide/safari

Firefox: https://support.mozilla.org/pop-blocker-settings-exceptions-troubleshooting

In case the MiTrust button stays visible in your UI while the Sharing Flow is in progress in its own popup, there is always the possibility that the End User might navigate between windows. Therefore, we recommend handling the clicking on the MiTrust button like this:

1. If a popup is already opened and backgrounded, restore it as the front window by calling focus() on the window object handling the popup
2. Otherwise, open a new popup to start a fresh Sharing Flow, and keep a reference to it

After the end of the MiTrust flow, somewhere on your redirect URI page, you should close the popup

window.close();

Scope, grammar, granularity and attributes

The list of sources (Data Providers) proposed to the end ensure is computed automatically based on the scope. Only data providers capable of producing valid and complete profiles are proposed to the user.

Each Data Provider may provide a different granularity for the same data. For instance, some Data Providers will provide a name, but not separate given_name and family name. Some Data Providers will provide a postal_address.formatted, but not separate elements like address.street, address.city, etc.

The full list of claims will be shared with you in the course of the set-up project

The MiTrust Grammar (full claims list)

• Several attributes may be added to the claims composing a scope. Here are a few examples:
• Data requirement: name#essential family_name#softly_required
• AutoUpdate role: name#invariant proof_of_address#mutable
• Data source inclusion/exclusion: tag:-sector.tax tag:sector.energy
• Tabular data / Historical depth: finances.income.table.date#period.P3M#limit.P9M
• Data normalization: personal.marital_status.raw, personal.marital_status.normalized, address#normalized
• Advanced features: autoupdate, certificate
• Singular data (choose one): public_health_insurance.beneficiary
• Plural data (get all): public_health_insurance.beneficiaries

Scope configuration is not an obvious task, please contact us if you need further assistance or in order to setup a workshop with our data consulting team.

Browser compatibility

The compatibility matrix of browsers is very fragmented, but MiTrust has extensive real-world support. You may enquire about a specific user-agent directly to us.

Environments

View the descriptions for sandbox and production environments below.

Mobile integration

There isn't a specific SDK for the integration of Mitrust into iOS or Android but the MiTrust data verification can be used directly within a webbrowser under mobile devices (especially Android and iOS). The recommended way to do it is to launch the mobile's default browser and redirect the EndUser to your mobile application once the SharingFlow is done. It is also possible to embed MiTrust in a webview, although this it is discouraged for security reasons as the users credentials could be maliciously fetched.

Here is some technical documentation about how an external browser can interact with a native application:

https://developer.android.com/training/app-links
https://developer.android.com/guide/components/intents-common#Browser https://developers.facebook.com/docs/facebook-login/security/#surfacearea

About iOS, the typical way would be:

let  safariViewController  =   SFSafariViewController ( url :   "m-itrust.com" )   present ( safariViewController ,  animated :   true ) 

❗️

WKWebView should be avoided as it allows HTML customisation and JS injection
About SSO, once the user account is ready: https://github.com/openid/AppAuth-iOS/issues/120

Server certificate

HTTPS

The MiTrust API will only serve traffic over HTTPS, and will include an HSTS response header in order to let browsers and other client so ware enforce this.

Server certificate

The MiTrust API server certificate should be trusted by all supported browsers, including latest versions of Chrome, Firefox, Edge, and Safari.

If your software uses a custom certificate trust store, and certificate pinning, you will have to trust:

• Let's encrypt trust anchor for SBX platform. More on https://letsencrypt.org/certificates/
• Sectigo's EV trust anchors for PRD platform. More on sectigo.com

Note that MiTrust renew its Let's Encrypt server certificates every 3 months. To avoid unexpected connectivity issues, MiTrust therefore recommends against depending on any part of the server certificate. The trust root is ISRG Root X1, which can be downloaded at the address above.

For production, MiTrust uses EV certificates that are renewed every year. In case of emergency, MiTrust may use a Let's Encrypt certificate in PRD environment, as a degraded mode.

About certificate pinning

🚧

Certificate pinning Let's Encrypt root certificate does not bring security, as anybody is free to generate a certificate with Let'sEncrypt. Hence, if we provided a way to pin a certificate which would not roll every 3 months, please understand this does not provide any safety regarding MiTrust actual legitimacy.

Availability API

You may want to check if a defined set of DataProvider is available to access the required data according to your scope. You can do it by calling the availability endpoint with a GET request corresponding to your environment (SBX or PRD), providing your scope and client_id as parameters.

This API can be used to automatically set up a "downgraded mode" in your UI, in which the MiTrust functionality is hidden, possibly informing the users of the temporary unavailability of the service.

The availability endpoint is described in our API documentation: Get count of available DP. The caller can expect the API to be fast most of the time, but a very occasional delay is expectable.

'https://sbx-app.m-itrust.com/v2/public/dp/statistics?scope='
  +   encodeURIComponent(scope)   
  +   '&client_id='
  +   encodeURIComponent(client_id) 

Example of a request with scope: name adress.formatted#softly_required

curl -X GET "https://sbx-app.m-itrust.com/v2/public/dp/statistics?scope=name%20address.formatted%23softly_required&client_id=myClientId"

will return:

{
  "status": "success",
  "data": {
    "active_dps": 53,
    "client_id": "myClientId",
    "scope": "name address.formatted#softly_required"
  }
}

🚧

This API checks for the availability of Data Sources matching the input scope. As MiTrust exposes a vast number of sources, you should take care of setting a meaningful scope parameter, that mirrors your actual use case. It is of little business value to know that 50 data sources are available for a scope like name if your use case depends on some other scope or claims.

As a general rule, the scope should be the same here than the one you use when calling the /start route of the API.