Documentation

Headless and Autoupdate

What is AutoUpdate

AutoUpdate is a MiTrust feature that allows a Service Provider to set up the synchronization of an End User's Sharing Data, automatically (without user interaction) and periodically, from the same Data Provider. AutoUpdate requires an "initial" (classic) transaction to set up, and then allows "ulterior" (headless) transactions to happen.

The initial transaction generates an AutoUpdate Token as part of the collection of Sharing Data, which is entrusted to the Service Provider and enables the execution of a subsequent transaction.

The AutoUpdate token

The AutoUpdate Token is a cryptographically secured token that contains all required information to replay the original transaction.

The token's full content can only be decrypted by MiTrust, although part of it is freely readable from its JWT structure

As such, the token refers to data from the original transaction :

  • The Sharing Flow ID and date
  • Its scope
  • The identifier for the user-chosen Data Provider and related authentication material
  • The description of the selected Sharing Data

Activating AutoUpdate in the original transaction

For a Sharing Flow to activate AutoUpdate, the flow's scope parameter should :

  1. contain the certificate scope fragment
  2. contain one or more claims with the #invariant marker
  3. contain one or more claims with the #mutable marker

When those conditions are met, the MiTrust application will provide tuned consent messages so that the End User adequately consents to the further synchronizations, and will return the AutoUpdate Token as part of the user info collection.

Invariant and mutable claims

The claims marked as #invariant will be used in subsequent AutoUpdate flows to identify the original End User's profile. As the name implies, it should be some piece of data from the Sharing Data that will not change from one flow to the next, and can uniquely identify the user's profile over time.

The claims marked as #mutable are the ones for which synchronization is requested. Only the #mutable claims will be returned in the AutoUpdate transaction.

Autoupdate functional goal

The AutoUpdate process' functional goal is to replay the original Sharing Flow's transaction, retrieving data from the same Data Source, and return the #mutable data that relate to the same #invariant data.

Importance of the scope in AutoUpdate

It is important to consider that the scope of the original transaction is sealed in the token, and with it, the End User's consent for accessing specific data points, from a specific Data Source, share the relevant ones in the original transaction, and the #mutable ones in the following transactions.

Therefore, as a Service Provider, you may not access any other data than the #mutable originally consented to, nor from any other profile than the one as determined by the #invariant.

The various functional rules pertaining to user consent management are outlined in the Integration guidelines for Autoupdate page.

Performing an Autoupdate Sharing Flow

As highlighted above, performing an Autoupdate sharing-flow requires having an AutoUpdate Token from a previous normal Sharing Flow.

The outline for performing an AutoUpdate flow is :

  1. Authenticate to gain access to the headless API, via a Bearer access_token
  2. Combine your access_token with the autoupdate_token to start a Headless session
  3. Poll the headless_session status periodically
  4. Fetch the End User data from the headless_session
  5. Terminate the headless_session.
📘

What's Headless?

Headless is a mode of operation of MiTrust in which no End User interaction is required. As such, a flow performed in headless mode has no User Interface, hence, its headless name.

Generate an access token

To authenticate to the headless APIs, the Service Provider shall request a "clients credentials" access token through a POST request with BASIC authentication and a grant_type=client_credentials.

See our postman example: Generate an access_token for Headless transaction

{  
  "body": { 
    "grant_type": "client_credentials", 
    "scope": "headless" 
  }, 
  "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" 
}

The response of this POST would look like:

{ 
  "access_token": "client_credentials_access_token", 
  "expires_in": 3599, 
  "jti": "DXrWeEKW2nJ_xDW9yqQWutcRysM", 
  "scope": "headless", 
  "token_type": "bearer" 
}

The content of the access_token key will be referred to as the access_token.

📘

Using a scope of headless is sufficient is most standard use cases for Autoupdate. However, some advanced use case, such as collection the MiTrust Certificate in an Autoupdate session, may require a more advanced scope when collecting the user_info. This will be explained in a further paragraph.

Start a headless session

