Back to CREATIS's Developer Portal Homepage

OAuth 2 and Strong Customer Authentication Workflows


PSD2 API Developer Portal OAuth 2 and Strong Customer Authentication Workflows

The Payment Services Directive 2015/2366 (PSD2) and the related RTSs have extensive requirements concerning the conditions under which financial data regarding a payment service user (PSU) can be shown.

We have chosen to implement these requirements by following the framework produced by the STET working group, available on its website.

The logic and implementation of these workflows heavily references the OAuth 2 framework workflows and vocabulary, specified in RFC 6749.

General Principles for Strong Customer Authentication

In order to proceed with Strong Customer Authentication, we universally rely on a redirect workflow, known as the OAuth 2 Authorization Code workflow:

  • The Third Party Payment Service Provider (TPP) is given a URL of an OAuth 2 authorization endpoint hosted by the Account Servicing Payment Service Provider (ASPSP);
  • The TPP fills URL query string parameters for the authorization endpoint, according to the specification;
  • The TPP instructs the Payment Service User (PSU) to visit the parametrized URL. The TPP must ensure, to its satisfaction, the PSU's identity before giving him the URL - in particular, it should use the OAuth 2 state parameter to bind the PSU's browser context with a given transaction, to protect against attacks where a nefarious party transmits the filled redirection endpoint URL to a third party;
  • The PSU performs the Strong Customer Authentication process on the ASPSP website:
    • The PSU is shown a page that asks them whether they agree to grant the TPP access to their data, or to allow an operation initiated by the TPP;
    • If the PSU agrees, they will be asked to authenticate strongly, in order to ensure the safety of the agreement process;
  • Whether the PSU agrees or not, they will eventually be redirected to the TPP's redirection endpoint, using the standard OAuth 2 authorization response parameters;
    • In case the PSU has agreed, the TPP will be given an OAuth 2 authorization code, to be used with the OAuth 2 token endpoint described on the OAuth 2 endpoints page to get an access token;
    • In case of an error, or if the PSU did not agree, the TPP will be given an error code and a message describing the cause of the error. That message is a technical message, and should not be shown to the PSU on the TPP UI.
OAuth 2 Authorization Code Workflow

In order to obtain an OAuth 2 Client ID, the TPP must complete the registration process.

Account Information Service Providers (AISP)

Getting access to the PSU's data

In order for Account Information Service Providers to access a PSU's banking data at CREATIS, the user must agree to authorize access to their data by the Third Party Account Information Service Provider, and that agreement must be registered by the ASPSP, CREATIS.

That authorization process takes the form of an OAuth 2 Authorization Code workflow, with the following implementation specificities:

Once that process is completed successfully, the TPP will be given an authorization code, which they will be able to use to obtain both an initial access token and a refresh token.

Getting new access tokens without an SCA

In order for the TPP to get new access tokens without requiring the PSU to go through an SCA process, the TPP can use the refresh token provided at the end of the authorization code workflow to obtain a new access token.

Access tokens obtained in this way only provide access to information for which an SCA is not necessary.

Scopes

The following scopes are supported for AISPs:

  • aisp
  • aisp extended_transaction_history

The first scope gives access to the PSU's recent transaction history and account information, while the second scope is necessary to get a transaction history beyond the 90 days for which the AISP can be exempted from a renewal of Strong Customer Authentication.

It should be noted that:

  • Both scopes can be used for Authorization Requests;
  • Both scopes can be set on Access Tokens issued from an OAuth 2 authorization code;
  • Only the first scope can be set on Access Tokens issued from an OAuth 2 refresh token;

SCA Expiration and renewal

When CREATIS considers that the SCA that was done on the user must be renewed, the refresh token will automatically expire and requests to get new access tokens from it will return an invalid_grant error.

In that case, the TPP must ask the PSU to renew their grant of access, by instructing the PSU to visit the OAuth 2 authorization endpoint.

The TPP must be aware that an invalid_grant return value may also mean that the PSU revoked their grant using the ASPSP's user interfaces.

Payment Initiation Service Proivders (PISP)

Getting an access token for Payment Initiation

In order to use the API endpoints for payment initiation, an OAuth 2 access token must be presented to the API. That token is obtained by making a Client Credentials Access Token Request on the OAuth 2 Token Endpoint.

The only valid value for the scope parameter in that request is pisp. Setting it in the request body is optional.

Payment Initiation Workflows

Note: These workflows do not describe the case where the payment is under an exemption from Strong Customer Authentication. In that case the payment will be executed when the Payment Initiation Request is made.

Target Payment Initiation Workflow

It should be noted that the current section is a work in progress:

  • The Payment Initiation Request workflow specified by versions 1.4.1 and 1.4.2 of the STET PSD 2 API Specification (on which this document is based) suffers from known security issues that make it unfit for production usage;
  • As of March 2019, work is still ongoing in the STET PSD 2 API Working Groups to determine precisely how these issues will be solved;

This section presents a workflow that is, to the best of our knowledge, in line with the solutions that the STET PSD 2 API Working Groups are working on and will produce in the near future.

This section will be updated when the specification is updated.

The target payment initiation workflow is an OAuth 2 Authorization Code workflow, with the following implementation specifics:

  • The Authorization Endpoint URL will be returned in the response to a Payment Initiation Request on the API;
  • The use of the OAuth 2 PKCE extension is mandatory, with the SHA-256 method;
Payment Initiation Target Workflow

Currently implemented Payment Initiation Workflow

The currently implemented Payment Initiation Workflow is a modified version of the REDIRECT Payment Workflow specified in the STET PSD 2 API, version 1.4.1, with the following specificities:

  • The payment will not be initiated while the PSU is visiting the ASPSP website;
  • The TPP redirection endpoint will receive a query string parameter, to be sent back in the payment request confirmation endpoint;

Compared to the target workflow, there are the following differences:

  • The target workflow is based on OAuth 2, the current workflow is not:
    • The URL to be visited by the user is not an OAuth 2 redirection endpoint;
    • There is no OAuth 2 authorization code nor access token - instead, a psuAuthenticationFactor parameter is transmitted in the query string, and must be forwarded in the confirmation request body;
Payment Initiation Current Workflow

Payment Request Cancellation Workflows

In order to cancel a payment request, an SCA will generally be required. The workflow is the same as for payment initiation, with the exception that it begins with a payment request cancellation (with a HTTP PUT on the payment URL) instead of a payment request initiation.

Card-Based Payment Instrument Issuers (CBPII)

Support for CBPII by CREATIS uses exactly the same workflows as the AISP case, with the following modifications:

  • The scope for CBPII is cbpii - this scope can be set on Access Tokens issued from an OAuth 2 authorization code, or from an OAuth 2 refresh token;

A CBPII cannot use an OAuth 2 Client Credentials workflow to obtain an OAuth 2 access token.