ACS Integration guide

Overview

This writeup documents how an ACS would integrate with the SCA gathering methods mSIGNIA uSDK 6.5 and later leverages. Starting from 6.5 release, the iOS and Android uSDKs allow the ACS servers to request additional properties from the mobile device and browsers to make SCA easier for ACSes. This document explains the features in details so an ACS vendor uses this document as an integration guide.

The SCA methods supported

As of 6.5 release the uSDKs support the following SCA methods:

How does ACS tell the uSDK to perform a method

An ACS has to tell the uSDK to perform one of the SCA methods during the next transaction. For that, the ACS leverages a custom message extension with the ID of usdk.strong-customer-auth like shown below and includes it in the ARes or CRes:

{
  "id": "usdk.strong-customer-auth",
  "name": "usdk.strong-customer-auth"
  "data": {
      "v": 1,
      "methods": [ "DEVICE_COOKIE", /* other methods go here */ ]
      "acsReferenceNumber": "${acs-reference-number}",
      "issuerId": "123e4567-e89b-12d3-a456-426655440000",
  }
  "criticalityIndicator": false
}

A few points to note at here are:

1. The ACS can request more than one SCA method for the SDK to perform on next transaction, thus the data.method data element is an array that holds a list of SCA methods.
2. The data.v data element denotes the message extension version. It should be 1.
3. The ACS tells a bit about itself - the data.acsRefenence is used to ACS Referene number assigned by EMVco, while data.issuerId is an ACS identifier issued by mSIGNIA when the ACS has been enrolled with it.

The following sections explain each specific SCA method in more detail.

DEVICE_COOKIE

The DEVICE_COOKIE method lets the ACS to store certain data on the device. The uSDK then send that exact data back to ACS on the next transaction the user performs. So it could be as simple as a cookie but also various advanced use-cases are possible - for instance the ACS may store a token, a public key etc.

Note, once a device cookie is received by the uSDK, it’ll send it back to ACS on each consequent transaction. The ACS can “clear” it if needed by sending an empty cookie value. In that case uSDK will clear the cookie and stop sending it to ACS.

How ACS requests the method

The message extension that ACS is supposed to issue requesting this specific SCA method would look this:

{
  "id": "usdk.strong-customer-auth",
  "name": "usdk.strong-customer-auth"
  "data": {
      "v": 1,
      "methods": [ "DEVICE_COOKIE" ]
      "acsReferenceNumber": "${acs-reference-number}",
      "issuerId": "123e4567-e89b-12d3-a456-426655440000",
      "deviceCookie": "${the-actual-cookie-value}"
  }
  "criticalityIndicator": false
}

When and how does SDK execute and delivers the data to ACS

Mobile uSDKs

Then, on the next transaction, the uSDK will run the method. Running it means it’ll take the data.deviceCookie received in the previously and include in AReq.sdkEncData data element that is normally encrypted with the DS public key. Once DS decrypts it and makes available for ACS as AReq.deviceInfo, the ACS then looks for it in the SCA data element:

let deviceInfo = {
    "SCA": {
        "deviceCookie": "c01d40c5-2157-46c7-95bd-c972f2fc6fb3"
    },
    "DD": {
        "A108": "422",
        "A051": "sdk_gphone_x86",
        // many other DDs omitted here
    },
    "DV": "1.4",
    "SW": [
        "SW03",
        "SW01"
    ],
    "DPNA": {
        "A106": "RE04",
    }
}

Using the of deviceInfo.SCA.deviceCookie as well as some other DDs would let the ACS to efficiently tag the user device.

Browser uSDK

The browser uSDK sends the SCA methods it performed as part of the request to the 3DS Method URL. This means that ACS receives it before the actual AReq/ARes flow begins so it lets the ACS to check the device cookie before it makes a frictionless transStatus decision.

An example request to the 3DS Method URL would looks like this:

Method: POST
URL: 3DS Method URL
Params:
    deviceCookie: c01d40c5-2157-46c7-95bd-c972f2fc6fb3
    threeDSMethodData: <a normal base64 datum sent to 3DS Method>

USDK_PROMPT_TEXT

This method is used to prompt the user to enter some text before the frictionless flow begins and include the user’s input in AReq. The method is flexible in the sence that it lets the ACS to control the details of the prompt such as prompt heading text, prompt message, the keyboard type to use etc.

How ACS requests the method

The method is requested via the message extension:

{
  "id": "usdk.strong-customer-auth",
  "name": "usdk.strong-customer-auth"
  "data": {
      "v": 1,
      "methods": [ "USDK_PROMPT_TEXT" ]
      "acsReferenceNumber": "${acs-reference-number}",
      "issuerId": "123e4567-e89b-12d3-a456-426655440000",
      "usdkPrompt": {
          "heading": "Postal code",
          "keyboard":"NUMERIC", 
          "message": "Please enter your postal code:"
      }
  }
  "criticalityIndicator": false
}

So, the method name is USDK_PROMPT_TEXT plus the usdkPrompt data element lets configure the prompt:

• usdkPrompt.heading - sets the heading text in the prompt
• usdkPrompt.message - the message
• usdkPrompt.keyboard - keyboard type. Options are: NUMERIC, EMAIL or DEFAULT

When and how does SDK execute and delivers the data to ACS

The uSDK then presents the user with the following prompt,

captures user’s input and includes it in AReq.sdkEncData data element that is normally encrypted with the DS public key. Once DS decrypts it and makes available for ACS as AReq.deviceInfo, the ACS then looks for it in the SCA data element:

let deviceInfo = {
    "SCA": {
        "usdkPrompt": {
            "input": "18005",
            "typing": "behavioral metrics - touches, 
                typing captured while user answered in the prompt"
        }
    },
    "DD": {
        "A108": "422",
        "A051": "sdk_gphone_x86",
        // many other DDs omitted here
    },
    "DV": "1.4",
    "SW": [
        "SW03",
        "SW01"
    ],
    "DPNA": {
        "A106": "RE04",
    }
}

USDK_PROMPT_LOCAL_BIO_AUTH

This method presents the user with a screen/popup (whatever is the most convenient way on the particular mobile platform) to either scan a fingerprint or authenticate via FaceID. This popup is displayed before the frictionless flow begins.

Note, the SDKs won’t the user to fallback to a non biometrical authentication such as drawing pattern or password entry.

How ACS requests the method

The method is requested via the message extension:

{
  "id": "usdk.strong-customer-auth",
  "name": "usdk.strong-customer-auth"
  "data": {
      "v": 1,
      "methods": [ "USDK_PROMPT_LOCAL_BIO_AUTH" ]
      "acsReferenceNumber": "${acs-reference-number}",
      "issuerId": "123e4567-e89b-12d3-a456-426655440000",
  }
  "criticalityIndicator": false
}

When and how does SDK execute and delivers the data to ACS

The uSDK performs fingerprint or FaceID authentication right before it kicks off the frictionless flow. Depending on the outcome it may or may not begin a transaction. See the following table for more details. If transaction happens, then the authentication result if delivered to ACS in AReq.sdkEncData which DS decrypts into AReq.deviceInfo.

The corresponging result (and reason) can then be found in the SCA.localBioAuth data element of AReq.deviceInfo:

let deviceInfo = {
    "SCA": {
        "localBioAuth": {
            "result": "FAILED"
            "reason": "HARDWARE_UNAVAILABLE"
        }
    },
    "DD": {
        "A108": "422",
        "A051": "sdk_gphone_x86",
        // many other DDs omitted here
    },
    "DV": "1.4",
    "SW": [
        "SW03",
        "SW01"
    ],
    "DPNA": {
        "A106": "RE04",
    }
}

BEHAVIORAL_METRICS

This lets the ACS to request capturing of typings, touches and device tilt changes while the user interacts with the mobile challenge screen (CReq/CRes phase of a 3DS tranaction). The data captured is then gets sent to ACS in a custom message extension included in CReq.

How ACS requests the method

The method is requested via the message extension received in CRes:

{
  "id": "usdk.strong-customer-auth",
  "name": "usdk.strong-customer-auth"
  "data": {
      "v": 1,
      "methods": [ "BEHAVIORAL_METRICS" ]
      "acsReferenceNumber": "${acs-reference-number}",
      "issuerId": "123e4567-e89b-12d3-a456-426655440000",
  }
  "criticalityIndicator": false
}

When and how does SDK execute and delivers the data to ACS

Depending on the challenge type, the uSDK captures different kinds of metrics:

The uSDK includes the following message extension in CRes.messageExtension data element:

{
  "id": "usdk.behavioral-bio",
  "name": "usdk.behavioral-bio"
  "data": {
      "typingPattern": "${typings and touch data captured}",
  }
  "criticalityIndicator": false
}