Introduction

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

Because you're using Treezor ACPR agreement, you must implement SCA into your user flow by declaring SCA either:

• With Treezor services for Treezor endpoints falling into SCA functional context and/or
• Outside Treezor services for any sensitive operation made from your back end.

Key concepts

A defined set of user actions requires Strong Customer Authentication, either by session or by operation.

Context	Description
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, even if they already went through strong authentication when logging-in.

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 identification)
• Something the User knows (password, PIN)

In a nutshell, 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 operation if legitimate.

Treezor relies on a digital safe containing a private key necessary for Strong Customer Authentication: the SCA Wallet object.

SCA authentication flow

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

Information – The diagram is not exhaustive, it doesn't cover:

• The notion of session expiration
• The necessity of a strong authentication every 180 days

Per Session authentication main steps

For other requests to the Treezor API.

1. You request an SCA proof.

This can be done using the SDK or Web Native solution.

2. You provide the SCA proof when authenticating against the Treezor API.

The SCA proof is passed as a header parameter of your authentication request.

3. Treezor checks the signature.

Signature	SCA type	Treezor returns
Valid	Other than None	Treezor returns a JWT (trz:sca valued to true)
Valid	None	Treezor returns a JWT (trz:sca valued to false).
Invalid	N/A	N/A, 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
• Per Session requests with 180 days exemption regardless of the trz:sca value and inactivity (as long as the JWT itself hasn't expired).

Per Operation authentication main steps

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 Web Native).

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

SCA solutions

Treezor offers mobile and web native solutions for you to produce the cryptographic signatures necessary for Strong Customer Authentication:

Solution	Description
Mobile Abstraction Layer	React abstraction layer wrapping the Mobile SDK.
Mobile Flutter Bridge	Bridge exposing the same methods and interfaces as the Mobile SDK, in Flutter.
Mobile SDK	SDK providing SCA wallet functionality, device eligibility checks, and cryptographic signature generation for strong authentication.
Web Native	Solution to generate SCA proofs within a web browser for use cases without a mobile app.

Mobile Abstraction Layer

Treezor provides a React abstraction layer that lives above the Mobile SDK. This wrapper allows you to implement SCA features more easily than via the SDK directly.

Prerequisites:

• Import react-native-treezor-sca using credentials provided by Treezor.
• Import bridge-reactNative-{version} provided to you encrypted using GPG.
• Using npm install -S {package} or yarn add {package}.

Learn more in the dedicated Mobile Abstraction Layer article.

Mobile Flutter Bridge

Treezor provides a Flutter bridge which exposes the same methods and interfaces as the Mobile SDK, in Flutter.

To use it you have to specify the following dependency in your pubspec.yaml.

YAML

dependencies:
  endtrust_bridge_flutter:
	path: path_to_the_bridge_folder

The bridge will be provided to you as a ZIP archive.

Android Bridge Configuration

Add the following to android/app/build.gradle

JSON

android {
	[...]

	defaultConfig {
		[...]
		minSdkVersion 21
	}
	
	packagingOptions {
		jniLibs {
			keepDebugSymbols += "*/*/libscm.so"
			useLegacyPackaging = true
		}
	}
}

Metadata

Add the following metadata to android/app/src/main/AndroidManifest.xml

XML

<meta-data
  android:name="fr.antelop.application_id"
  android:value="\4713640103500149457" />
<meta-data
  android:name="fr.antelop.issuer_id"
  android:value="treezor" />

Permissions

Add the following permissions to android/app/src/main/AndroidManifest.xml

XML

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.USE_BIOMETRIC" />

Mobile SDK

All the SDK features are provided through an SCA Wallet object implemented in the SDK itself. It can be seen as a base layer, gathering configuration and security settings on which Strong Customer Authentication relies.

SCA Wallets are synchronized between the mobile device and Treezor back end.

The main property of the SCA wallet is its state, evolving from actions triggered on the back end or on hosting app side, and defining how an SCA Wallet is accessible to the hosting app.

Requirements for mobile compatibility on your end users side

Android

• Minimum supported version – Android 5.0 Lollipop (API level 21)
• Target version – Tested with Android versions until Android 13 (API level 33)

iOS

