Mutual Transport Layer Security

​

Overview

• Operate under zero-trust security frameworks
• Have strict compliance requirements such as SOC2, ISO 27001, or HIPAA
• Restrict API access to specific authenticated services or devices
• Require network-layer security controls in addition to application authentication
• Enforce different trust policies for various environments (development, staging, production)

​

Common use cases

• Enterprise API security: Restrict Fusion API access to only authenticated services within your infrastructure. Services must present a valid client certificate signed by your organization’s certificate authority (CA).
• Multi-environment access control: Enforce different certificate requirements for development, staging, and production environments. Development might use self-signed certificates while production requires certificates from your enterprise public key infrastructure (PKI).
• Compliance and audit: Meet regulatory requirements for network-layer authentication. All client certificate usage is logged in Google Cloud Logging for audit purposes.
• Zero-trust architecture: Implement defense-in-depth security where every connection must be authenticated at both network and application layers.

​

Authentication flow

​

Prerequisites

​

Configure certificate infrastructure

• Certificate Authority (CA): Establish access to a trusted CA for signing client certificates
  • Option 1: Use your organization’s existing PKI infrastructure
  • Option 2: Use Google Cloud Certificate Authority Service (platform-managed)
• CA Certificate: Configure a privacy enhanced mail (PEM) encoded root or intermediate CA certificate to use as a trust anchor
• Client Certificates: Set up the ability to generate and distribute PKCS#12 (.p12) or PEM certificates to clients

​

Configure access and permissions

• Administrative access to the applicable Fusion environment
• Ability to upload CA certificates to Google Cloud
• Permissions to configure load balancer settings

​

Client capabilities

• Client configuration must support TLS 1.2 or later
• Client systems must be able to load and present client certificates
• For browser access, users need certificates imported to their browser’s certificate store
• For API access, applications need certificate configuration in their HTTP client

​

Configuration

​

Configuration steps

1. Provide CA Certificate: Supply your organization’s CA certificate (PEM format) as a trust anchor.
2. Configure TrustConfig: Load balancer TrustConfig is updated with your CA certificate.
3. Enable mTLS Policy: Server TLS policy is set to MTLS mode with REJECT_INVALID validation.
4. Testing: Verify mTLS enforcement in a non-production environment first.
5. Certificate Distribution: Distribute client certificates to your users and services.
6. Production Rollout: Enable mTLS for production after successful testing.

​

Trust configuration options

​

Using mTLS

​

Browser access

1. Import certificate: Import the PKCS#12 (.p12) certificate into your browser’s certificate store. These are the access paths for the specified browser:
   • Chrome/Edge: Settings > Privacy and security > Security > Manage certificates.
   • Firefox: Settings > Privacy & Security > Certificates > View Certificates > Your Certificates > Import.
   • Safari: Use the macOS Keychain Access to import the certificate.
2. Access Fusion: Navigate to your Fusion URL.
3. Certificate selection: Select the certificate provided by your administrator. If prompted, confirm the certificate usage.
4. Authenticated access: When the certificate is validated, access Fusion.

​

API access

# Use PEM certificate and key
curl -X GET \
  --cert CLIENT_CERT.pem \
  --key CLIENT_KEY.pem \
  https://YOUR_INSTANCE.lucidworks.cloud/api/apps

# Use PKCS#12 certificate
curl -X GET \
  --cert-type P12 \
  --cert CLIENT_CERT.p12:PASSWORD \
  https://YOUR_INSTANCE.lucidworks.cloud/api/apps

import requests

# Use PEM certificate and key
response = requests.get(
    'https://YOUR_INSTANCE.lucidworks.cloud/api/apps',
    cert=('CLIENT_CERT.pem', 'CLIENT_KEY.pem')
)

# Use PKCS#12 certificate (requires requests_pkcs12)
from requests_pkcs12 import get

response = get(
    'https://YOUR_INSTANCE.lucidworks.cloud/api/apps',
    pkcs12_filename='CLIENT_CERT.p12',
    pkcs12_password='PASSWORD'
)

import javax.net.ssl.*;
import java.security.KeyStore;
import java.io.FileInputStream;

// Load PKCS#12 keystore
KeyStore keyStore = KeyStore.getInstance("PKCS12");
keyStore.load(new FileInputStream("CLIENT_CERT.p12"),
              "password".toCharArray());

// Create KeyManagerFactory
KeyManagerFactory kmf = KeyManagerFactory.getInstance(
    KeyManagerFactory.getDefaultAlgorithm());
kmf.init(keyStore, "password".toCharArray());

// Create SSLContext
SSLContext sslContext = SSLContext.getInstance("TLS");
sslContext.init(kmf.getKeyManagers(), null, null);

