Mutual TLS Testing Setup Guide

Overview

This guide explains how to set up and test the Mutual TLS (mTLS) functionality in the DIBBs Query Connector.

Prerequisites

1. Obtain mTLS Certificates

You'll need a certificate and private key pair for mTLS authentication. These can be:

For Development/Testing: VAL environment certificates signed by the EMR Direct Certificate Authority
For Production: PROD environment certificates signed by the EMR Direct Certificate Authority

Getting Certificates

Follow the instructions from EMR Direct to obtain your mTLS certificates.

### 2. Certificate Placement

The application looks for certificates in two places:

1. **File System** (preferred for development):

   - Place certificates in the `keys/` directory at the project root
   - Files should be named:
     - `mtls-cert.pem` - Certificate file
     - `mtls-key.pem` - Private key file

2. **Environment Variables** (preferred for production):

   - For ease of configuration, the env vars are required to be base-64 encoded.
   - Configure your env vars with the encoding method of your choice according to the below:
   ```bash
   export MTLS_CERT="base64Encode(-----BEGIN CERTIFICATE-----
   [certificate content]
   -----END CERTIFICATE-----)"

   export MTLS_KEY="base64Encode(-----BEGIN PRIVATE KEY-----
   [private key content]
   -----END PRIVATE KEY-----)"

Running Tests

Unit Tests

# Run all mTLS-related unit tests
npm run test:unit -- mtls

# Run specific test files
npm run test:unit -- src/app/shared/mtls-utils.test.ts
npm run test:unit -- src/app/backend/fhir-servers.test.ts
npm run test:unit -- src/app/shared/fhirClient.test.ts

Integration Tests

# Run integration tests including mTLS functionality
npm run test:integration

End-to-End Tests

# Run E2E tests with mTLS servers
npm run test:playwright -- mtls.spec.ts

Manual Testing with eHealthExchange

1. Configure an mTLS-enabled FHIR Server

Navigate to /fhirServers in the application
Click "New server"
Fill in server details:
- Server name: "eHX VAL (mTLS)"
- URL: https://fhir002val.ehealthexchange.org/ehx/1.0/r4/cdex
- Auth Method: None
- Enable Mutual TLS: Check this box
- Custom Headers: Add any required headers
Click "Test connection" to verify
Click "Add server" to save

2. Test Patient Discovery

Navigate to the main query page
Fill in patient demographics
- First Name: Rick943
- Last Name: Prohaska837
- DOB: 01-05-1963
- Phone Number: 555-306-8493
- State: MA
Click "Advanced" and select your mTLS server
Click "Search for patient"
The application will:
- Create a Task resource via POST to /Task
- Poll for child task completion
- Retrieve patient results from completed tasks

Troubleshooting

Certificate Not Found Error

If you see "Mutual TLS certificate not found" error:

Check that certificates exist in keys/ directory:
```
ls -la keys/mtls-*
```

Verify environment variables are set:

echo $MTLS_CERT | head -n 1
echo $MTLS_KEY | head -n 1

Ensure certificates have correct permissions:

chmod 600 keys/mtls-key.pem
chmod 644 keys/mtls-cert.pem

Connection Refused

If the mTLS connection is refused:

Verify the server actually requires mTLS
Check that your certificate is trusted by the server
Ensure the certificate CN or SAN matches what the server expects
Try disabling certificate validation for testing (not recommended for production)

Task Polling Timeout

If tasks don't complete:

Check the server's Task implementation
Verify the server supports the Task profile being used
Look for error messages in child tasks
Check server logs for processing errors

Security Considerations

Never commit certificates to version control
- The keys dir has been added to .gitignore - keep it there!
- Use environment variables in production
Certificate Rotation
- Plan for certificate expiration
- Implement a process for updating certificates
- Test certificate updates in a staging environment