Knowledge Article Detail Page - CYBS | Cybersource Support Center

What can we help you with?

Article Number

KA-04117

Article Total View Count

179

Last Modified Date

07/16/2024 00:21 AM

Version

7.0

Overview

We are updating the Public Key for Flex API based applications. This Key is used to validate the authenticity of the Capture Context retrieved from the sessions call (see below). The Capture Context is a JWT object and its signature can be validated using the public key. Additionally, the signature is internally validated in the Microform and Unified Checkout applications. These security protocols are put in place to ensure the integrity of the chain of trust of the data flow.

Impact
If your integration validates the Capture Context and using one of the following versions, then your application will be impacted:

Microform
- V1
- V2
- V0.11.x (e.g. V0.11.5)

Please note: using the original version of V0.11 is not impacted as it points to the latest Flex Key endpoint dynamically:

Example: https://flex.cybersource.com/cybersource/assets/microform/0.11/flex-microform.min.js

Unified Checkout
Flex API

Details

Ensure you are dynamically loading the correct key for Capture Context JWT Validation
Ensure you are using the correct JS Library

The following Endpoints will be impacted new public Key
- /flex/v2/sessions
- /microform/v2/sessions
- /up/v1/capture-contexts
- /flex/v2/public-keys/
- /flex/v1/keys?format=JWT
This change has been rescheduled and the new Date will be announced soon.

Actions

Flex API

Verifying the JWT on your backend system is security best practice (but optional)
Ensure that you are not validating the capture context signature using an old Key
- The Public Key should be retrieved dynamically leveraging the public keys endpoint. The last segment of the URI path is KID (Key ID).
  - /flex/v2/public-keys/[KID]

- - - For example: https://flex.cybersource.com/flex/v2/public-keys/ln
    - For example: https://testflex.cybersource.com/flex/v2/public-keys/zu
  - The KID used for this request is contained in the header of the capture context JWT data structure (see Decoded Body in Samples section)
  - The Public Key are immutable and can (should) be cached to improve performance by avoiding unnecessary network calls.
  - The new public keys can be tested on the CAS environment by calling public key endpoints C1 to C5 (where C1 to C5 = [KID]).
  - For example: https://testflex.cybersource.com/flex/v2/public-keys/c1

Microform Version 0.11 or V1

Verifying the JWT on your backend system is security best practice (but optional)
- Ensure that you are not validating the capture context signature using an old Key
  - The Public Key should be retrieved dynamically leveraging the public keys endpoint. The last segment of the URI path is KID (Key ID).
    - /flex/v2/public-keys/[KID]

- - - For example: https://flex.cybersource.com/flex/v2/public-keys/ln
    - For example: https://testflex.cybersource.com/flex/v2/public-keys/zu

- - - The KID used for this request is contained in the header of the capture context JWT data structure (see Decoded Body in Samples section)
    - The Public Key are immutable and can (should) be cached to improve performance by avoiding unnecessary network calls.
Ensure that you are using the most up to date Microform JS Library
- The Microform JavaScript validates the Public Key as well, ensure that you are leveraging the most up to date version of the microform.
  - Ensure you are not defining a minor version of the SDK
    - Example: https://flex.cybersource.com/cybersource/assets/microform/0.11.5/flex-microform.min.js

Microform Version 2

Verifying the JWT on your backend system is security best practice (but optional)
- Ensure that you are not validating the capture context signature using an old Key
  - The Public Key should be retrieved dynamically leveraging the public keys endpoint. The last segment of the URI path is KID (Key ID).
    - /flex/v2/public-keys/[KID]

- - - For example: https://flex.cybersource.com/flex/v2/public-keys/ln
    - For example: https://testflex.cybersource.com/flex/v2/public-keys/zu

- - - The KID used for this request is contained in the header of the capture context JWT data structure (see Decoded Body in Samples section)
    - The Public Key are immutable and can (should) be cached to improve performance by avoiding unnecessary network calls.
