Skip to main content

Implementing mTLS with Threat Protection

This guide explains how to configure mutual TLS (mTLS) for your traffic. mTLS ensures that not only is your traffic encrypted, but both parties in a network connection verify each other's identities using digital certificates.

In the Threat Protection ecosystem, mTLS is handled in two independent segments. You can implement either one or both.

The Two Segments of mTLS​

1. Client-to-Proxy mTLS (Downstream)​

The Threat Protection Proxy acts as the "Server." It presents a certificate to the client, and in turn, requires the client to present a valid certificate signed by a Certificate Authority (CA) that you trust.

  • Use Case: Restricting access to your application to only specific authorized devices or users.

2. Proxy-to-Origin mTLS (Upstream)​

The Threat Protection Proxy acts as the "Client." It presents a certificate to your backend (Origin) server. Your origin server can then verify that the traffic is coming specifically from Threat Protection.

  • Use Case: Ensuring your backend only accepts traffic that has been inspected and cleaned by Threat Protection.

Minimum Requirements​

For either mTLS segment, the proxy must be configured for HTTPS.

You can do this either by bringing your own certificate or using Let's Encrypt via Threat Protection.

Uploading a CA Certificate​

CA Certificates can be used to validate client TLS certificates or origin server TLS certificates.

You can upload a CA certificate via a POST request to POST /api/v2/traffic-mgmt/ca-certificates as follows:

curl -X POST "https://portal.baffinbay.com/api/v2/traffic-mgmt/ca-certificates" \
     -H "Content-Type: application/vnd.api+json" \
     -d '{
  "data": {
    "type": "caCertificate",
    "attributes": {
      "certificates": [
        { 
            "certificate": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
            "crlUrl": "http://some.cert.revocation.list.crl"
        }
      ]
    },
    "relationships": {
      "belongsTo": { "data": { "type": "account", "id": "YOUR_ACCOUNT_ID" } }
    }
  }
}'

Client-to-Proxy mTLS​

Client TLS certificates will need to be verified by a CA Certificate of your choosing.

1. Upload a CA Certificate to validate client TLS certificates​

See Uploading a CA Certificate.

2. Update the proxy to validate client TLS certificates​

You can either update the whole proxy configuration at /api/v2/traffic-mgmt/traffic-configs/{id} via PUT or just simply PATCH the relevant parts as the following example:

curl -X PATCH "https://portal.baffinbay.com/api/v2/traffic-mgmt/traffic-configs/{id}" \
     -H "Content-Type: application/vnd.api+json" \
     -d '{
        "data": {
            "type": "httpProxy",
            "attributes": {
                "frontend": {
                    "clientCertificateVerification": {
                        "mode": "VERIFY_AND_REJECT",
                        "caCertificateIds": ["CLIENT_CA_ID"],
                        "verifyCrl": true
                    }
                }
            }
        }
}'

Proxy-to-Origin Server mTLS​

To set up server side mTLS, the proxy must present a TLS certificate and so must the origin server. The proxy can optionally validate the origin server's TLS certificate using our Trust Store of well-known CAs, or using your own Trust Store of CA Certificates.

1. Set up proxy-to-server TLS certificate​

Threat Protection only supports bringing your own certificate for the proxy to present a TLS certificate to the origin server.

2. Set up origin server to validate proxy TLS certificate​

3. (Optional) Upload CA Certificates to validate origin server TLS certificates​

See Uploading a CA Certificate.

4. Update the proxy to present a TLS certificate to the origin server​

In all of the scenarios below, at least regular TLS must be configured on the client side.

4.a. No validation of origin server TLS certificates​

If you prefer to not validate the origin server, you can update the proxy configuration as follows:

curl -X PATCH "https://portal.baffinbay.com/api/v2/traffic-mgmt/traffic-configs/{id}" \
     -H "Content-Type: application/vnd.api+json" \
     -d '{
    "data": {
        "type": "httpProxy",
        "attributes": {
            "backend": {
                "hosts": [
                    {
                        "address": "ORIGIN_ADDRESS",
                        "port": ORIGIN_PORT
                    }
                ],
                "deliveryMethod": "LEAST_CONNECTIONS",
                "tlsSettings": {
                    "clientCertificateId": "PROXY_TO_ORIGIN_TLS_CERT_ID"
                }
            }
        }
    }
}'

4.b. Validate origin server TLS certificates using the Threat Protection Proxy Store​

curl -X PATCH "https://portal.baffinbay.com/api/v2/traffic-mgmt/traffic-configs/{id}" \
     -H "Content-Type: application/vnd.api+json" \
     -d '{
    "data": {
        "type": "httpProxy",
        "attributes": {
            "backend": {
                "hosts": [
                    {
                        "address": "ORIGIN_ADDRESS",
                        "port": ORIGIN_PORT
                    }
                ],
                "deliveryMethod": "LEAST_CONNECTIONS",
                "tlsSettings": {
                    "verifyCertificate": {
                        "mode": "SYSTEM_TRUSTSTORE"
                    },
                    "clientCertificateId": "PROXY_TO_ORIGIN_TLS_CERT_ID"
                }
            }
        }
    }
}'

4.c. Validate origin server TLS certificates using a custom Trust Store​

This requires that at least one CA Certificate is set up as described in Uploading a CA Certificate.

curl -X PATCH "https://portal.baffinbay.com/api/v2/traffic-mgmt/traffic-configs/{id}" \
     -H "Content-Type: application/vnd.api+json" \
     -d '{
    "data": {
        "type": "httpProxy",
        "attributes": {
            "backend": {
                "hosts": [
                    {
                        "address": "ORIGIN_ADDRESS",
                        "port": ORIGIN_PORT
                    }
                ],
                "deliveryMethod": "LEAST_CONNECTIONS",
                "tlsSettings": {
                    "verifyCertificate": {
                        "mode": "CUSTOM_TRUSTSTORE",
                        "caCertificateIds": ["CA_CERT1_ID", "CA_CERT2_ID", ...]
                    },
                    "clientCertificateId": "PROXY_TO_ORIGIN_TLS_CERT_ID"
                }
            }
        }
    }
}'