// Use with HttpsURLConnection or HTTP client
HttpsURLConnection.setDefaultSSLSocketFactory(
    sslContext.getSocketFactory());

const https = require('https');
const fs = require('fs');

const options = {
  hostname: 'YOUR_INSTANCE.lucidworks.cloud',
  path: '/api/apps',
  method: 'GET',
  cert: fs.readFileSync('CLIENT_CERT.pem'),
  key: fs.readFileSync('CLIENT_KEY.pem'),
  ca: fs.readFileSync('CA_CERT.pem') // optional
};

const req = https.request(options, (res) => {
  console.log('statusCode:', res.statusCode);
  res.on('data', (d) => {
    process.stdout.write(d);
  });
});

req.end();

​

Certificate management

1. Generate new certificates from the same CA.
2. Distribute new certificates to clients.
3. Clients update to use new certificates.

4. Remove old certificates after all clients have migrated.

1. Revoke the certificate by updating the TrustConfig.
2. Issue replacement certificates from the CA.
3. Update all affected clients.

​

Security considerations

• Application authentication: Continue using SSO, OIDC, or JWT tokens.
• Authorization: Enforce role-based access control (RBAC).
• Network security: Use IP allowlisting where appropriate.
• Data encryption: Confirm all traffic is encrypted via TLS 1.2+.

​

Certificate storage

• Protect private keys
  • Never commit certificates or private keys to source control.
  • Store certificates in secure key management systems such as HashiCorp Vault, AWS Secrets Manager, and others.
  • Use environment variables or secure configuration files for deployment.
  • Restrict file system permissions on certificate files such as chmod 600.
• Environment recommendations Follow these guidelines to secure different environments:
  • Use separate certificate authorities or intermediate CAs for different environments.
  • Production certificates should have stricter issuance policies.
  • Development/testing can use self-signed certificates if approved by security team.

​

Monitoring and logging

• Successful certificate validations
• Failed authentication attempts
• Certificate validation errors

• Unusual patterns in failed authentication attempts
• Upcoming certificate expirations
• Certificate validation errors

​

Troubleshooting

​

Connection refused or certificate errors

• Client certificate not signed by trusted CA
• Certificate expired
• Certificate not properly configured in client
• Wrong certificate selected (browser)
• Certificate format mismatch (PEM vs PKCS#12)

1. Verify the certificate is signed by the CA configured in TrustConfig.
2. Check the certificate expiration date: openssl x509 -in client-cert.pem -noout -dates.
3. Verify the certificate chain is complete: openssl verify -CAfile ca-cert.pem client-cert.pem.
4. Test the certificate with curl: curl -v --cert CLIENT_CERT.pem --key CLIENT_KEY.pem https://YOUR_INSTANCE.lucidworks.cloud.

​

Browser not prompting for certificate

• Certificate not imported to browser certificate store
• Certificate imported to wrong store, for example, to the CA certificates instead of the client certificates
• Browser cached a previous certificate selection

1. Verify the certificate is in browser’s personal/client certificate store.
2. Clear the browser cache and cookies.
3. Try a private or incognito window.
4. Re-import the certificate, if necessary.

​

Certificate works in testing but not production

• Different CA certificates configured per environment
• Certificate signed by wrong CA
• TrustConfig not updated in production

1. Verify the same CA certificate is configured in both environments.
2. Check the certificate’s issuer: openssl x509 -in CLIENT_CERT.pem -noout -issuer.
3. Verify the TrustConfig settings.

​

Application cannot load certificate

• Incorrect file path
• Insufficient file permissions
• Certificate format not supported by library
• Missing intermediate certificates

1. Verify the file exists and is readable: ls -la CLIENT_CERT.pem.
2. Check the certificate’s format: openssl x509 -in CLIENT_CERT.pem -noout -text.
3. For PKCS#12, verify the password is correct.
4. Ensure the certificate chain includes all intermediate certificates.
5. Convert between formats if needed:
   • PEM to PKCS#12: openssl pkcs12 -export -out cert.p12 -inkey key.pem -in cert.pem
   • PKCS#12 to PEM: openssl pkcs12 -in cert.p12 -out cert.pem -nodes

​

Frequently asked questions

• Mobile Device Management (MDM) systems for employee devices
• Configuration management tools for servers such as Ansible, Puppet, and Chef
• Secure file sharing with password-protected archives
• Hardware security modules (HSMs) or smart cards for high-security environments

​

Related topics

• Security Overview for comprehensive security features
• Access Control for user authentication and authorization
• Security Realms for authentication providers
• Monitoring for monitoring and alerting