• Minimum supported version – iOS 11
• Minimum supported version for pushing a Card to Apple Pay – iOS 13.4
• Swift 5

Learn more in the dedicated Mobile SDK article.

Download SDK

Sandbox

Production

Web Native

Web-only banking scenarios can't rely on mobile app SDK for cryptography and signing. Instead, you can use the web native solution to generate SCA proofs within a web browser.

Treezor built its web-native technology by relying on the Web Authentication standard (WebAuthn). It leverages public key cryptography for user authentication, achieving a security level comparable to native apps.

WebAuthn addresses the SCA elements as follows.

Element	Description
Passkey	Represents “something the user has”.
Passcode	Represents “something the user knows”. The passcode is unique by user for all their devices, and is encrypted on the user's device before transmission to Treezor.

Why is the passcode necessary?

You might wonder why Treezor requires the passcode, when a smartphone might already mandate biometry to unlock the passkeys, satisfying both “something the user has” and “something the user is”.

Although the conditions may be satisfied in this very situation, due to the multiplicity of authenticators supported by WebAuthn the passkeys may be accessed with or without biometry.

Therefore, to be SCA-compliant with every WebAuthn authenticator, Treezor requires the encrypted passcode in addition to the WebAuthn generated signature.

Note – Authentication type = None only applies to the SDK.

When using Web Native, the authentication is always stronger than None as we use “something the user has” (trusted browser/device) and require “something the user knows” (passcode).

Requirements

Web Authentication API usage requires hardware capabilities to handle cryptographic operations and keys. Unauthorized access protection can be ensured using either:

• A Trusted Execution Environment (TEE) or
• A Trusted Platform Module (TPM)

TEEs and TPMs are available on modern computers and smartphones. They can also be found in dedicated roaming hardware authenticators.

When first generating their passkey, the browser prompts the User to select a storage location. The passkey storage location depends on the device capabilities and how the WebAuthn API is called. They can be one of the following:

The device itself

Requires the device to possess necessary cryptographic capabilities (TEE, TPM, or other hardware-based security features).

Roaming hardware authenticators

Such as YubiKey, SoloKey, or Google Titan for instance.

Smartphones

Utilizing a QR code displayed during the Web Native enrollment process, a smartphone can scan the code to assist in the key pair generation and storage process.

This last method leverages the smartphone security features to extend Web Native reach beyond the first two options. The smartphone can either store the key pair or assist in the authentication process by verifying the user's identity before the key pair is generated, stored, or accessed securely. Both the computer and the smartphone must have Bluetooth enabled and be connected to the internet (although they do not necessarily need to be on the same network).

Reading – Matrix of device support

A comprehensive matrix detailing device support and key pair synchronization features is available at https://passkeys.dev/device-support/, offering developers insight into the wide array of compatible devices and their specific capabilities.

SCA Wallet object

An SCA Wallet is the secure enclave locally present on a device. Please note that this is an example of SCA Wallet object, and that some attributes such as the activationCode are only valorized when relevant.

JSON

