iovation TAF mutual TLS authentication implementation guide

API endpoints for iovation FraudForce are changing to require mutual TLS authentication via client certificates. This announcement describes what you need to do to comply with this new requirement if you're using the Journey Exchange iovation TAF component.

Background

Starting from 1 November 2023, API endpoints for iovation FraudForce require mutual TLS authentication via client certificates. Accordingly, the Journey Exchange iovation TAF component has been updated to comply with this new requirement. Without this component update, API calls will cease to work from that date.

iovation, TruValidate, and TransUnion are all names used at various times that refer to the same service.

Prerequisites

To complete these instructions, you need:

• access to Journey Manager with privileges to install services and edit Service Connections
• the openssl and Java keytool command-line tools installed on your computer

What you need to do

To maintain connectivity to the iovation FraudForce API endpoint, follow these steps:

• Install the updated Journey Exchange iovation TAF component into your Journey Manager instance.
• Obtain a client certificate (PEM file) from TransUnion.
• Convert the certificate into a password-protected Java KeyStore (JKS file).
• Update the Service Connection configuration with a new Endpoint URL, and a new JKS filename and password.

Detailed Instructions

Install the updated Exchange iovation component

Install version 1.6.0 of iovation TAF from Journey Exchange. This is the first version with support for mutual TLS authentication. It will update the service Iovation TAF - Check Transaction Details.

Ensure these existing service parameter values are preserved, or re-enter them after the update:

• iovationDefaultIntegrationPointName
• iovationSubscriberAccount

 Obtain a client certificate from TransUnion

If TransUnion has not provided you with a PEM-encoded client certificate, contact TransUnion support to request one. They will send you a client certificate, probably with a .txt extension, via secure email or another secure method.

Your PEM-encoded certificate file contains lines like this:

-----BEGIN CERTIFICATE-----
<certificate content in base64>
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
<private key content in base64>
-----END RSA PRIVATE KEY-----

Convert the PEM-format certificate to a Java KeyStore

The Service Connection requires a Java KeyStore (JKS file), not a PEM file. So, you need to convert your PEM file to a password-protected JKS file.

The commands below assume you have saved your PEM file as customer.pem. Executing these commands produces an interim file called customer.p12, and an output file called customer.jks. You can use different file names, but if you do replace all instances of each file name in both commands.

In a terminal or command prompt, enter the following commands.

1. openssl pkcs12 -export -in customer.pem -out customer.p12 -name iovationalias -passin pass:PASSWORD -passout pass:PASSWORD
   

2. keytool -v -importkeystore -srckeystore customer.p12 -srcstoretype PKCS12 -destkeystore customer.jks -deststoretype JKS -srcstorepass PASSWORD -deststorepass PASSWORD -srcalias iovationalias -destalias iovationalias
   

You can verify the resulting customer.jks file is valid by running the following command:

keytool -v -list -keystore customer.jks -storepass PASSWORD

Update your existing Service Connection

Follow these steps:

1. Login to your Journey Manager instance.
2. From the menu, select Services > Service Connections then select your existing iovation TAF Service Connection from the list.

3. In the Endpoint box, enter the URL for your environment:

   Environment	Endpoint URL
   Production	https://mtls-api.iovation.com/fraud/v1/subs
   Development/Test	https://mtls-ci-api.iovation.com/fraud/v1/subs

4.  Enter values for other Service Connection properties as shown below.

   1. Username: Enter your TransUnion Subscriber ID.
   2. Password, Confirm Password: Enter your TransUnion Subscriber password.
   3. Auth Key: Enter your JKS file password.
   4. Data File: Click Choose File and select your JKS file.

    

5. Click Save.