SCA Authentication

Key principles

Before the SCA mechanism, all your requests to the Treezor API were 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 Web Native 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.).

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.

Obtain an SCA Proof

Prerequisites – Users must be enrolled first

For both the mobile and web native solutions, the user must have an active SCA Wallet. See Enrolling users for more information.

Mobile signature

SCA proof capabilities are provided by the SDK via CustomerAuthenticatedSignature, it produces a signature once the user has performed the required authentication. This signature is generated locally within Entrust SDK and is returned to the hosting app.

CustomerAuthenticatedSignature must first be instantiated with the following parameters.

Parameter	Description
patternName	The name of the authentication pattern to use for this authentication. Can be: patterns.NONE.name for none authentication patterns.PIN.name for PIN authentication patterns.BIOMETRY.name for Biometric authentication
message	The message to display to the customer. Must be set if the SDK is used to display the UI. In any case, this information is part of the signed data.
signatureType	Type of signature result to generate. You must use the CustomerAuthenticatedSignatureType.LocalJws option.
signatureInputData	Custom, context-related information that is part of the signed data.

Once instantiated, you must call CustomerAuthenticatedSignature#sign() to start the signature process.

When the CustomerAuthenticatedSignature is successfully completed, you're notified by the CustomCustomerAuthenticatedProcessCallback#onProcessSuccess() callback. The generated signature result can be fetched by calling CustomerAuthenticatedSignature#getResult().

See the SDK Signature article for more information.

Web Native signature

Once the browser has undergone the enrollment, it is able to produce SCA signatures.

SCA enforcement requires that all request to the Treezor API be made in the name of the User. Therefore, when obtaining a JWT, you must now provide an SCA proof.

The following code snippet shows how to generate an SCA proof that can then be used to obtain a JWT.

JavaScript

const publicKeyCredentialRequestOptions = {
    challenge: convertToArrayBuffer(JSON.stringify({ iat: Date.now() })), 
    // for the login step, you must strictly provide the challenge above
    allowCredentials: [],
    timeout: 60000, 
    // time in milliseconds for the end user to complete the WebAuthn flow
    rpId: 'www.example.com', 
    // the current FQDN, must be the same used during enrollment flow
};

const assertion = await navigator.credentials.get({
    publicKey: publicKeyCredentialRequestOptions,
});

const response = assertion.response;

const rawId = arrayBufferToBase64Url(assertion.rawId).toString();

const clientDataJSON = arrayBufferToBase64Url(
    assertion.response.clientDataJSON
).toString();

const authenticatorData = arrayBufferToBase64Url(
    response.authenticatorData
).toString();

const signature = arrayBufferToBase64Url(response.signature).toString();

const userHandle = arrayBufferToBase64Url(response.userHandle).toString();

let encodedResponse = btoa(
    JSON.stringify({
        response: {
            authenticatorData,
            clientDataJSON,
            signature,
            userHandle,
        },
        id: assertion.id,
        rawId,
        type: "public-key",
    })
);

Request the User to enter their passcode and encrypt it.

JavaScript

const encryptedPassCode = encryptPasscode(passCode) 
// see Passcode encryption section below regarding how to encrypt the passcode

The two strings from the previous steps should now be concatenated with a dot as follows:

JavaScript

const sca = `${encryptedPassCode}.${encodedResponse}` // concatenate these values with a dot

Request the end user's JWT

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(userIdclient_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.

Request example

CURL

curl -X POST {baseUrl}/oauth/token \
	--form 'grant_type="delegated_end_user"' \
    --form 'client_id="{clientId}"' \
    --form 'client_secret="{clientSecret}"' \
    --form 'scope="read_write"' \
    --form 'username="101109094"' \
    --form 'password="bc6ead2bbcd9cc409ba53d9cfbf145a667647414eae496xxxx75636b15384a8"'  \
    --form 'sca="eyJh_NDN9.WQBp_Xg7w"'

Returns the Bearer token:

JSON

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJ0_XXX_q44Q"
}

Make requests in the name of the end user

Here is an example for creating a Beneficiary (per-operation SCA, so you need another SCA proof prior to this action).

CURL

curl -X POST {baseUrl}/v1/beneficiaries \
	--header 'Authorization: Bearer eyJ0_XXX_q44Q' \
	--header 'Content-Type: application/json'\
    --data '{payload}'

With the following {payload}:

JSON

{
    "userId": "101109094",
    "name": "Alex Oak",
    "adress": "33 av de Wagram Paris",
    "iban": "FR1130003000305928344XXXXX",
    "bic": "SOGEFRPPXXX",
    "usableForSct": true,
    "sca":"eyJh_UxfQ.nNIH_n9kA"  // SCA proof that you need as a prerequisite
}

Returns the Beneficiary object:

JSON

{
    "beneficiaries": [
        {
            "id": 527977,
            "tag": "",
            "userId": 101109094,
            "nickName": "",
            "name": "Alex Oak",
            "address": "",
            "iban": "3537524356444355504255444055564B574C405157455041XXXX",
            "bic": "SOGEFRPPXXX",
            "sepaCreditorIdentifier": "",
            "sddB2bWhitelist": [],
            "sddCoreBlacklist": [],
            "usableForSct": true,
            "sddCoreKnownUniqueMandateReference": [],
            "isActive": true,
            "createdDate": "2024-11-21 08:05:56",
            "modifiedDate": "2024-11-21 08:05:56",
            "metadata": {
                "iban": "FR1130003000305928344XXXXX"
            }
        }
    ]
}