mTLS guide

Introduction

This guide, including the test harness, supports mTLS as of version v1.1. 

The authoritative description of mTLS in PDP is contained in other PDP documents. However, an overview and description is included here to assist participants with system testing.

It is assumed that the reader has a good understanding of mTLS.

Version

This is version 1.1 of the mTLS guide.

Downloads

Download mtls-guide.zip

This zip folder contains:

• 9. MaPS System Testing - error mTLS scenarios.postman_collection (1).json

mTLS overview 

Mutual TLS (mTLS) is used in PDP to ensure that a server will authenticate the client when a TLS connection is being established. This is enforced throughout the PDP architecture. Using mTLS to authenticate clients relies on a chain of trust: checking that the client’s certificate is signed by the PDP certificate authority.

mTLS connections are used in the following places:

• dashboard -> data pension provider (for example, for sending ‘view’ requests).
• dashboard -> consent and authorisation API
• data pension provider -> consent and authorisation API
• pension finder service (PFS) -> data pension provider (for ‘find’ requests).

The guide supports mTLS, in a similar way to the real system. Benefits of this include:

1. Testing the use of mTLS during system testing will give earlier feedback, helping to reduce errors and delays during the subsequent onboarding and integration testing.
2. Without mTLS support, the system-under-test would have to be configured into a “test-mode” that did not enforce mTLS.

Crypto material 

The use of mTLS during the system testing is designed to mirror the onboarding and integration testing as closely as possible.

Crypto pack for system testing 

Similar to onboarding, participants are given a cypto pack by MaPS for use during system testing. The pack contains the following files: 

certificate

Format: PEM.

Purpose: An X.509 transport certificate for mTLS connections .

certificateChain   

Format: PEM .

Purpose: An ordered list of:  

• SSL certificate 
• certificate authority certificate  

For the receiver to authenticate the certificate authority which issues the rest of the X.509 certificates.

certPrivateKey 

Format: PEM.

Purpose: The private key used to sign the CSR that was used to generate the transport certificate (key pair with the certPublicKey).

certPublicKey 

Format: PEM.

Purpose: The certificate public key (key pair with the certPrivateKey).

jwtPrivateKey

Format: PEM.

Purpose: A private key to sign any payloads that you may returned as JWT (key pair with the jwtPublicKey).

jwtPublicKey

Format: PEM.

Purpose: The public key to enable verification of JWT payload signing (key pair with the jwtPrivateKey).

kid

Format: GUID.

Purpose: The key id of the jwtPublicKey in the central JWKS endpoint (exposed by the test harness).

Supplementary crypto material for system testing 

There is also supplementary crypto material for system testing. This additional material is to be used in Postman when running various mTLS test scenarios.

postmanCertificate_valid.pem

Purpose: A transport certificate for mTLS connections.

postmanCertificate_valid.pem.key

Purpose: The private key, to accompany the postmanCertificate_valid.pem.

postmanCertificate_invalid.pem

Purpose: A transport certificate for mTLS connections. However, this is generated by an untrusted certificate authority Root.

postmanCertificate_invalid.pem.key

Purpose: The private key, to accompany the postmanCertificate_invalid.pem.

postmanCertificate_expired.pem

Purpose: A transport certificate for mTLS connections. Though generated by a trusted certificate authority Root, this certificate has expired.

postmanCertificate_expired.pem.key

Purpose: The private key, to accompany the postmanCertificate_expired.pem.

System testing configuration 

System-under-test 

The system-under-test must be configured in the standard way, using the crypto pack that is provided for system testing. There is separate guidance from MaPS for this, not included in this document.

However, some key points are highlighted below:

• Authenticating client connections:
  • The system-under-test must add the certificateChain to its trust store, in order to authenticate clients.
  • The system-under-test must only accept connections from clients with a certificate generated by the MaPS certificate authority (which is given in the certificateChain).
• Sending requests to the consent and authorisation Stub:
  • The system-under-test must use the certPublicKey and certPrivateKey when sending http requests to the consent and authorisation Stub, and must do so over the https. If this is not done, mTLS connections will be rejected.
• System-under-test Server certificate:
  • It is expected that the system-under-test has a certificate from a public certificate authority, which matches the domain on which the system-under-test is listening. This will be the basis of trust from the client’s perspective (for example, when Postman is sending ‘find’ and ‘view’ requests). However, see Appendix A: use of private certificate authority
  • It is the participant’s responsibility to generate and configure a valid server certificate for the system-under-test.

Postman configuration

For system testing, Postman is used to send ‘find’ and ‘view’ requests to the system-under-test for each of the test scenarios. Thus Postman must be configured to use mTLS: it must be configured with the client certificate and key.

The supplementary crypto material for system testing includes the certificate and key files to use for configuring Postman.

For details of setting this up, see the official Postman documentation.

However, some points are highlighted below, along with a screenshot of Postman configuration:

• Configuring the client certificate:
  • When adding a client certificate to Postman, the host is required. This is the server host that requests are being sent to (the domain name of the system-under-test that requests will be sent to).
  • The “CRT file” is the “.pem” file.
  • The “KEY file” is the “.pem.key” file.
  • There is no passphrase for the keys in the supplementary crypto material.
• Use https:
  • When setting the URL for the system-under-test, ensure that https is used.
• Testing different mTLS error scenarios:
  • The mTLS configuration is ‘global’ - it is not specific to a test suite. Therefore, to test different error scenarios (for example, an invalid certificate or an expired certificate) requires that Postman be reconfigured between each test case.

Consent and authorisation stub 

For details of mTLS configuration in the consent and authorisation stub, see the test harness administrator guide.

Online Certificate Status Protocol (OCSP): certificate revocation 

Note that mTLS OCSP is not supported for system testing in v1.1 of the test pack.

OCSP is used to handle certificate revocation in the production PDP system, and also in the integration testing environment.

In the production system, the system-under-test must check that the client certificate has not been revoked when accepting the TLS connection.

mTLS checklist for system testing 

The steps include the following:

1. Generate a server certificate for the system-under-test, for the domain on which it will be reached.
2. Generate a server certificate for the consent and authorisation stub, for the domain on which it will be reached.
3. Configure the system-under-test, using the supplied crypto pack for system testing and using the generated server certificate.
4. Configure the consent and authorisation stub container with the generated server certificate, and run the container.
5. Configure Postman with the mTLS client certificate and key.
6. Run the test scenarios, collect evidence, and submit to MaPS.

Appendix A: use of private certificate authority

Some organisations may only use an internal private certificate authority for test environments, rather than generating certificates from a public certificate authority. If this is company policy, then a private certificate authority may have to be used to generate the server certificates for both the system-under- test and for the consent and authorisation stub.

Note that the participant’s production system must be reachable from the pension finder service (PFS) and from dashboards, so must be publicly available and must have a TLS server certificate from a public certificate authority.

If a private certificate authority is used to generate the server certificate that is injected into the consent and authorisation stub, then the system-under-test must be configured to trust this. The private certificate authority’s certificate chain must be added to the trust store of the system-under-test.

If a private certificate authority is used for the system-under-test’s TLS server certificate, then Postman must be configured accordingly (because it sends ‘find’ and ‘view’ requests). The private certificate authority’s certificate chain must be added to Postman’s trust store, or to the trust store of the operating system on which the trust store of the system-under-test.