Ensure that you are using the most up to date Microform JS Library
- The Microform JavaScript validates the Public Key as well, ensure that you are leveraging the most up to date version of the microform.
  - The most recent version of the client library can be found within the body of the capture context client Library
    - Example:
      "clientLibrary": "https://testflex.cybersource.com/microform/bundle/v2.0/flex-microform.min.js",

Unified Checkout

Verifying the JWT on your backend system is security best practice (but optional)
- Ensure that you are not validating the capture context signature using an old Key
  - The Public Key should be retrieved dynamically leveraging the public keys endpoint. The last segment of the URI path is KID (Key ID).
    - /flex/v2/public-keys/[KID]

- - - For example: https://flex.cybersource.com/flex/v2/public-keys/ln
    - For example: https://testflex.cybersource.com/flex/v2/public-keys/zu

- - - The KID used for this request is contained in the header of the capture context JWT data structure (see Decoded Body in Samples section)
    - The Public Key are immutable and can (should) be cached to improve performance by avoiding unnecessary network calls.
Ensure that you are using the most up to date Unified Checkout JS Library
- The Unified Checkout JavaScript validates the Public Key as well, ensure that you are leveraging the most up to date version of the microform.
  - The most recent version of the client library can be found within the body of the capture context client Library
    - Example:
      "clientLibrary": "https://testflex.cybersource.com/microform/bundle/v2.0/flex-microform.min.js",

Samples:

JWT:
eyJraWQiOiJ6dSIsImFsZyI6IlJTMjU2In0.eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiJJTWZpS3FpR3U3Y2t6bEZ4d2t2eHNCQUFFSmZDZ3RYWVlNSmNrN1prUFRrbjRrODB5YnlHTUd2S09GREUxOHlGcUZtRVZHc0RnbkdBYmFxZyt1ZytITXh6OGZOZys2VHlGUHR1ekFvNlM0NDk3eVcyalVMaFZycW5kMVJ5N2JjUXJEdzAiLCJvcmlnaW4iOiJodHRwczovL3Rlc3RmbGV4LmN5YmVyc291cmNlLmNvbSIsImp3ayI6eyJrdHkiOiJSU0EiLCJlIjoiQVFBQiIsInVzZSI6ImVuYyIsIm4iOiJqNXZRS2dIOEFZUzJpTDZGc0IzTmtsbHhZbGpPbXQydjZRTDdjQXk3elJ0bXZuVThYRWUzd014djV3WVlJT1R3WjJrTnBUOWd0ODNzZjRDYTRLRDh5ak8xeWJ5bXR1VWVZa01iMnhBajBVRmpZS2ljMm9fY3pGQkJrenMteDBNQUUxVE9JdTFVelkySWdicDZycVVQVmExWnlUUHZuNF8wX1FzbDVkS1ExN3lEX2Y2MzBHeVBtdVY0RzVxWmNtTjZVQ2o4Ni0wN3NxZnRXZ3N2TWkwZy1QTld1WERKcV92emU1Qi1rdU1acjBWbF90d0JLeF9NQmlxdXg5d3huYWtLTklRWHFXYzBFRXM1RmV5LWJocmh3MUxwSEtmTlhUa25YTmExWUlSZkpqclNER2w4NUN3UUxnNV9ocjBmYXc4MEViVkFza0duQXg2TjB3YkU2c0ZkSlEiLCJraWQiOiIwOE5IU05MY0FrdEtadTEyMlpCb0lmWkU4YnZJakMwRCJ9fSwiY3R4IjpbeyJkYXRhIjp7ImNsaWVudExpYnJhcnkiOiJodHRwczovL3Rlc3RmbGV4LmN5YmVyc291cmNlLmNvbS9taWNyb2Zvcm0vYnVuZGxlL3YyLjAvZmxleC1taWNyb2Zvcm0ubWluLmpzIiwiYWxsb3dlZENhcmROZXR3b3JrcyI6WyJWSVNBIiwiTUFFU1RSTyIsIk1BU1RFUkNBUkQiLCJBTUVYIiwiRElTQ09WRVIiLCJESU5FUlNDTFVCIiwiSkNCIiwiQ1VQIiwiQ0FSVEVTQkFOQ0FJUkVTIiwiQ0FSTkVUIl0sInRhcmdldE9yaWdpbnMiOlsiaHR0cHM6Ly93d3cuZXhhbXBsZS5jb20iLCJodHRwczovL3d3dy5leGFtcGxlLm5ldCJdLCJtZk9yaWdpbiI6Imh0dHBzOi8vdGVzdGZsZXguY3liZXJzb3VyY2UuY29tIn0sInR5cGUiOiJtZi0yLjAuMCJ9XSwiaXNzIjoiRmxleCBBUEkiLCJleHAiOjE2NzE0NzQzNDgsImlhdCI6MTY3MTQ3MzQ0OCwianRpIjoiZUpLdzdoS0pXdFBaR3BMYSJ9.mY37ur3TeBMi59iX4ZtA9J5e4kTbMyaUW6ojbAebjRZ3Htju7p9YAwXg_eenwShLDENknPYzHpkytEIuMwon9peqt-LT3Bzc9GPm67wklC8feTLgQaxuzAdANeWDvs-Kh3xlL6BOuhBt8fd4Csa4TFnKyNhDPU1shkHlnbJInQVZ-b8eWY9RLe-I1wVpCbSBaWtWYivEAQ8eORovA7W5rpT5hqlAJBggEm-vz9DoimqlKTNXuZKhBFXNTngn8xNyx1hrz9WE1zu1zE9J16WQPVuT2kWaytFG-_Mk7oJ9JiM0VJlKuW_ofJc7ax10WQsxwm1VPIxgtCaCNxyJYcJqpQ

