SCA SDK
/
SCA Implementation
Last updated

SCA Implementation

Introduction

Before going through the SCA-features implementation, make sure you read :

  • The Authentication SCA Page which explains the global workflow of Strong Customer Authentication with LinkCy API.
  • The SCA SDK Page wich explains who to install and get started with the provided SCA SDK.

On the client side, the SCA flow can be resumed in a few steps.

  • Initializing the SDK listeners.
  • Enrolling/Logging your customer.
  • Performing SCA challenges on secured features.
  • Handling updates.

You will find below a few implementation examples of the basic SCA features needed in a client application, written in javascript using the React Native SDK.

Setting up the SDK listeners.

Challenges

For any security operation, the customer will have to be challenged to an SCA validation using the SDK.

It can be useful to wrap this challenge call inside a method so you can add some common behavior.

export const addChallengeListener = (
    onSuccess: () => void,
    onFailure: () => void,
) => {
    RNCustomerAuthnSDK.onChallengeCustomer(challenge => {
        switch (challenge.authentication.factorType) {
            case 'ENDPOINT_PIN':
            case 'endpointPin':
            case 'BIOMETRICS_DEVICE':
            case 'biometricsDevice':
                RNCustomerAuthnSDK.answerChallenge({
                    challengeId: challenge.challengeId,
                    selectedButtonRole: ButtonRole.POSITIVE,
                })
                .then(() => {
                    onSuccess();
                })
                .catch(() => {
                    onFailure();
                });
            break;
            default:
                console.error('Unknown challenge');
    }
  });
};

Pin authentication

Setting up listeners for pin enrolment and authentication.

export const addPinListener = (passcode: string) => {
  RNCustomerAuthnSDK.onRequireEndpointPinAuthenticationFactor(() => {
    proceedPinAuthenticationFactor(passcode);
  });
  RNCustomerAuthnSDK.onSetEndpointPinAuthenticationFactor(() => {
    proceedPinAuthenticationFactor(passcode);
  });
};

function proceedPinAuthenticationFactor(passcode: string) {
  if (passcode) {
    try {
      RNCustomerAuthnSDK.endpointPinSuccess(passcode);
    } catch (e) {
      console.error(`unable to capture pin : ${e}`);
    }
  } else {
    console.error('Unable to enroll endpoint pin: no passcode.');
  }

Biometric authentication

Setting up listeners for biometric enrolment and authentication.

export const addBiometricListener = () => {
  RNCustomerAuthnSDK.onSetBiometricAuthenticationFactor(() => {
    proceedBiometricAuthenticationFactor();
  });
  RNCustomerAuthnSDK.onRequireBiometricAuthenticationFactor(() => {
    proceedBiometricAuthenticationFactor();
  });
};

function proceedBiometricAuthenticationFactor() {
  try {
    RNCustomerAuthnSDK.proceedBiometricAuthenticationFactor();
  } catch (e) {
    console.error('unable to capture biometry :', e);
  }
}

Enrolling/Logging your customer

When your customer logs in, you should get his information and either try to enroll him in the SCA procedure or give him access to the app depending on his status.

Knowing if the given consumer has enrolled a SCA device

After getting the current consumer from our API, the strongAuthentication property will give information about his status through the SCA enrollment process.

function isDeviceEnrolledByEntersekt(consumer): boolean {
    return (
        consumer?.strongAuthentication?.pinStatus === ScaFactorStatus.SET ||
        consumer?.strongAuthentication?.biometryStatus === ScaFactorStatus.SET ||
        consumer?.strongAuthentication?.pinStatus === ScaFactorStatus.PENDING ||
        consumer?.strongAuthentication?.biometryStatus === ScaFactorStatus.PENDING
    );
}

Enrolling a new device

You can retrieve your endpointId from your SDK.

async function getSdkEndpointId() {
    return RNCustomerAuthnSDK.getSDKInfo().then(sdkInfo => sdkInfo.endpointID);
}

Then, sending an enrollment request for the given endUser to the LinkCy API is a piece of cake (using axios) !

axios
    .post('partner/sca', {
        endpointId, // See above
        factor, // 'PIN' | 'BIOMETRY' 
        strategy, // 'PUSH_NOTIFICATION' | 'JOIN_CODE' | 'BY_PASS' | 'FAIL'
        endUserId, // The consumer id
    })
    .then(axiosResponse => axiosResponse.data)
    .catch(error => {
        // Trigger a behavior when the enrollment fails.
    });

Checking if the actual device is enrolled

The consumer endpointId can also be compared to the actual endpointId to check if the current device is the one enrolled.

if(consumer.strongAuthentication?.endpointId !== endpointId) {
    console.log('another device is enrolled with this consumer').
}

Performing SCA challenges on secured features

When performing a sensible operation, SCA might be required. If that is the case, the API will return a 202 status with the corresponding ID of the SCA operation.

A challenge will then be triggered to validate this operation and the request should be sent again, with the previous SCA Id.

LinkCy API Requests headers for SCA

You may configure and complete the SCA through requests to the Partner API by adding the following headers:

  • Linkcy-SCA-Factor = PIN | BIOMETRY
  • Linkcy-SCA-Strategy = PUSH_NOTIFICATION | JOIN_CODE | BY_PASS | FAIL
  • Linkcy-SCA-Id = your challenge id

Returned errors

  • SCA_INTERACTION_DOES_NOT_MATCH : The SCA interaction you are referring does not match the one you are trying to make.
  • SCA_INTERACTION_NOT_FOUND : The SCA interaction you are referring could not be found.
  • SCA_INTERACTION_NOT_COMPLETED : The SCA interaction you are referring is not completed.
  • SCA_INTERACTION_DECLINED : The SCA interaction you are referring was declined by user or expired.
  • SCA_INTERACTION_ALREADY_CONSUMED : The SCA interaction you are referring has already been used, you need to create a new one.
  • SCA_REQUIRED : The operation you are trying to do requires SCA.
  • SCA_DEVICE_NOT_SET : The operation requires SCA but the corresponding user has no SCA device set up.
  • SCA_DEVICE_NOT_FOUND : The SCA device you are referring to could not be found.
  • SCA_FACTOR_NOT_SET : The SCA factor is not set for this end user.
  • SCA_DEVICE_ALREADY_SET : The SCA device for this user has already been set up.
  • SCA_BIOMETRY_ALREADY_SET : Biometry is already set on this SCA device.

Use cases

  • Enroll
  • Login
  • Sensible operations
Previous page