Client certificate (mTLS) in Apache APISIX

When Apache APISIX client certificate (mTLS) authentication fits partner and service traffic

Choose client certificate authentication when a partner or internal service must prove its identity with a certificate before it can reach an API, and when your security team wants that proof checked at the network edge rather than inside each application. In APISIX, client verification is configured per SSL object: the client.ca field holds the trusted certificate authority and client.depth sets how far up the certificate chain APISIX will follow. This applies to HTTPS listeners only, so plan the TLS listener for each partner-facing hostname and confirm the chain depth against the certificate hierarchy your partners actually issue. The APISIX mTLS documentation covers the related settings in detail.

Keep the scope of this control clear in the design. The client certificate check on SSL objects governs traffic from callers to the gateway. It does not secure the Admin API, which has its own mTLS settings under admin_api_mtls, nor the connection from APISIX to etcd (deployment.etcd.tls), nor the connection from APISIX to upstream services (tls.client_cert and tls.client_key). Each of these needs its own certificate plan, and teams often mistake one for another during an audit. Confirm which of the three connections your architecture uses before you assign certificate ownership and rotation.

Compare mTLS with API keys and JWTs on the basis of who holds the credential and where trust comes from. Certificates suit partners and services that can manage private keys and that your organization can onboard through a certificate authority, because the gateway can verify identity during the TLS handshake without a shared secret. API keys are simpler to issue but are bearer secrets, and JWTs suit user or application tokens issued by an identity provider. Many organizations combine mTLS for the transport trust with a consumer-level credential for authorization, so decide early whether one partner certificate maps to one consumer or to several applications.

Which mTLS links APISIX can secure and where each is configured

APISIX documents mTLS on four separate links: the Admin API, its etcd connection, client traffic into the gateway, and traffic from the gateway to upstreams. Each link has its own certificates and configuration keys, so securing one does not secure the others. This page focuses on the client-facing link, and the cards below show where the other three sit so they can be planned as separate hardening work.

Client to APISIX on each SSL object

This is the link this page covers. Client certificate verification is set per SSL object using client.ca and client.depth, and it applies only to HTTPS. Partner and service traffic is therefore controlled by which SSL object matches the request, so the CA trust and depth you set on each object determine who gets through. Check that every partner hostname maps to an SSL object with the intended CA bundle.

APISIX to upstream connections

Here APISIX presents its own client certificate to a backend, configured with tls.client_cert and tls.client_key on the upstream. This protects the hop from gateway to service, not the partner's access. Confirm that the backend validates the gateway's certificate, that the private key is stored outside the route definition where possible, and that rotation is planned for both sides of the connection.

Admin API over https_admin

The Admin API can require client certificates through the https_admin setting with admin_api_mtls certificates. Without this, anyone who can reach the Admin API port can change routes, consumers and SSL objects, so the Admin API should be treated as a control-plane asset. Confirm which networks can reach the Admin API port, which clients hold certificates, and who can issue them.

etcd connections

When APISIX runs in traditional or decoupled mode, it stores configuration in etcd. The deployment.etcd.tls settings protect those connections. Because every route and certificate passes through etcd, a compromised or unauthenticated etcd link affects the whole gateway. Confirm the etcd cluster's certificate authority, which nodes trust it, and how etcd certificates are rotated without restarting the gateway.

Scope and sequencing of the four links

Each link has a different CA, different certificate owners and a different failure impact, so they should be inventoried and sequenced separately. A common approach is to start with the client link for the partner or service traffic in scope, then review the Admin API and etcd, then the upstream hop. Ask the team which links are in scope for your audit or partner agreement before the build starts.

Configuration options for client certificate checks and when each fits

This table compares the settings that shape a client certificate check in APISIX, from trust anchors and chain depth to SNI binding, HTTPS scope and stream route mTLS. Read each row for when the setting fits and what it costs in trust isolation or operations. Confirm parameter names and defaults against the APISIX release you deploy, because they can change between versions.

