Copy page

Securing Your Backend

Gateway to Origin mTLS Authentication

Mutual TLS (mTLS) authentication establishes a trust relationship between your Zuplo API Gateway and your backend services using client certificates. With mTLS, both the client (Zuplo Gateway) and the server (your backend) authenticate each other, creating a "Zero Trust" security model.

This is particularly useful for enterprise customers who need to ensure that both parties in a connection verify each other's identity before exchanging data.

How mTLS Works

When Zuplo makes an outbound request to your backend service:

1. Your backend service presents its SSL/TLS certificate to Zuplo (standard TLS)
2. Zuplo presents a client certificate to your backend (the mutual part)
3. Both parties verify each other's certificates against a trusted Certificate Authority (CA)
4. Only after mutual verification does the secure connection establish

This ensures that your backend only accepts requests from authorized Zuplo gateways, and Zuplo can verify it's connecting to the correct backend service.

Prerequisites

Before you begin, you need:

• A PEM-encoded client certificate and matching private key generated from a Certificate Authority (CA) that your backend trusts
• Your backend service configured to require and validate client certificates
• The Zuplo CLI installed (see CLI documentation)

Client certificate requirements

The certificate uploaded to Zuplo is the client, or leaf, certificate that the gateway presents to your backend. It should have the following properties:

• X.509 version 3
• Basic Constraints: critical, CA:FALSE
• Key Usage: critical, Digital Signature
• Extended Key Usage: TLS Web Client Authentication (clientAuth)
• An RSA key between 2048 and 8192 bits, or an ECDSA key using P-256, P-384, or P-521
• A SHA-256 or stronger signature
• A subject that uniquely identifies the gateway credential
• A validity period appropriate for your certificate rotation policy

The issuing CA certificate must be X.509 version 3 with Basic Constraints: critical, CA:TRUE and a key usage that includes Certificate Sign and CRL Sign. Your backend's trust store must contain the CA certificates needed to build a path from the client certificate to a trusted root. When the trusted CA directly signs the client certificate, you do not need a client certificate-chain bundle. If an intermediate CA signs it, follow your backend's requirements for presenting and trusting the intermediate chain.

The private key must match the public key in the client certificate. Keep it secret and limit access to it. The key must be unencrypted when uploaded to Zuplo so the gateway can use it without a passphrase.

1/ Upload Your Certificate

Use the Zuplo CLI to upload your client certificate and private key to your project. You can upload multiple certificates, each with a unique name.

Code
zuplo mtls-certificate create \
  --cert cert.pem \
  --key key.pem \
  --name my-backend-cert \
  --account your-account \
  --project your-project \
  --environment-type development \
  --environment-type preview \
  --environment-type production

Parameters:

• --cert: Path to your PEM-encoded client certificate file
• --key: Path to your PEM-encoded private key file
• --name: A unique name to identify this certificate in your project
• --account: Your Zuplo account name
• --project: Your Zuplo project name
• --environment-type: Specify which environments can use this certificate (can be specified multiple times)

2/ Use the Certificate in Your Code

Once uploaded, you can use the certificate when making outbound requests from your Zuplo Gateway.

Using mTLS in a Request Handler

Reference the certificate by name in the zuplo options object when making fetch requests:

Code
import { ZuploContext, ZuploRequest } from "@zuplo/runtime";

export default async function (request: ZuploRequest, context: ZuploContext) {
  const response = await fetch("https://secure-backend.example.com/api", {
    zuplo: {
      mtlsCertificate: "my-backend-cert",
    },
  });

  return response;
}

Using mTLS in a Policy

You can also configure mTLS in the URL Forward Handler or URL Rewrite Handler that make outbound requests:

Code
{
  "export": "UrlForwardHandler",
  "module": "$import(@zuplo/runtime)",
  "options": {
    "baseUrl": "https://secure-backend.example.com",
    "mtlsCertificate": "my-backend-cert"
  }
}

3/ Using Environment Variables

For better flexibility across environments, store the certificate name as an environment variable:

Production environment:

Code
BACKEND_MTLS_CERT=my-backend-prod-cert

Staging environment:

Code
BACKEND_MTLS_CERT=my-backend-staging-cert

Then reference it in your code:

Code
import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";

