Migrating from mTLS to a new mTLS connection to Thredd and SOAP Web Services

Thredd's scalable security architecture roadmap is aligned with emerging standards and regulatory requirements. In the context of this work, Thredd has enhanced its Secure Framework. As a result, Thredd is phasing out support for Raidiam certificates and Cloudentity. You will have used Cloudentity as the identity provider for Thredd interfaces and OAuth OpenID provider for application, access token and access policy management.

Thredd's Secure Framework is the combination of several components which enables clients to access Thredd's resources securely over mTLS (Mutual Transport Level Security). Thredd Portal sits at the centre of this, enabling Admin users to manage their organisation's applications, users, and credentials for accessing Thredd services through a single user interface and dashboard.

Migrating your connectivity to Thredd's enhanced Secure Framework and managing your organisation and access through Thredd Portal offers a higher level of assurance and security for your data and services. To learn more, see Thredd Secure Framework.

Who should read this guidance

If you also use Thredd's API Hub for REST APIs, then instead see the following guide: Migrating from mTLS to a new mTLS connection to Thredd and API Hub

This guidance applies to you if you:

  • currently connect to Thredd applications and services using mTLS (Mutual Transport Layer Security)

  • currently use Transport Certificates issued by Raidiam Connect

  • currently use Cloudentity as an identity provider and OAuth OpenID provider

  • Thredd SOAP Web Services

  • will continue to use mTLS — you will change the your Certificate Authority by using certificates issued by Thredd through Thredd Portal

This migration process also applies to you if you use any of the following applications and services (you do not need to be currently using all of these services):

  • Thredd Portal

  • Thredd Smart Client

  • Thredd PAN Finder

  • Webhooks/Event Delivery System (EDS)

  • Thredd's External Host Interface (EHI) application

Migration end state

Once you have completed the migration process, your connectivity to Thredd will comprise mTLS with Client Credentials.

Thredd has prepared updated guidance to help walk you through the migration process. It comprises several stages, depending on the different services that you use.

It will guide you through your migration so that you can use the following services at a minimum:

  • Thredd Portal

  • Thredd SOAP Web Services using a Mutual TLS connection

  • EHI with Mutual TLS (EHIm)

  • Smart Client — existing users only (requires download of the latest version)

  • PAN Finder — existing users only (requires download of the latest version)

You can begin the process of migrating to the Thredd Secure Framework once you receive confirmation from Thredd.

Thredd Portal overview

Thredd Portal is the main entry point to Thredd services and is the main component that is related to identity and access management. Before you can start your migration, your organisation must be set up on Thredd Portal and the Thredd Secure Framework. These combine several components that enable secure access to Thredd's resources, using a common identity store.

This enables you to use the latest version of Thredd Portal for:

  • Managing your organisation, applications, OAuth Client, users and user roles, by your registered Organisation Admin users (all clients).

  • Card and transaction management by users who are assigned an appropriate role (for clients already using Thredd Portal or clients that Thredd has advised can use this functionality).

If you currently use Smart Client to manage cards and transactions, you can continue to do by downloading the latest version. For more information, see Smart Client migration.

This migration process will onboard you to the latest version of Thredd Portal — this includes existing Thredd Portal users and Smart Client users. To learn more, see Thredd Portal overview.

Preparation and testing considerations

This migration process comprises several steps and requires you to update the configuration of your system and how you connect to the Thredd platform. You should prepare for this by reading the migration guidance, so that you can ensure a smooth transition.

For best practice, Thredd recommends that you first set up your organisation's access in the UAT (User Acceptance Test) environment. This enables you to test and verify that your organisation can use Thredd applications and services successfully.

A successful migration to UAT involves replicating production environment settings, but updating environment-specific configurations, and passing your testing. Key tasks during the testing phase include verifying that your organisation can access Thredd applications, such as Thredd Portal, and use SOAP Web Services successfully.

Once you have verified that the migration to the UAT environment is satisfactory, you can coordinate with Thredd and prepare for migrating to Production. You will need to repeat all of these migration steps for Production, ensuring that environment-specification configurations are correct. This includes requesting new certificates and credentials for your client application.

Information for clients using SOAP Web Services

Thredd's SOAP Web Services are secured using Mutual Transport Layer Security (MTLS). Mutual TLS requires your client application to present a trusted Transport Certificate to Thredd for authentication.

If you use Thredd’s SOAP Web Services, the steps to migrate your application and request a Transport Certificate from Thredd are broadly the same as those for using Thredd's REST APIs and API Hub over mTLS. Thredd provides its Certificate Authority through Thredd Portal.

To obtain certificates, you must first set up an Organisation Admin user in Thredd Portal, create an application and OAuth Client, and then request certificates for it.

Overview of the key migration stages

You must complete the following steps:

  1. An Organisation Admin user must set up their access to Thredd Portal and then review details for their organisation's application and OAuth Client. They can also review user access details, depending on whether your organisation's users access Thredd Portal and other services via Single Sign-On (SSO) or use passwords to log in.

  2. Create a new Application and OAuth Client Thredd Portal. You can then request client credentials for your application and configure your client application to provide them when making SOAP calls. This allows Thredd to verify your identity and grant access. See Creating an Application and OAuth Client.

  3. Request the certificates and create credentials that your application requires to access Thredd's SOAP Web Services. See See Requesting certificates for applications using mTLS.

  4. Review and set up access to Thredd Portal and other applications — only if you did not complete this in step 1. An Organisation Admin must set up access to the Thredd platform for their organisation's users.

    • For the SSO method, this involves inviting users to log in to Thredd Portal via your organisation's identity provider. Once users have logged in for the first time, you can assign the appropriate roles to each user to ensure that in they have the appropriate access to Thredd Portal and applications. See Migrating Single Sign-On access and users to the Thredd platform.

    • For the password login method, this involves manually adding users in Thredd Portal. You can assign the appropriate roles to them, and use the built-in invitation feature to send an invite to the user to log in to Thredd Portal. See Migrating password access and users to the Thredd platform.

  5. Migrate other Thredd applications. At a minimum, you must migrate your EHI (EHI with mTLS) configuration.

    Migrating Smart Client (Smart Client users only)

    Clients that use and will continue to use the Smart Client application to manage cards and transactions must update to the latest version of Smart Client.

    For more information, see Smart Client Migration.

    Do not follow this guidance if you use Thredd Portal for your cards and transaction management.

    Migrating PAN Finder (PAN Finder users only)

    Clients that use and will continue to use the PAN Finder application must update to the latest version of PAN Finder. You must already have updated to the latest version of the Smart Client application before installing PAN Finder.

    For more information, see PAN Finder Migration.

    Migrating your EHIm configuration

    Update your EHIm configuration to use the new Thredd EHI Trust Chain. You need to download the new Thredd EHI Trust Chain, configure the changes on your Server to trust it, and ask Thredd to switch the EHI Client Certificate once you are ready.

    For more information, see Migrating to Thredd-issued certificates for EHI with mTLS.

Migrating to Production after successful UAT testing

Once you have verified that the migration to the UAT environment is satisfactory, you can coordinate with Thredd and prepare for migrating to Production. You will need to repeat all of these migration steps for Production, ensuring that environment-specification configurations are correct. This includes requesting new certificates and configuring the latest Postman Collection.