Setting	What it controls	When it fits	Trade-off to weigh
client.ca on the SSL object	The CA certificate used to verify client certificates presented to that SSL object	One CA issued for a single partner group or internal service mesh with a single owner	A shared CA lets any certificate it signs pass the check, so issuance and revocation controls must be tight
Per-partner CAs	Separate trust anchors, each bound to its own SSL object or SNI name	Partners with different onboarding, revocation or audit requirements, or where one partner must not be trusted by another	More SSL objects and CA files to rotate and monitor, and more Admin API changes during partner onboarding
client.depth	How many intermediate certificates APISIX walks up the chain when verifying a client certificate	Hierarchies with an intermediate issuing CA that signs partner certificates	A larger depth accepts longer chains, so keep it no deeper than your PKI design requires
SNI binding on the SSL object	Which hostname selects the SSL object and therefore which client CA applies	Several partner APIs on one gateway that need different trust settings under different hostnames	Clients that send no SNI or a mismatched name may reach the wrong SSL object, so test each hostname explicitly
HTTPS-only scope	Client certificate verification applies to HTTPS connections handled by SSL objects, not plain HTTP on port 9080	Partner and service APIs that must never accept unauthenticated HTTP	Plain HTTP listeners need separate controls such as a redirect, a firewall rule or an authentication plugin
Stream route mTLS	Client certificate checks for TCP traffic through stream routes once stream proxying is enabled	Non-HTTP partner or service protocols that need client certificates at the gateway	Stream proxying is off by default, so enabling it changes the gateway's exposed surface and needs its own review
Mapping certificates to consumers	Whether a verified certificate identity is linked to a consumer for later authorization	Per-partner access rules that must follow the certificate identity	Mapping depends on which fields the certificate carries, so confirm the mapping approach for your release before relying on it

How to design the CA hierarchy, chain depth and consumer mapping

Decide the trust model before you touch the SSL object. The first choice is whether one issuing CA signs every partner and service certificate, or whether each partner gets its own intermediate CA under a root you control. A single issuing CA is simpler to operate and rotate, but it means one compromised key affects every partner. Per-partner intermediates limit that blast radius and let you revoke one partner's trust without reissuing everyone else's certificates, at the cost of more CA material to protect and more chain configuration. Whichever you choose, write down who signs, who holds the keys, and where the root lives. Then confirm with each partner's PKI team how deep their chain is, because APISIX's client.depth setting on the SSL object limits how many intermediate levels it will walk when validating a client certificate. If a partner presents a chain deeper than the depth you set, the handshake fails for reasons that look like a certificate problem rather than a configuration one.

Map certificate identity to consumers before you write the mapping. APISIX associates a client certificate with a consumer based on fields you select in the certificate, typically the subject or a SAN entry, so the identity you rely on must be stable, unique per partner and not reused across environments. Treat the mapping rule as a contract: a partner renewing a certificate with a changed subject string would silently lose its consumer binding, so agree naming conventions for subject and SAN fields with each partner before go-live. The exact fields the mapping supports, and how they are matched, depend on the APISIX version in use, so confirm them against the APISIX mTLS documentation for your release before you design around them. Revocation also needs an explicit decision. Confirm in your APISIX version and build whether certificate revocation checking is performed by the gateway. If it is not, plan revocation through short certificate lifetimes, removing the consumer or SSL binding, and an incident runbook that disables a partner's trust in minutes.

How to set up mTLS on an APISIX SSL object step by step

This sequence takes a gateway from no client authentication to one that accepts only partner or service clients presenting a certificate issued by your client CA, then maps those certificates to consumers. Each step closes with a check so the team can confirm the control works before traffic depends on it.

Confirm the deployment mode and listening ports
The platform engineer confirms which APISIX deployment mode is in use and where the Admin API and client traffic listen. In traditional mode, APISIX listens on port 9080 for client traffic and port 9180 for the Admin API. In decoupled and standalone modes the Admin API and configuration path differ, so the commands in the following steps must be adapted to the mode your team runs. Done when the team has written down the mode, the client-facing HTTPS port and the admin endpoint, and a basic request to the gateway returns a response from APISIX.
Issue and store the client certificate authority
The security engineer creates or selects the certificate authority that will sign partner and service client certificates, keeping its private key in your secrets store or hardware-backed storage rather than in a repository. Record the CA certificate file that APISIX will trust and the chain depth your clients will present. Done when you can sign a test client certificate from this CA and verify it locally with openssl verify against the CA file, and the CA file is ready to be loaded into the SSL object.
Create the SSL object with client CA and depth
The platform engineer creates an SSL object through the Admin API with the server certificate and key, a snis list matching the hostname partners will use, and a client block that sets ca to the PEM content of the client CA and depth to the number of intermediate certificates APISIX should walk. The client settings apply only to HTTPS, so confirm the object is attached to the HTTPS listener. Done when a GET on the SSL object returns the stored client block and the gateway accepts the configuration without a validation error.
Create the route bound to the SNI
The platform engineer creates the route with a host match that corresponds to the SNI in the SSL object, sets the upstream to the partner or service backend, and applies TLS settings for the upstream only if the backend requires its own client certificate. Mismatched hostnames are a common cause of failures, so the route host and SNI must be identical. Done when a request sent with the matching hostname reaches the route and the access log shows the expected route ID.
Test with valid and invalid client certificates
The engineer runs an openssl s_client handshake against the gateway with the SNI set and a certificate signed by the client CA, then repeats it with no certificate and with a certificate from a different CA. The valid handshake should complete and the request should return the upstream response. The invalid handshakes should be rejected during TLS negotiation or return an error before the upstream is reached. Done when the valid case succeeds, both invalid cases fail, and the gateway error log shows the rejection reason.
Verify TCP stream routes separately if needed
If partner traffic arrives on a non-HTTP protocol, the network engineer must enable stream proxying, which is off by default and is turned on through the proxy mode setting, then create a stream route that terminates TLS with client verification. Stream routes match on server address, server port, remote address and SNI. Run the same valid and invalid handshake tests against the stream port. Done when the stream listener accepts the valid certificate, rejects the others, and the behavior matches the HTTPS tests.
Map client certificates to consumers
The identity owner decides how each certificate identifies a partner or service, then creates the matching consumer and documents the mapping from certificate subject or fingerprint to consumer name. Confirm in the APISIX mTLS documentation how the current release exposes the client certificate identity to downstream plugins before writing the mapping logic, because the mapping method depends on the version in use. Done when a request from a known certificate is attributed to the correct consumer in the logs and an unmapped certificate is refused by the policy you chose.

