Treezor Doc

# Introduction

Strong Customer Authentication (SCA) (opens new window) is a European regulatory requirement aiming at reducing fraud and making payments more secure.

As a Treezor client, you are using Treezor's ACPR agreement and must therefore implement SCA into your Users flow by either:

# Key concepts

To ensure a Strong Customer Authentication, we use at least 2 of the following 3 elements:

  • Something the User has (smartphone, hardware token...)
  • Something the User is (fingerprint, facial id)
  • Something the User knows (password, PIN)

SCA can be required in the following scenarios:

  • Per session: When logging-in, the User is required to authenticate with SCA. This allows for some follow up actions without an additional SCA.
  • Per operation: When doing a sensitive operation, the User is required to use SCA to confirm it.

SCA aims to prove that the operation effectively originates from the User by:

  1. Generating a cryptographic signature known as SCA Proof (JWS) of the requested operation on the User's device.
  2. Sending this SCA proof to the Treezor API along with the usual operation request (e.g., creating a Beneficiary).
  3. Checking the received SCA proof by the Treezor API and only allowing the operation if it is legitimate.

Treezor provides a mobile SDK and an abstraction layer to produce these cryptographic signatures.

# Authentication

Previously, all your requests to the Treezor API where made using the same authentication token.

To leverage the SCA mechanism, your requests to the Treezor API will have to be made in the name of each end user, using a distinct authentication token.

To make requests in the name of the end user, you:

  1. Obtain an SCA Proof in the form of a JSON Web Signature(JWS) using the Mobile SDK or WebAuthn on the end user's device.
  2. Provide this SCA Proof and a different grant type when requesting a JWT.
  3. Use this JWT to authenticate all future requests to the Treezor API made in the name of that end user.

Depending on the type of SCA Proof provided, the JWT will contain a trz:sca attribute valued to:

  • false if the provided SCA was of type None.
  • true if any stronger type of authentication was used (Biometry, Passcode, etc.).
Info icon

Information – SCA type other than None required every 180 days

The end user is required to authenticate using a stronger SCA type (Biometry, Passcode, etc.) if no authentication using an SCA type other than None occurred in the last 180 days.

The authentication payload is structured as follows.

# Parameters

Parameter Description
client_id The client_id as per your usual authentication flow.
client_secret The client_secret as per your usual authentication flow.
username The userId or the end user's email, as used in User objects
password A hash to be generated by concatenating userId with client_secret and hashing the string using sha256 i.e., sha256(userId + client_secret).
grant_type Must be set to delegated_end_user.
sca The SCA proof (which can be generated using a type None if a stronger type was used in the last 180 days).

In return, Treezor provides you with a JWT for all subsequent requests to the Treezor API made in the name of that User. It must be placed in the Authorization: Bearer header as described in the Authentication article.

# Typical flow

The following diagram illustrates what is required of your Mobile App and back end to enforce Strong Customer Authentication.

Info icon

Information – The diagram is not exhaustive

For brevity, the diagram doesn't cover:

# Sessions

A session means that the User's requests to the Treezor API are authenticated using a JWT which:

  • Has been obtained with an SCA of type != None (JWT contains a trz:sca attribute valued to true).
  • Is not expired (in practice, this means that it has been obtained in the last 60 minutes as JWT has a 60-minute lifetime)
  • Has been used in the last 5 minutes to make any valid call to the Treezor API.
Note icon

Note – Session expiration after 5 minutes

Even if the JWT itself hasn't expired yet, if it has not been used in the last 5 minutes to call Treezor API the SCA session is considered expired.

If the session has expired, the following error will be returned by the API with an HTTP Status Code 401

# Flows

# Per Operation

When a request to the Treezor API mandates a per-operation SCA:

1. You prepare the necessary API payload for the desired endpoint.

This step is the same as for any endpoint.

2. You sign the payload using the User's private key.

This produces a unique signature (using the SDK or WebAuthn).

3. You send the payload along with the signature to the Treezor API.
  • For requests using GET, DELETE you add the signature as a sca query parameter
  • For requests using PUT, POST you add the signature as a sca body parameter
4. Treezor checks the payload against the provided signature and the User's public key.
  • If the signature is valid, the request is handled by Treezor
  • If the signature is invalid or missing, the request is rejected by Treezor with a 400 Status Code

The signing steps are done using Treezor partner's SDK.

You will provide your Payload to the SDK or WebAuthn along with the desired authentication method (PIN or BIOMETRIC for SDK, or PASSCODE for WebAuthn). In return, the SDK or WebAuthn provides you with the payload's signature. This signed payload is known as SCA proof and takes the form of a JWS (JSON Web Signature).

# Per Session

For other requests to the Treezor API.

1. You request an SCA proof.

This can be done using the SDK or WebAuthn.

2. You provide this SCA proof when authenticating against the Treezor API.
3. Treezor checks the signature.
  • If the signature is valid (SCA type other than None), Treezor returns a JWT ( trz:sca valued to true).
  • If the signature is valid (None SCA type), Treezor returns a JWT (trz:sca valued to false).
  • If the signature is invalid, no JWT is delivered.
4. You authenticate all future requests using the obtained JWT.
Updated on: 7/22/2024, 1:55:11 PM

← Endpoints & Data →