export default async function (request: ZuploRequest, context: ZuploContext) {
  const response = await fetch("https://secure-backend.example.com/api", {
    zuplo: {
      mtlsCertificate: environment.BACKEND_MTLS_CERT,
    },
  });

  return response;
}

Or in your policy configuration:

Code
{
  "export": "UrlForwardHandler",
  "module": "$import(@zuplo/runtime)",
  "options": {
    "baseUrl": "https://secure-backend.example.com",
    "mtlsCertificate": "$env(BACKEND_MTLS_CERT)"
  }
}

Managing Certificates

Listing Certificates

To view all certificates in your project:

Code
zuplo mtls-certificate list \
  --account your-account \
  --project your-project

Deleting Certificates

To remove a certificate:

Code
zuplo mtls-certificate delete \
  --cert-id my-cert-id \
  --account your-account \
  --project your-project

Certificate Rotation

When your certificates need to be rotated (due to expiration or security policies):

1. Upload the new certificate with a different name
2. Update your environment variables or code to reference the new certificate name
3. Use the CLI zuplo mtls-certificate disable command to disable the old certificate.
4. Deploy your changes to all environments that reference the old certificate.
5. After verifying the new certificate works, you may delete the old certificate.

The order of operations is important so that your services continue to work as you rotate the certificate.

Local Development

For local development, consider:

• Using conditional logic to bypass mTLS when running locally
• Setting up a separate backend endpoint that doesn't require mTLS for development
• Testing mTLS functionality in a preview environment

Troubleshooting

Certificate Validation Errors

Inspect the certificate and confirm its subject, issuer, validity, and client authentication purpose:

Code
openssl x509 \
  -in client.crt \
  -noout \
  -subject \
  -issuer \
  -serial \
  -dates \
  -purpose

SSL client should report Yes. To inspect all extensions, run openssl x509 -in client.crt -noout -text and confirm the certificate reports CA:FALSE, Digital Signature, and TLS Web Client Authentication.

Check that the certificate will remain valid for at least seven days:

Code
openssl x509 -in client.crt -noout -checkend 604800

Validate the certificate path against the same CA bundle your backend trusts:

Code
openssl verify \
  -verbose \
  -purpose sslclient \
  -x509_strict \
  -show_chain \
  -CAfile backend-client-ca-bundle.pem \
  client.crt

The expected result is client.crt: OK. Common errors include:

• unable to get local issuer certificate: The issuing CA or an intermediate CA is missing from the backend's trust bundle.
• unsupported certificate purpose: The client certificate is missing the clientAuth extended key usage.
• certificate has expired: The client certificate is outside its validity period.
• invalid CA certificate: An issuing certificate is missing valid CA extensions.
• key usage does not include certificate signing: An issuing CA does not have the keyCertSign key usage.

Confirm that the certificate and private key contain the same public key:

Code
CERT_KEY_HASH=$(openssl x509 -in client.crt -noout -pubkey | openssl sha256)
PRIVATE_KEY_HASH=$(openssl pkey -in client.key -pubout | openssl sha256)

test "$CERT_KEY_HASH" = "$PRIVATE_KEY_HASH" &&
  echo "Certificate and private key match" ||
  echo "ERROR: Certificate and private key do not match"

If your backend still rejects the certificate, verify:

• The certificate is signed by a CA that your backend trusts
• The certificate hasn't expired
• The certificate has the required key usage and extended key usage
• The certificate and private key match
• The certificate name in your code matches the uploaded certificate name

Connection Failures

If requests fail to connect:

• Ensure your backend is configured to accept mTLS connections
• Verify the certificate is uploaded to the correct environment (development, preview, production)
• Check that your backend's CA certificate is properly configured

Runtime Errors

If you see errors about missing certificates:

• Confirm the certificate was uploaded successfully using zuplo mtls-certificate list
• Ensure the environment type was specified correctly during upload
• Verify your code references the correct certificate name

Additional Resources

For more information on securing your backend, see:

• Securing your Backend - Overview of all backend security options
• Shared Secret / API Key - Alternative approach using shared secrets
• Secure Tunnels - Connect to private backends without exposing them to the internet
• Client mTLS Authentication - The reverse direction, where clients authenticate to your Zuplo gateway with a client certificate

If you need assistance configuring mTLS for your project, contact us at support@zuplo.com.