Introduction
Strong Customer Authentication (SCA) is a European regulatory requirement aiming at reducing fraud and making payments more secure.
As a Treezor client, you are using Treezor ACPR agreement and must therefore implement SCA into your Users flow by either:
- Declaring SCA with Treezor services for Treezor endpoints that falls into SCA functional context and/or
- Declaring SCA outside of Treezor services for any sensitive operation made from your back end.
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:
- Generating a cryptographic signature known as SCA Proof (JWS) of the requested operation on the User's device.
- Sending this SCA proof to the Treezor API along with the usual operation request (e.g., creating a Beneficiary).
- 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:
- 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.
- Provide this SCA Proof and a different grant type when requesting a JWT.
- 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 typeNone
.true
if any stronger type of authentication was used (Biometry, Passcode, etc.).
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.
json
{
"grant_type": "delegated_end_user",
"client_id": "string",
"client_secret": "string",
"username": "string",
"password": "string",
"sca": "string"
}
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.
Information – The diagram is not exhaustive
For brevity, the diagram doesn't cover:
- The notion of session expiration
- The necessity of a strong authentication every 180 days
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 atrz:sca
attribute valued totrue
). - 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 – 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
json
{
"errors": [
{
"type": "invalid_request",
"code": "sca_session_expired",
"message": "Your session has expired.",
"docUrl": "string"
}
]
}
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 asca
query parameter - For requests using
PUT
,POST
you add the signature as asca
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.
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 totrue
). - If the signature is valid (
None
SCA type), Treezor returns a JWT (trz:sca
valued tofalse
). - If the signature is invalid, no JWT is delivered.
4. You authenticate all future requests using the obtained JWT.
- Per Session requests will be accepted if the JWT:
- Contains
trz:sca
=true
and - Has been obtained less than 5 minutes ago
- Has been used to make any type of valid request
- Contains
- Per Session requests with 180 days exemption regardless of the
trz:sca
value and inactivity (as long as the JWT itself hasn't expired).