Establish Connectivity for Data Transfer

To work successfully with Publisher v2.0 APIs, partners must establish connectivity for ongoing data transfer and services. The process involves using industry-standard HTTPS and sFTP over mTLS + an IP-Address-Allow-List. Cardlytics is hosted across two regions and multiple availability zones in AWS.

Traffic in this configuration flows over the public internet, as shown in the diagram below. The connection is secured with IP address-whitelisting and two-way SSL

Key Terminology

SSL, or Secure Sockets Layer, is an encryption-based Internet security protocol. A website that implements SSL/TLS has HTTPS in its URL instead of HTTP.

ACL, an access-control list, is a list of permissions associated with a system resource. An ACL specifies which users or system processes are granted access to resources, as well as what operations are allowed on given resources.

Security rules and network ACLs are implemented by the Cardlytics Operations team to protect both parties involved, using two-way SSL encryption.

Mutual TLS, or mTLS for short, is a method for mutual authentication, ensuring that parties at each end of a network connection are who they claim to be by verifying they both have the correct private key.

How It Works

The typical TLS process works like this:

Client connects to the server.
Server presents its TLS certificate.
Client verifies the server's certificate.
Client and server exchange information over an encrypted TLS connection.

Tasks & Implementation Steps

Cardlytics will work closely with your network team to plan out the full details. The high-level implementation steps are described in broad outline below.

These are organized based on specific [Joint] and [Publisher] tasks.

The first [Joint] task is to create a certificate for securing the communication.

The [Publisher] begins by generating a Client Certificate for mTLS Integration, as follows:

Step 1: Generate a private client certificate key like this:

> openssl genrsa -out my_client.key 2048

Generating RSA private key, 2048 bit long modulus ...+++++ ...................................................................................................................+++++ e is 65537 (0x10001)

Step 2: Generate a client certificate signing request (CSR)

Note that you may enter the Organizational Name, Unit details, Common Name and Email address. DO NOT enter any ‘extra’ attributes (for example: Challenge password).
Each setup requires a unique client certificate. That is, one client certificate for the PROD and one for the PRE-PROD.
Ensure that the subject for Pre-Prod and Prod certificates are different. We recommend adding CN=UAT to the Pre-Prod CSR.

For example:

> openssl req -new -key my_client.key -out my_client.csr

You will be asked to enter information that is incorporated into your certificate request.
What you enter is a Distinguished Name or a DN. There are quite a few fields but you can leave some blank. For some fields, there is a default value, If you enter '.', the field will be left blank.

Country Name (2 letter code) []:US
State or Province Name (full name) []:Texas
Locality Name (eg, city) []:Austin
Organization Name (eg, company) []:Dosh
Organizational Unit Name (eg, section) []: Promotion
Common Name (eg, fully qualified host name) []:
Email Address []: [email protected]

Enter the following 'extra' attributes to be sent with your certificate request A challenge password []:`

What you need to do:

Generate your bank_client.key (private key) - this is not shared with Cardlytics.
Generate your bank_client.csr (certificate sign request) and send it to Cardlytics. Note that two CSRs are needed: one for Pre-Production, one for Production.
Provide your public IPs for whitelisting on the Cardlytics side.

Step 3. Cardlytics signs and generates client certificates

Step 4. Share new endpoints [Cardlytics]

Cardlytics provides the DNS links in case a Publisher wants to whitelist.
Cardlytics configures the infrastructure for the Publisher.

Step 5. Pre-Production network switch-on [Joint]

As a Publisher, you point the Pre-Prod environment to the Pre-Prod endpoint with a new certificate.
You install a new certificate in your Pre-Prod infrastructure.
Pre-Prod testing and verification.
Verify connectivity via a health check endpoint at https://pub-api-us.prod.cardlytics.com/healthcheck
Integration Test - startSession, getAds, clientEvent for a known good customer needs to be confirmed

Step 6. Production network switch-on [Joint]

As a Publisher, you point the Production environment to the Production endpoint with a new certificate.
Publisher installs new certificate in their Prod infrastructure
Production testing and verification:

Verify connectivity via a health check endpoint
Integration Test - startSession, getAds, clientEvent for a known good customer needs to be confirmed.

Monitor dashboards.