The Headless Session represents an actual transaction, and is similar to a Sharing Flow

The way to start a Headless Session is to make a POST request with your previously created access_token and AutoUpdate Token :

{ 
  "headers": {
    "Authorization": "Bearer access_token", 
    "headless_token": "autoupdate_token"
  }, 
  "method": "POST",
  "url": "https://sbx-app.m-itrust.com/v2/sp/headless/"
}

If the AutoUpdate Token size is greater than 64kB, you should send it in the HTTP body, instead of the header :

{ 
  "headers": {
    "Authorization": "Bearer 'client_credentials_access_token'"
  }, 
  "method": "POST", 
  "payload": {
    "headless_token": "headless_token"
  },
  "url": "https://sbx-app.m-itrust.com/v2/sp/headless/" 
}

The response of this POST will return to you a Headless Session token:

{ 
  "data": {
    "headless_session": "headless_session",
    "sharing_flow_id": "2c2c05e4-cc02-4f7b-a42f-4787cc44827f"
  },
  "status": "success"
}

See our postman example: Postman Fetch headless_session token

Poll the Headless Session's status

Once the Headless Session is started, MiTrust shall be polled to check the sessions's status.

{ 
  "headers": {
    "Authorization": "Bearer access_token", 
    "headless_session": "headless_session"
  }, 
  "method": "GET",
  "url": "https://sbx-app.m-itrust.com/v2/sp/headless/"
}

Polling shall be done until the session's status is completed.

The HTTP response code could be:

  • HTTP 429 (Too many requests), in case your application polls MiTrust API too aggressively. This error is not permanent, and the call should be retried after a short delay (e.g. a few seconds). You should consider reducing the polling-rate of your application.

    • Header x-ms-retry-after-ms: The number of milliseconds to wait to retry the operation after an initial operation received HTTP status code 429 and was throttled. This value is informative only, as any number of calls could pass or fail between the calculation and the expiration of the retry delay.

  • HTTP 200 (OK) with one of the following status messages in the response body:

    • ongoing: continue polling every N seconds,

    • completed: the user info will be available at userinfo entrypoint,

    • failed: the status failed is associated with a reason. Possible reasons are:

      • login: Issue with the login: (invalid input, MFA, ...).
      • profile_not_found: Issue with profiles: there is not a single profile matching the initial transaction's invariants.
      • profile_ambiguity: Issue with profiles: there is multiple profiles matching the invariants of the initial transaction.
      • dp_user_action_required: The data retrieval could not be completed, because the Data Provider requires an explicit user interaction that MiTrust can not perform on its behalf. It is generally related to a major update of the Data Provider's terms of services.
      • dp_unavailable: The Data Provider is encountering a planned or unplanned unavailability period. The failure is most likely transient and the process could be retried in a few hours or days.
      • internal: Issue within the platform.

See our postman example: Postman PollBackend for response

Fetching the user information

To collect user information of a completed session, the endpoint is https://sbx-app.m-itrust.com/user_data/v1/userinfo using the access_token (see here) and the headless_session.

{
  "Headers": {
    "Authorization": "Bearer access_token", 
    "headless_session": "headless_session" 
  }
}
🚧

Warning

Some elements of the userinfo response are not part of the User Data, but are post-processed and generated at the time of calling userinfo.

This include most notably the use of the MiTrust Certificate with the certificate scope fragment, and the computation of #normalized attributes (from the address or postal_address claims).

As a consequence, if you expect the MiTrust certificate or the #normalized data points to be present in an Headless Session's response, the access_token used to perform the userinfo collection MUST have been created with the proper scope fragments in the scope attribute at step 1, such as certificate.

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

{
  "data": {
    "user_consent": {
      "jwe": "encryptedUserConsent"
    },  
    "user_info": {
      "address": {
        "locality": "Paris"
      },
      "name": "John DOE"
    },
    "certificate": {
      "file_wrapper": {
        "filename": "mitrust_certificate.pdf",
        "base64": "JVBERi0xLjYKJfb... suite du certificat (PDF en base64)"
      }
    }
  },  
  "message": " some message ", 
  "status": "success"
}

