Client mTLS Authentication

Client mTLS authentication lets your Zuplo gateway verify the identity of clients calling your API using certificates issued by your own Certificate Authority (CA). Both the client and the gateway authenticate each other during the TLS handshake, so only clients holding a certificate signed by your CA can reach your API.

How Client mTLS Works

When a client calls your Zuplo gateway:

1. The client presents a certificate issued by your CA during the TLS handshake.
2. Zuplo's edge verifies the certificate against the CA you've uploaded and passes the verification result (and parsed certificate) to your gateway workers.
3. The mtls-auth-inbound policy on your route reads the verification result, enforces it, and attaches the parsed certificate metadata to request.user.data.mtlsAuth for use in your handlers and downstream policies.

CA certificates are scoped to your Zuplo account, not a single project or deployment. Once a CA is uploaded, every gateway domain on the account will verify presented client certificates against it. The policy on each route controls whether unverified traffic is rejected or allowed through.

Prerequisites

Before you begin, you need:

• A public CA certificate (PEM-encoded) that issued — or will issue — the client certificates you want to accept
• The Zuplo CLI installed and authenticated
• A Zuplo project where you can add the mtls-auth-inbound policy to a route

1/ Upload Your CA Certificate

Use the Zuplo CLI to upload your CA certificate. The CA is registered against your account and is automatically made available on all of your gateway domains.

First, authenticate your client:

Code
zuplo login

Then you can create a CA by running:

Code
zuplo ca-certificate create \
  --name my_ca \
  --cert ./ca.pem \
  --account your-account

Parameters:

• --name: A unique identifier for the CA. Must be a valid JavaScript identifier (letters, digits, _, $; cannot start with a digit).
• --cert: Path to the PEM-encoded CA certificate (-----BEGIN CERTIFICATE----- ...). DER is not supported.
• --account: Your Zuplo account name.

The command returns the new CA's ID (prefixed with mtlsca_). You can list all CAs on the account at any time:

Code
zuplo ca-certificate list --account your-account

See the ca-certificate CLI reference for all available subcommands (create, list, describe, update, delete).

2/ Add the mTLS Auth Inbound Policy

Add the mtls-auth-inbound policy to any route that should require a verified client certificate. The policy reads the verification result that Zuplo's edge attached to the request and either rejects unverified traffic or allows it through, depending on configuration.

config/policies.json
{
  "name": "my-mtls-auth-inbound-policy",
  "policyType": "mtls-auth-inbound",
  "handler": {
    "export": "MTLSAuthInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "allowUnauthenticatedRequests": false,
      "certIssuerDN": "CN=example-ca, O=Example, C=US"
    }
  }
}

Key options:

• allowUnauthenticatedRequests (default false): When false, the policy rejects requests that don't present a valid client certificate signed by a CA on your account. When true, the policy lets traffic through but still attaches certificate metadata when a parseable client certificate is present — useful for staged rollouts or logging-only modes.
• certIssuerDN: The fully qualified issuer distinguished name that the client certificate must be signed by.

See the full policy reference for all options.

Code
openssl x509 -in ca.pem -noout -subject -nameopt RFC2253

3/ Read Certificate Metadata in Your Handler

When verification succeeds, the policy attaches parsed certificate metadata to request.user.data.mtlsAuth. If request.user does not already exist, the policy also sets request.user.sub to the certificate subject.

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

export default async function (request: ZuploRequest, context: ZuploContext) {
  const mtls = request.user?.data?.mtlsAuth;

  if (!mtls) {
    return new Response("No client certificate", { status: 401 });
  }

  context.log.info("Authenticated client", {
    subject: mtls.subject,
    issuer: mtls.issuer,
    fingerprint: mtls.sha256Fingerprint,
  });

  // Authorize based on certificate subject, fingerprint, etc.
  return new Response(`Hello, ${mtls.subject}`);
}

The metadata object includes:

• subject — the client certificate subject DN
• issuer — the issuer DN (the CA that signed the certificate)
• notBefore / notAfter — validity window in ISO 8601 format
• sha256Fingerprint — SHA-256 digest of the DER-encoded certificate, uppercase hex with colon separators (e.g. AB:CD:EF:...). Useful for pinning specific client certificates.

The raw client certificate is also available on context.incomingRequestProperties.clientCert in RFC 9440 format (Base64-encoded DER, colon-wrapped) if you need to perform custom parsing or forward it to a backend.

Managing CA Certificates

Listing CAs

Code
zuplo ca-certificate list --account your-account

Inspecting a CA

Code
zuplo ca-certificate describe \
  --cert-id mtlsca_abc123 \
  --account your-account

Renaming a CA

Only the name can be updated; to replace the certificate body, delete the CA and create a new one.

Code
zuplo ca-certificate update \
  --cert-id mtlsca_abc123 \
  --name renamed_ca \
  --account your-account

Deleting a CA

Code
zuplo ca-certificate delete \
  --cert-id mtlsca_abc123 \
  --account your-account

Rotating a CA

To rotate the CA without downtime:

1. Upload the new CA alongside the existing one with zuplo ca-certificate create.
2. Reissue client certificates from the new CA and distribute them to your clients.
3. Once all clients have moved to the new CA, delete the old CA with zuplo ca-certificate delete.

If you've followed the common practice of preserving the CA's subject DN across the rotation (only the key, serial, and validity dates change), the issuer DN on newly issued client certificates is identical to the previous one and certIssuerDN does not need to change. If the rotation deliberately changes the CA's subject DN, update certIssuerDN to match the new value before cutting clients over — or temporarily set allowUnauthenticatedRequests: true to allow both issuers during the transition.

Local Development

The mtls-auth-inbound policy relies on verification metadata supplied by Zuplo's edge proxy and does not work in local development with zuplo dev. Test the policy in a working-copy or preview environment.

Troubleshooting

Requests are rejected with 401

• Confirm the client is presenting a certificate signed by a CA that's been uploaded with zuplo ca-certificate list.
• If you've set certIssuerDN, verify it matches request.user.data.mtlsAuth.issuer exactly (casing and whitespace are tolerated, but RDN order is not).
• Temporarily set allowUnauthenticatedRequests: true and log context.incomingRequestProperties.clientMtlsVerificationStatus and context.incomingRequestProperties.clientMtlsVerificationReason to see why verification failed.

request.user.data.mtlsAuth is missing

• The policy only attaches metadata when a parseable client certificate is present on the request. Confirm the client is sending one.
• Verify the route includes the mtls-auth-inbound policy.

Custom domains

When a CA is uploaded, it's automatically associated with Zuplo's managed gateway domains. A custom domain must be active in the dashboard (check the Settings/Custom Domains sidebar) before CA verification will become active on that custom domain.

If you use a custom domain and your clients aren't being verified against it, contact support@zuplo.com.

Additional Resources

• mtls-auth-inbound policy reference
• ca-certificate CLI reference
• Gateway to Origin mTLS Authentication — the reverse direction, where Zuplo authenticates to your backend with a client certificate

If you need help configuring client mTLS for your account, contact us at support@zuplo.com.