Applying mTLS to TCP stream routes and SNI-based matching

Stream proxying is off by default in Apache APISIX, so the first step for any mTLS design on TCP or TLS traffic is to enable it through apisix.proxy_mode set to stream or http&stream. Choose http&stream only if the same gateway must also serve HTTP routes. Confirm the exact setting and its placement in your configuration file against the stream proxy documentation for the APISIX version you deploy, because the behavior has changed across releases and your platform team will need it written down for change control.

Stream routes match on server_addr, server_port, remote_addr and SNI, so you can separate partner connections by listening port or by the server name the client presents. With TLS termination, APISIX completes the handshake, can require a client certificate, and then forwards plain or re-encrypted traffic to the upstream. Mutual TLS on a stream route follows the same client CA and chain-depth logic as HTTPS SSL objects, but you must test whether a given stream configuration verifies the client certificate in the way you expect, using a partner-style test client that presents an untrusted certificate and an expired one.

TLS passthrough routed by SNI works differently. APISIX reads the SNI value from the ClientHello and forwards the encrypted stream to the upstream without terminating it, so it cannot inspect the client certificate, apply certificate-to-consumer mapping, or log certificate fields. Any client certificate check must happen at the upstream service, and your runbook should name that service as the owner of certificate revocation and rotation. Decide early which model fits each partner, and document the trade-off for auditors who will ask where the handshake is verified.

Certificate rotation without breaking partner connections

Rotating a client certificate chain is mostly a coordination problem: the gateway, the partner and the CA all change on different clocks. The cards below cover the sequence that keeps existing partner connections working while the new chain is introduced, tested and, if needed, reversed.

Overlap old and new CA trust

During rotation, the client CA list on the SSL object should trust both the outgoing and the incoming CA until every partner has moved. Confirm with your team how client.ca is set on each SSL object that serves partner traffic, and whether one SSL object covers several SNI names that must rotate together. Remove the old CA only after traffic logs show no handshakes using it.

Issue leaf certificates in overlap

Partners should receive new leaf certificates issued by the new chain while their old certificates are still valid, so both are accepted during the window. Check that each leaf carries the client authentication usage its partner expects and that the chain depth set through client.depth still reaches the trust anchor in the new chain. Test this with a partner-side certificate before any cutover date is announced.

Update the SSL object safely

Change the SSL object in a controlled step: stage the new CA list, validate the configuration, then apply it. Ask your team which mechanism applies the change in your deployment mode (traditional, decoupled or standalone) and whether a reload is needed or the change is picked up dynamically. Record the exact object version before the change so you can restore it quickly.

Communicate dates to partners

Send partners a written schedule with the date the new CA will be trusted, the date the old CA will be removed, and the contact for failures during the window. Agree on which side owns certificate expiry alerts and who approves a deadline extension. Partners with long internal change cycles need this notice well before the cutover, not on the day.

Test old and new chains together

Before removing the old CA, run handshake tests from a client presenting the old chain and another presenting the new chain against the same listener. Include a partner-representative client on each side of the cutover. Confirm that failed handshakes produce log entries you can filter by SNI and client certificate subject, so a broken partner is visible quickly.

Roll back a failed rotation

Keep the previous SSL object configuration and the previous CA bundle available so the rotation can be reverted without reissuing partner certificates. Define the rollback trigger in advance, such as a rising handshake failure rate on one partner, and rehearse the revert in a non-production environment. Ask your team to confirm how quickly a revert takes effect in your deployment mode.

Questions teams ask before hiring help with APISIX mTLS

What drives the cost of an APISIX mTLS engagement?

The main drivers are the number of partners and client certificate chains, how mature your PKI is, whether stream routes are needed, and how much certificate rotation you want automated. Each partner adds intake, chain validation, SNI mapping, consumer mapping and testing, so a short list of partners with one internal CA is a much smaller piece of work than many partners with several issuers. Stream routes add configuration in the stream proxy layer and separate testing. Rotation automation is usually the largest recurring item, because it decides whether renewals are a planned task or an emergency. Ask any provider for a quote that lists each partner, each SSL object, each stream route and the rotation approach as separate line items, with the one-time build and any recurring support shown apart.