{
	"id": "1a73b1eca9a64cf19a448b61dd494d15",
	"status": "CREATED",
	"subStatus": "CREATED_READY",
	"passcodeStatus": "NOT_SET",
	"locked": false,
	"lockReasons": [],
	"lockMessage": null,
	"settingsProfile": "default",
	"mobileWallet": {
		"pushMessagingId": "c9wB0BakTaakW9vwtDIyl_:APA91bH-0-ArJEbYdV9s8m-6332wXfvO1DLYeoZzkkqasU3s-1893KdLarFdM7dJBHsb22H4lOFI4Xr_PzE9bFS2w",
		"productModel": "SM-A415F",
		"os": "ANDROID",
		"deviceIdType": "ANDROID_ID",
		"secretFingerprint": "0x83ec6a38e8cd9f12bc1ed89e771ca402048959e738943dAAAAAAAA",
		"lastEligibilityCheck": "2023-11-15T10:04:50Z",
		"nfc": true,
		"deviceId": "c2032a73ac90de11",
		"appBuildNumber": "v04-04-06-06-02-02",
		"productFingerprint": "samsung/a41eea/a41:12/SP1A.210812.016/A415FXX123456:user/release-keys",
		"mobileUpdateDate": "2023-11-15T10:04:50Z",
		"appleTeamId": null,
		"emulator": false,
		"pushMessagingProvider": "FIREBASE",
		"osVersion": "12",
		"root": "0",
		"sdkVersion": "2.4.11",
		"brand": "samsung"
	},
	"activationCode": null,
	"creationDate": "2023-07-13T15:29:05+02:00",
	"deletionDate": null,
	"activationCodeExpiryDate": "2023-07-13T15:49:05+02:00",
	"authenticationMethods": [
		{
			"type": "DEVICE_BIOMETRIC",
			"usages": [
				"STRONG_CUSTOMER_AUTHENTICATION"
			],
			"parameters": {
				"validityDuration": 60
			}
		},
		{
			"type": "HYBRID_PIN",
			"usages": [
				"WALLET_MANAGEMENT",
				"STRONG_CUSTOMER_AUTHENTICATION"
			],
			"parameters": {
				"maxAttempts": 3,
				"validityDuration": 60
			}
		},
		{
			"type": "NONE",
			"usages": [
				"STRONG_CUSTOMER_AUTHENTICATION"
			],
			"parameters": []
		},
		{
			"type": "CLOUD_PIN",
			"usages": [
				"WALLET_MANAGEMENT",
				"STRONG_CUSTOMER_AUTHENTICATION"
			],
			"parameters": {
				"maxAttempts": 3,
				"validityDuration": 60
			}
		}
	],
	"invalidActivationAttempts": null,
	"userId": "3400118",
	"scaWalletTag": "Iphone 13 mini",
	"clientId": "string",
	"activationDate": "2023-07-15T15:29:05+02:00"
}

Key attributes

Status (status)

Status	Description
CREATING	SCA Wallet is being created
CREATED	SCA Wallet has been created, but has not yet been initialized
INITIALIZING	SCA Wallet is being initialized
ACTIVE	SCA Wallet has been initialized and is not locked or deleted
DELETED	SCA Wallet has been deleted by issuer

Sub Status (subStatus)

Sub Status	Description
CREATING_IN_PROGRESS	SCA Wallet is being created
CREATED_BLOCKED	SCA Wallet created but may not be used yet
CREATED_READY	SCA Wallet created that can be used
INITIALIZING_MOBILE	SCA Wallet is being initializing by the mobile
ACTIVATED_LOGGED_IN	User is logged in
ACTIVATED_LOGGED_OUT	User is logged out
DELETED_BY_ISSUER	SCA Wallet has been deleted by the issuer
DELETED_UNINSTALLED	SCA Wallet has been deleted because the SCA wallet has been uninstalled

Passcode Status (passcodeStatus)

Passcode Status	Description
SET	Passcode was set by the customer
NOT_SET	Passcode was not set by the customer
TO_BE_CHANGED	Passcode has to be changed
NONE	None

Locking Reasons (lockReason)

Lock Reason	Description
ISSUER	You locked the SCA Wallet (generic lock reason)
LOST_DEVICE	End User declared a lost device
STOLEN_DEVICE	End User declared a stolen device
FRAUDULENT_USE_SUSPECTED_BY_ISSUER	You suspected a fraudulent use of the SCA Wallet
FRAUDULENT_USE_SUSPECTED_BY_CLIENT	End User suspected a fraudulent use of the SCA Wallet
TERMINATE_SERVICE	Your business relation with the End User was terminated
INCIDENT	Technical incident

Note – You may encounter locking reasons that can't be set manually

• DELETED – The SCA Wallet was deleted
• PASSCODE – The end user entered too many wrong PIN codes
• PAYMENT – The end user entered too many wrong PIN codes during a payment SCA

Endpoints

Endpoint	Scope
/core-connect/sca/scawallets	legal, read_write
/core-connect/sca/scawallets/swap	read_write
/core-connect/sca/scawallets?userId={userId}	read_only
/core-connect/sca/scawallets/{scaWalletId}	read_only
/core-connect/sca/scawallets/{scaWalletId}/lock	legal
/core-connect/sca/scawallets/{scaWalletId}/resetPin	legal
/core-connect/sca/scawallets/{scaWalletId}/unlock	legal
/core-connect/sca/setPasscode	read_write
/core-connect/sca/scawallets/{scaWalletId}	legal