Updating authentication

Description

There are several cases an authentication update is necessary:

User credential update requested by the bank.
The PSD2 API token expired and need to be renewed
One-time password strong authentication requested by the bank

To be notified of theses requests, you need to check the statuses of the connection, updated during the last synchronization, or retrieve the events containing these information.

Events are generated in order to be able to follow the evolution of the various asynchronous processes. These events will contain several pieces of information like status which allow the client to be aware of various actions to be taken. Events are obtained by subscribing to a queue.

The 'HowTo' Using Queues explains how to manage these queues and events.

Environment

The widget usually allows to create a connection and start a synchronization. Bank accounts can be recovered using 2 types of connection:

The banks' PSD2 API for checking and credit card accounts: we are redirected to the bank's site (OAuth2 redirect),
The scraping flow (historical flow) for other accounts (savings, credit, investment) or current accounts if PSD2 API is not available: A form is generated to request the user's password to log in on their behalf.

The PSD2 directive imposes a strong customer authentication (SCA) on the first connection and every 90 days (credentials expiration). SCA is a requirement of PSD2 on payment service providers within the European Economic Area. The requirement ensures that electronic payments are performed with multi-factor authentication.

It may also be necessary to renew these passwords following requests from the bank to continue to access the accounts. A user action is therefore required and password change requests must be detected in order to be able to redirect the user to a new authentication path.

It is also possible to manage the authentication updates directly with the API. This is described in a dedicated chapter in the Advanced API integration page.

Credentials management

Credentials lifecycle

In the Linxo Connect environment, a bank connection has 2 types of none exclusive channels allowing to separate the 2 flows:

EMBEDDED: corresponding to the 'scraping' type connection
REDIRECT: corresponding to the DSP2 API type connection

The connection object contains a list of structures named channels that contains necessary information for you to know if your user needs to interact with the credentials. The related fields are:

channel_definition_id that represents uniquely the channel definition in the provider
status that provides a new status for this channel only
expires that optionally provides the date the actual credential value has to be renewed

Leaving a channel in a failure state leads to a break in the data sync. On a REDIRECT channel, credential expiration can be prevented by renewing the authentication before the expiration date. This is made by using the expires property of the channel in the connection resource. One can decide to make its user renew the credentials one month before its expiration or send a notification when something goes wrong indicating what to do.

Given these information and the global connection status that remains available, a client can track its users connections and make decisions:

You therefore analyze the statuses of the connection and the associated channels reported by the events.
You notify the user of the action to be performed
You call the edit_credential entry point of the widget to modify the user's credentials

Each channel is associated to credentials and synchronization jobs that have statuses to manage. Some statuses requires a user action and it might be interesting to watch the following ones in this context:

Updating the credentials
- TOKEN_EXPIRED: The PSD2 API token expired. The user must re-authenticate to restore the channel synchronization.
- PASSWORD_CHANGE_REQUIRED: Last channel synchronization failed because the provider requires the user to change his password.
- AUTH_FAILED: Authentication failed during last channel synchronization.
- TOO_MANY_ATTEMPTS: Authentication failed several times in a row. Channel synchronization is suspended until the user re-authenticates.
Synchronizing the connection
- CHALLENGE_REQUIRED: Last channel synchronization failed because the provider required a challenge (by SMS, mail, etc.).
- CHALLENGE_TIMED_OUT: Last channel synchronization failed because the user did not answer the challenge in the allowed time.
- CHALLENGE_FAILED: Last channel synchronization failed because the user responded incorrectly to the challenge.
- CHALLENGE_CANCELLED: Last channel synchronization failed because the user cancelled the challenge.
Asking the user to perform an action on the provider website:
- USER_ACTION_REQUIRED: Last channel synchronization failed because the provider requires the user to fulfill an action (accepting new terms and conditions, filling a form, etc).

Example: Fetch status for a specific connection:

#
curl -s {baseUrl}/v2.1/connections/18903
      -H "authorization: Bearer {access_token}"
{
  "id" : "18903",
  "provider_id" : "182",
  "name" : "Demo Bank",
  "status" : "FAILED",
  "creation_date" : 1562233721,
  "auto_sync" : true,
  "logo_url" : "https://static.linxo-connect.io/common/pictures/providers_logos/182.png",
  "channels" : [ {
    "channel_definition_id" : "17650",
    "mode" : "EMBEDDED",
    "status" : "AUTH_FAILED",
    "last_success_date" : 1562233742,
    "last_end_date" : 1562233742,
    "credentials" : [ {
      "id" : "10001",
      "masked_value" : "**mo"
    } ],
    "account_types" : [ "CHECKINGS", "SAVINGS", "LOAN", "CREDIT_CARD" ]
  } ],
  "owner" : {
    "name" : "Mr Test",
    "address" : "address test",
    "birth_date" : 1562233742,
    "birth_place" : "birth place test",
    "phone_number" : "06******1"
  }
}

