Migrating to Thredd-issued certificates for EHI with mTLS

Thredd has enhanced its Certificate Authority service for clients who want to optionally use an EHIm setup, whereby your organisation uses the External Host Interface (EHI) application to communicate with Thredd using mTLS.

An EHI with mTLS setup (EHIm) comprises an integration with an external payments network that itself is authenticated using Mutual TLS (mTLS). mTLS relies on a system of digitally-signed certificates issued by a trusted third party called a Certificate Authority (CA). The CA proves the authenticity of the public key and the identity of the Server presenting the key.

In the EHIm flow, your application is the Server and Thredd is the Client. Both parties must prove their identities to each other for authentication by presenting their respective certificates to each other, and verifying this during the mTLS handshake.

If you are currently validating certificates from Raidiam Connect, you must change to validate client certificates from Thredd.

Thredd will only migrate clients that are currently using mTLS with Raidiam certificates to mTLS using Thredd certificates.

Who should read this guide

This guidance applies only to existing clients of Thredd who have an existing EHIm setup that is validating certificates from Raidiam Connect.

If you are setting up EHI with mTLS for the first time, see Setting up EHI for mTLS connections in the Connecting to Thredd Guide.

Why you need to switch to using Thredd-issued certificates

Thredd identity and access platform supports industry standard protocols for authentication, Single Sign-On (SSO), secure role-based access control, token and certificate lifecycle management, and secure network and API-level connectivity. Thredd's scalable security architecture roadmap is aligned with emerging standards and regulatory requirements.

In the context of this work, Thredd has enhanced its Certificate Authority service for clients who want to optionally use mTLS (Mutual Transport Layer Security) for the External Host Interface (EHI) application. As a result, Thredd is phasing out support for Raidiam certificates.

What is mTLS?

Mutual Transport Layer Security (Mutual TLS or mTLS) is an enhanced security protocol that ensures that both the Client and the Server verify each other's identity before establishing a secure communication channel. This is a digital handshake where both parties must provide their official identity. To learn more about mTLS, see Mutual TLS explained.

MTLS in EHI

In the EHIm (EHI + mTLS) communication flow, your application is the Server and Thredd is the Client. Both parties must prove their identities to each other for authentication by presenting their respective certificates to each other, and verifying this during the mTLS handshake. Once both certificates are verified, the Server grants access. The Client and Server then exchange information over the secure connection.

In order to enable this, you need to install the Thredd EHIm Trust Chain on your EHI Server. The EHI Server must validate the Client Certificates that Thredd sends to you. This ensures that a Chain of Trust is established.

A Trust Chain is a collection of trusted root certificates that are installed on the Server, which includes the root anchor (top level) and intermediate Certificate Authority (CA) certificates. An end entity uses these to establish a Chain of Trust, by checking the certificate chain, and validates the Client Certificate. The Server uses the Certificate Chain to prove the legitimacy of a Client Certificate by tracing it back to a single Root CA.

Considerations before you start

This migration process comprises several steps and requires you to change the Trust Chain that your Server is validating Client Certificates against. It also requires Thredd to update the EHI Client Certificate once you have informed Thredd that you are ready to support the new Trust Chain.

You should prepare for this by reading this guide, so that you can avoid any downtime and ensure a smooth transition during the Client Certificate Migration.

First, you need to configure your systems to use and trust the new certificate. Converting the Raidiam Trust Chain to the Thredd Trust Chain requires a phased approach:

  • First phase: Download and install the Thredd Trust Chain, while retaining trust for Raidiam certificates. During this phase, your server trusts certificates both from Raidiam and certificates from Thredd.

  • Transitional phase: Inform Thredd and confirm that you are ready for Thredd to switch the EHI Client Certificate.

  • Last phase: Once Thredd confirms that the migration is complete, you must remove the Raidiam Trust Chain from your Trust Chain file.

When you are ready, follow this guide to migrate to using Thredd's new EHI Trust Chain.

Migration steps and overview

