Mutual TLS configuration

Mutual TLS authentication

Mutual authentication requires both communicating parties to verify each other's identity. Unlike standard HTTPS, the gateway verifies the backend service, and the backend service verifies the gateway. An encrypted channel is established only after both verifications succeed.

This mechanism suits service-to-service communication with high security requirements. When the gateway connects to a backend service, the process has three phases:

1. Certificate exchange: The backend service sends its server certificate to the gateway for validation. The gateway then sends its client certificate to the backend service for validation.

2. Key negotiation: Both parties use the other's public key to encrypt and exchange key materials, then independently compute the same session key.

3. Encrypted channel establishment: Both parties use the session key to encrypt all subsequent data transmissions.

Before you begin

To configure mutual authentication, you must prepare the following three types of certificates:

• Gateway client certificate (client.crt): Identifies the gateway. This certificate must be uploaded to the console and selected in the Certificate ID field.

• Root certificate (ca.crt): Validates the backend service's certificate. This certificate must be pasted into the CA Certificate field and also configured on the backend service.

• Backend service certificate (server.crt): Identifies the backend service. This certificate must be configured on the backend service, such as Nginx.

For a test environment, see the appendix for instructions on how to generate self-signed certificates.

Important: The gateway and the backend service must use the same root certificate trust chain. Otherwise, they cannot verify each other's identity.

Configure mutual authentication on the console

After you prepare the certificates, sign in to the gateway console. On the Create Service page, configure the following settings:

Review the settings and click OK to save the service configuration.

Configure the backend service

After you configure the gateway, configure the backend service to enable mTLS. This is typically handled by an operations team.

For example, if your backend service uses Nginx as a reverse proxy, enable client certificate verification by adding the following directives to the server block:

server {
    listen 443 ssl;
    server_name api.example.com;

    # Server certificate
    ssl_certificate     /etc/nginx/ssl/server.crt;
    ssl_certificate_key /etc/nginx/ssl/server.key;

    # Enable client certificate verification (critical configuration)
    ssl_verify_client on;
    ssl_client_certificate /etc/nginx/ssl/ca.crt;

    location / {
        proxy_pass http://localhost:8080;
    }
}

The ssl_verify_client on directive requires all clients to present a valid client certificate. The ssl_client_certificate directive specifies the CA certificate file used to validate client certificates. This file must contain the root certificate that issued the gateway's client certificate.

After modifying the configuration, you must restart the Nginx service to apply the changes.

Verify the configuration

After you configure the gateway and backend service, verify the setup:

Console test: Create a route and send a test request. A successful response indicates the configuration is correct. If you receive a 400, 403, or SSL error, check your certificate configuration.

Command-line test:

curl --cert client.crt --key client.key https://api.example.com/test

A successful response confirms the configuration is correct. If the service rejects requests without a certificate, mutual authentication is active.

Check the backend service access logs to confirm the request arrived. If an SSL handshake failure occurs, verify that the backend's CA certificate matches the gateway's client certificate.

Appendix: Generate test certificates

To validate the feature in a test environment, generate self-signed certificates with the following commands. Run these on a Linux or macOS system with OpenSSL installed.

First, generate the private key file for the root certificate. Run the following command:

openssl genrsa -out ca.key 2048

This command generates a 2048-bit RSA private key and saves it to the ca.key file.

Next, use this private key to create a self-signed root certificate:

openssl req -new -x509 -key ca.key -out ca.crt -days 3650 \
  -subj "/C=CN/O=Test/CN=RootCA"

The days parameter sets the certificate validity to 3650 days. Customize the subject fields such as country (C), organization (O), and common name (CN) as needed.

Next, generate the server certificate for the backend service. First, generate the private key:

openssl genrsa -out server.key 2048

Then, create a certificate signing request. The Common Name (CN) must match the actual domain name of your backend service.

openssl req -new -key server.key -out server.csr \
  -subj "/C=CN/O=Test/CN=api.example.com"

Note: Change the CN value to your own domain name.

Finally, use the root certificate to sign the server certificate:

openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out server.crt -days 3650

Similarly, generate a client certificate for the gateway. Generate the private key:

openssl genrsa -out client.key 2048

Create a certificate signing request:

openssl req -new -key client.key -out client.csr \
  -subj "/C=CN/O=Test/CN=Gateway"

Then, sign the certificate:

openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out client.crt -days 3650

After you complete these steps, you have three certificate files: ca.crt, server.crt, and client.crt. The following table shows where to use each certificate and its private key.

With this setup, mutual authentication will work correctly in your test environment.