Can our in-house team set up APISIX mTLS without a partner?

Yes, if your team already runs APISIX, understands X.509 chains and can test against partner clients. The configuration itself is small: APISIX documents mTLS per SSL object through client CA and depth settings, and it documents upstream client certificates separately. The harder parts are operational: deciding who signs partner certificates, keeping chain depth correct as intermediates change, mapping certificates to consumers without accidental matches, and rotating certificates without breaking live partners. If those decisions are already owned by someone on your team, an in-house build is realistic. If your PKI or APISIX experience is thin, a fixed-scope engagement can cover the design, build and test while your team takes over operation.

What do we need to provide before work starts?

Plan to provide four things. First, a named owner for the client CA and its intermediates, including who approves issuance and revocation. Second, a technical contact at each partner who can confirm the certificate subject, issuer, chain and expiry dates, and who can run a test call. Third, test environments that match production routing, including a non-production APISIX instance and sample partner clients. Fourth, a change window for the first cutover and a rollback path. Without a test environment that mirrors the real chain, most delays come from discovering a missing intermediate after go-live. Confirm these inputs in the written scope, because they determine the schedule more than the configuration does.

How do partner certificate issuance timelines affect the project?

Partner certificate issuance is often outside your control, so it can set the critical path. If a partner's security team needs internal approval, uses a third-party CA or must generate keys in a hardware module, the certificate may arrive later than the gateway work is ready. Ask each partner early which CA issues their client certificate, whether they can supply the full chain, and how long their own approval process takes. DeployOpen can build and test the gateway configuration against a test CA while partners finish, but production traffic should wait until the real chain is validated. Treat partner readiness as a tracked dependency with named owners in the written plan.

What does a fixed-scope quote for APISIX mTLS include?

A fixed-scope quote follows from a written scope agreed before work starts. Expect the scope to name the APISIX deployment and mode, each SSL object or stream route that will require client certificates, the CA and chain arrangement, the number of partners and consumers, the rotation method, the test plan and the handover items. Deliverables and timelines are agreed in writing, so changes such as adding partners or new stream routes are handled as scope changes. Ask for the quote to separate one-time build work from any retainer for upgrades, certificate rotation support or continuous testing, since those recur. DeployOpen does not publish a price list, so the quote is the basis for cost.

What breaks most often with client certificate authentication in APISIX?

The most common failures are a missing or incorrect intermediate certificate in the chain, a client.depth value that does not match the chain, expired certificates that were not replaced in time, and SNI mismatches where the request reaches a different SSL object than intended. On stream routes, mTLS is only available once stream proxying is enabled through apisix.proxy_mode, so a route that appears correct in configuration may not receive traffic until that setting is changed. Teams also get surprised when certificate mapping to consumers matches more clients than expected. Test each partner with a valid certificate, an expired one, a certificate from another CA and a missing client certificate before go-live.

Does DeployOpen guarantee that our PKI or compliance will pass?

DeployOpen cannot guarantee a compliance outcome. It plans, implements and documents APISIX configuration and prepares evidence such as configuration records, test results and operating procedures that your auditors may review. DeployOpen does not issue audit reports, attestations or certifications. Independent auditors and certification bodies make those decisions. Ask for the evidence list in the written scope so you know what will be delivered and what your own team or auditor must still assess.

How DeployOpen works on this

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including Apache APISIX. For client certificate authentication, we scope the trust model, partner and service inventory, and certificate lifecycle in writing before any configuration changes are made in your environment.

How we scope

Inventory which partner, service and internal callers need client certificates, and which can stay on other controls.
Define the client CA hierarchy, chain depth, SNI hostnames and whether TCP stream routes need mTLS.
Agree in writing how certificates map to APISIX consumers, rotation intervals and who approves issuance.

How we build

Configure client CA and depth on HTTPS SSL objects, with SNI matching validated per hostname.
Set up stream routes with mTLS only where the protocol and the apisix.proxy_mode setting require them.
Test valid, expired, wrong-CA and missing-certificate requests before any partner traffic is moved.

How we hand over

Document the certificate issuance, consumer mapping, rotation and revocation runbooks for your operations team.
Deliver test evidence showing accepted and rejected handshakes for each route and hostname in scope.
Walk through rotation with your team so a renewal can be carried out without a planned outage.

How we support

Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
Ongoing support, APISIX upgrades and continuous testing are available as a retainer.
Confirm with your auditor which evidence they expect. DeployOpen prepares controls and evidence but does not issue audit reports or certifications.

Client certificate (mTLS) authentication in Apache APISIX