This guidance helps you to complete the following steps:

  1. Download and install Thredd's new EHI Trust Chain.

  2. Ensure that your mTLS termination point has access to Thredd's Online Certificate Status Protocol (OCSP) responder.

  3. Inform Thredd to switch the EHI Client Certificate.

  4. Remove the Raidiam Trust Chain from your Trust Chain file, and provide your EHI endpoint to Thredd.

Prerequisites

  • You must have the Admin role for your organisation in Thredd Portal.

  • You must have access to Thredd Portal.

Step 1: Download and install Thredd's new EHI Trust Chain

You must install the EHI Trust Chain on your Server and configure your systems to ensure that your Server presents this certificate to the Client (Thredd) during the mTLS handshake.

During this phase, your server trusts both certificates issued by Raidiam and certificates issued by Thredd.

Instructions for storing certificates can differ between server vendors. Refer to your vendor's server documentation for a guide.

To download and install the Trust Chain:

  1. Log in to Thredd Portal.

  2. Navigate to and select System Admin, select Organisation, and then select EHI Configuration.

  3. Download the EHI Trust Chain.

  4. Append the Thredd EHI Trust Chain to the existing Trust Chain. This is because your mTLS termination point (your load balancer, proxy, or server) settings are currently using a Raidiam Trust Chain file. Copy the contents of the Thredd EHI Trust Chain and append it to your existing file.

  5. Configure your mTLS termination point (your load balancer, proxy, or server) settings to use the Thredd EHI Trust Chain. Point it to or copy the contents of the Thredd EHI Trust Chain file.

Before you proceed, you must ensure that your mTLS termination point is validating against the updated file, in which the contents include Thredd's EHI Trust Chain.

Refer to your server's technical documentation for information about how to complete this task.

Step 2: Ensure that your mTLS termination point has access to Thredd's Online Certificate Status Protocol (OCSP) Responder

Thredd recommends that you configure your mTLS termination point (load balancer, proxy, or server) to carry out certificate status checks. For example, to check if the certificate has been revoked.

This is optional. However, if you want to ensure that it can do this, your mTLS termination point must have access Thredd's Online Certificate Status Protocol (OCSP) Responder. The OCSP Responder provides both parties, such as your organisation and Thredd, with the ability to verify the validity of certificates issued within Thredd's private PKI hierarchy, and in real time.

Check the settings for your mTLS termination point:

  1. Make sure that your mTLS termination point can access Thredd's OCSP Responder at: https://ocsp.threddid.com

  2. Verify and change the settings if necessary. For example, by adding the OCSP Responder to the allowlist.

  3. Refer to your server's documentation for information about how to check and change your mTLS termination point settings.

Step 3: Inform Thredd that you are ready to switch the EHI client certificate

You are now in a position where your server is trusting both Raidiam certificates and Thredd certificates. Inform Thredd that you have installed the new Trust Chain on your server, and confirm that you are ready for Thredd to switch the Client Certificate.

Thredd will conduct a test to ensure that the newly-issued certificate is accepted by your server. Thredd will inform you of the result of this test once it has completed.

If successful, Thredd requests your approval to update the Client Certificate on the EHI server. Thredd will notify you when the Client Certificate Migration is complete.

Step 4: Remove the Raidiam Trust Chain from your Trust Chain file

Once Thredd has confirmed that the Client Certificate Migration is complete, you can safely delete the Raidiam Trust Chain from your Trust Chain file. This removes your server's trust for Raidiam certificates.

Refer to your server's technical documentation for information about how to complete this task.

Provide the EHI endpoint to Thredd.

Adding Security Controls

You can choose to implement additional optional controls to enhance mTLS security. These include the:

  • IP Address Allowlist — Thredd EHI messages are sent from a firewall with a fixed IP address. Optionally, you can add this IP address to your allowlist.

  • Certificate Pinning — the mutual communication, between your Server and Thredd (the Client), is secured by Thredd's Transport Certificate. Your Server only trusts the Transport Certificate if it the Thredd CA has issued it. However, you can choose to also implement Certificate Pinning. Certificate Pinning blocks attempted requests made with the incorrect certificates. For more information, see Certificate and Public Key Pinning | OWASP Foundation.