Decoded Header:
{
"kid": "zu",
"alg": "RS256"
}

Decoded Body:
{
"flx": {
    "path": "/flex/v2/tokens",
    "data": "IMfiKqiGu7ckzlFxwkvxsBAAEJfCgtXYYMJck7ZkPTkn4k80ybyGMGvKOFDE18yFqFmEVGsDgnGAbaqg+ug+HMxz8fNg+6TyFPtuzAo6S4497yW2jULhVrqnd1Ry7bcQrDw0",
    "origin": "https://testflex.cybersource.com",
    "jwk": {
      "kty": "RSA",
      "e": "AQAB",
      "use": "enc",
      "n": "j5vQKgH8AYS2iL6FsB3NkllxYljOmt2v6QL7cAy7zRtmvnU8XEe3wMxv5wYYIOTwZ2kNpT9gt83sf4Ca4KD8yjO1ybymtuUeYkMb2xAj0UFjYKic2o_czFBBkzs-x0MAE1TOIu1UzY2Igbp6rqUPVa1ZyTPvn4_0_Qsl5dKQ17yD_f630GyPmuV4G5qZcmN6UCj86-07sqftWgsvMi0g-PNWuXDJq_vze5B-kuMZr0Vl_twBKx_MBiqux9wxnakKNIQXqWc0EEs5Fey-bhrhw1LpHKfNXTknXNa1YIRfJjrSDGl85CwQLg5_hr0faw80EbVAskGnAx6N0wbE6sFdJQ",
      "kid": "08NHSNLcAktKZu122ZBoIfZE8bvIjC0D"
    }
},
"ctx": [
    {
      "data": {
        "clientLibrary": "https://testflex.cybersource.com/microform/bundle/v2.0/flex-microform.min.js",
        "allowedCardNetworks": [
          "VISA",
          "MAESTRO",
          "MASTERCARD",
          "AMEX",
          "DISCOVER",
          "DINERSCLUB",
          "JCB",
          "CUP",
          "CARTESBANCAIRES",
          "CARNET"
        ],
        "targetOrigins": [
          "https://www.example.com",
          "https://www.example.net"
        ],
        "mfOrigin": "https://testflex.cybersource.com"
      },
      "type": "mf-2.0.0"
    }
],
"iss": "Flex API",
"exp": 1671474348,
"iat": 1671473448,
"jti": "eJKw7hKJWtPZGpLa"
}

Was this article helpful?

Articles Recommended for You

FLEX Key Rotation update