See our postman example: Postman Get userInfo For AutoUpdate

Delete the session

Once completed, you should acknowledge to good reception of data by systematically deleting the headless_session. See our postman example: Postman DELETE headless session

{ 
  "headers": {
    "Authorization": "Bearer 'client_credentials_access_token'", 
    "headless_session": "headless_session"
  },
  "method": "DELETE",
  "url": "https://sbx-app.m-itrust.com/v2/sp/headless/" 
}

AutoUpdate Token expiration and refresh

AutoUpdate token expire after a variable amount of time (usually around 90 days, but the actual duration may vary based on other technical constraints). During that period, you may refresh the token at any point in time, pushing back the expiry further in time (usually, for another 90 days). After 24 months though, it is not possible to refresh a token anymore.

📘

Checking the expiration date

We recommend that you actively check the expiration of your tokens, and renew them in a timely manner, e.g. every 60 days for a 90 days expiration delay, by making a speficic call with your token, so that its expiry is reset long before expiration.

You may want to check the final date of expiration (24 months limit). It is encoded into the AutoUpdate Token, by parsing the refresh_token claim as a JWS object, and looking at its exp claim.

To refresh a token, you should POST it to the appropriate route, using a valid access_token :

{ 
  "headers": { 
    "Authorization": "Bearer 'client_credentials_access_token'", 
    "headless_token": "old_autoupdate_token" 
  }, 
  "method": "POST", 
  "url": "https://sbx-app.m-itrust.com/v2/sp/autoupdate" 
}

The response of this call will return:

{ 
  "date": {
    "autoupdate": { 
      "access_token_wrapper": { 
        "access_token": "renewed_autoupdate_token",
        "expires_in": 7776000, 
        "links": [ 
          { 
            "href": "https://sbx-app.m-itrust.com/v2/sp/headless", 
            "rel": "self" 
          } 
        ], 
        "token_type": "headless" 
      }
    }
  },  
  "status": "success"
}

Headless

Headless mode is a generic mode of operation of MiTrust that allows the use of MiTrust without a End User in the loop, and without a User Interface.

Data can be fetched in Headless mode (without a graphical user interface) in two situations:

  • When no end user credentials are required: a lot of corporate data is publicly available (ex. : registration certificates from Infogreffe.fr),
  • When end user credentials were previously provided with user consent: they are encrypted in an AutoUpdate Token, as already seen above.

In both cases, an encrypted token has to be provided in order to initiate the transaction : a Headless Token in pure headless mode, or a Autoupdate Token, as already mentioned.

Headless operate in a very similar fashion to AutoUpdate, the main difference being the means by which the token shall be created.

Generate a "headless" token

A Headless transaction requires an access_token with proper scope, and a Headless Token,

The access_token can be obtained in a similar fashion than in AutoUpdate, with an adequate scope pertaining to the data needing retrieval.

Then, the Headless Token (which is equivalent to an AutoUpdate Token), is generated by combining business-specific inputs with the access_token.

See our postman example: Postman Generate Headless Token Example

{ 
  "body": { 
    "company.country": "FR", 
    "company.registration_number": "SIREN Number" 
  }, 
  "headers": { 
    "Authorization": "Bearer 'client_credentials_access_token'", 
    "type": "application/json" 
  }, 
  "method": "POST", 
  "url": "https://sbx-app.m-itrust.com/v2/sp/headless/company" 
}

This will return a Headless Token, which has an expiry limited to 90 days, and can be used to start multiple sessions (e.g. fetch multiple KBIS)

{ 
  "data": {
    "access_token_wrapper": { 
      "access_token": "eyJhbGciOi[....]", 
      "expires_in": 3600, 
      "links": [ 
        { 
          "href": "https://sbx-app.m-itrust.com/v2/sp/headless", 
          "rel": "self" 
        } 
      ],  
      "token_type": "headless_token" 
    }
  },  
  "status": "success" 
}

Updated 4 days ago