In this example, the connection is in FAILED status because its only channel is in AUTH_FAILED status. To fix the issue and restore the link with the bank, the user needs to update its password using an embedded form.

Edit credentials

The edit connection flow allows a user to edit an existing connection and update its credentials. The service will update the connection data in the database and try to reach the provider if the credentials are updated.

The client can provide some parameters to customize the screen flow and he is notified of the results by a callback URL.

These screens require an active Webview service session, the Webview service will immediately redirect to the redirect_uri with a result of "expired" if the session is expired.

These scopes are needed for the user Access Token: accounts_manage transactions_read connections_manage connections_sync

The reference documentation describes the Edit credentials API endpoint parameters.

Request examples:

# Update the channel that handles savings accounts for the connection#84
 
curl https://{widget_uri}/widget/edit_credentials?session_id=4242XXX
      &redirect_uri=https://mywebsite.coom/callback%26channel_definition_id=EMBEDDED1
      %26provider_id=42%26connection_id=84
 
# Add the channel tat handles payment accounts for the connection#85,
# aggregate asynchronously and select accounts
 
curl https://{widget_uri}/widget/edit_credentials?session_id=4242XXX
      &redirect_uri=https://mywebsite.coom/callback%26
      channel_definition_id=REDIRECT1%26provider_id=42%26connection_id=85%26
      captive_mode=true%26select_accounts=true

Response examples:

# Success case, the user will be redirect on
{callback_uri}?result=edited&status=success&connection_id=42

# Expired case, the user will be redirect on
{callback_uri}?result=expired

# Cancelled case, the user will be redirect on
{callback_uri}?result=cancelled

Strong authentication

The widget allows you to build the form making it possible to enter challenges.

These scopes are needed for the user Access Token: accounts_manage transactions_read connections_manage connections_sync

The reference documentation describes the User input API endpoint parameters.

Request example:

# Given the following challenge event
{
  "id":"14",
  "event_type":"LIST_ACCOUNTS_USER_INPUT_REQUESTED",
  "resource_type":"CONNECTION",
  "creation_date":1528199358,
  "channel_definition_id":"embedded1",
  "resource":{
    "id":"17730",
    "provider_id":"87",
    "name":"Test Bank",
    "status":"SUCCESS",
    "channels": [
      {
        "id": "redirect1",
        "expires": 1528106353
        "status": "SUCCESS"
      },
      {
        "id": "embedded1",
        "status": "RUNNING"
      }
    ],
    "creation_date":0,
    "last_success_date":1528199340,
    "last_end_date":1528199340
  },
  "list_accounts_user_input_requested":{
    "challenge":[
      {
        "id":"303",
        "label":"La connexion à Banque demande la saisie d’un code envoyé par SMS sur votre téléphone au {phone}. Souhaitez vous recevoir ce code maintenant ?",
        "regexp":".*",
        "type":"INFO_MSG",
        "encrypt":false,
        "params":{
          "phone":"0606060606"
        }
      },
      {
        "id":"304",
        "label":"Envoyer le SMS",
        "regexp":".*",
        "type":"OK_CANCEL",
        "encrypt":false
      }
    ]
  }
}

# Call /widget/user_input with challenge_ids (id of each object in challenge array) and parameters (key=value in object params for each challenge)

curl https://{widget_uri}/widget/user_input?session_id=4242XXX&channel_definition_id=embedded1&provider_id=87&connection_id=17730&challenge_ids=303,304&phone=0606060606&redirect_uri=https%3A%2F%2Fmywebsite.com%2Fcallback

Response examples:

The results are added as query string parameters to the redirection URL provided when creating a session or displaying the widget

# Success case, the user will be redirect on
{callback_uri}?result=success&status=success&connection_id=17730&queue_id=4242XX&channel_definition_id=embedded1

# Expired case, the user will be redirect on
{callback_uri}?result=expired

# Cancelled case, the user will be redirect on
{callback_uri}?result=cancelled

Description​

Environment​

Credentials management​

Credentials lifecycle​

Edit credentials​