Require client certificates

You configure a trusted client CA for incoming TLS and verify access with and without a client certificate.

Note: Balancer is in beta. Endpoints, fields and behavior may change before general availability, and the feature must be enabled on your account before use. Contact your NetActuate account manager to request access.

Prerequisites

• Balancer access and a key in the BALANCER_API_KEY environment variable with permission for these operations.
• The API host shown in the Balancer portal. Replace <your-api-host> in every example with that host.
• A shell, curl and Python 3 for examples that build JSON from environment variables.
• An HTTPS group and domain, a local PEM client CA bundle, and a client certificate and private key signed by that CA. Set CLIENT_CA_PEM to the CA bundle contents.

Resource identifiers come from your API responses. Set each variable when its value is available, before the first step that uses it.

Environment variable	Value
CLIENT_CA_PEM	Your local PEM contents.
GROUP_ID	Returned resource identifier, or your selected scope identifier.
HTTP_LB_ID	Returned resource identifier, or your selected scope identifier.

For an identifier, enter the value returned for your resource and export it:

read -r -p 'GROUP_ID: ' GROUP_ID
export GROUP_ID

Read your local CA bundle before configuring the group:

export CLIENT_CA_PEM="$(cat client-ca.pem)"

Steps

1. Require client CA validation on the group.

   python3 - <<'PYBODY' | \
   curl --silent --show-error --include \
     --request PATCH \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups/$GROUP_ID" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary @-
   import json, os
   print(json.dumps({'downstreamCaCertificate': os.environ['CLIENT_CA_PEM']}))
   PYBODY

   API reference: Update an HTTP group configuration

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success",
     "data": {
       "groupId": 1
     }
   }

2. Read the group configuration.

   curl --silent --show-error --include \
     --request GET \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups/$GROUP_ID" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: Get HTTP group

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success",
     "data": {
       "groupId": 1
     }
   }

Verify

Test https://example.com without a client certificate, then with the authorized client certificate. The first connection should fail client CA validation during TLS. The second should complete TLS and reach the configured HTTP behavior. A TLS rejection need not include an HTTP status.

Use your configured site domain in this traffic check:

curl --silent --show-error --include "https://example.com/"

Expected: the site behavior described above. The application response body and status depend on your origin and selected policies.

Repeat with your local client material:

curl --silent --show-error --include \
  --cert client-certificate.pem \
  --key client-private-key.pem \
  "https://example.com/"

Expected: TLS succeeds for a trusted client, followed by the configured application response.

An API mutation saves desired configuration first. Readback and a live traffic check answer different questions. No fixed propagation time is established.

The mtlsClientCertificateId field selects a client certificate for connections toward the origin. It does not require incoming clients to present certificates.

Troubleshooting

Symptom	Cause	Fix
Valid client fails TLS	Wrong trust bundle or certificate chain	Check the client issuer and supplied chain.
Origin authentication changes instead	An origin client certificate was configured	Use downstreamCaCertificate for incoming TLS.
API readback succeeds but connections differ	Serving TLS configuration has not converged	Repeat the handshake and ask support to compare deployment state.

Limits and defaults

Setting	Limit or default
Client CA bundle	Maximum 32768 characters
HTTP TLS profile	Default modern; modern, compatible or legacy

API status codes

Status	Meaning
200	Request succeeds; inspect returned data.
400	Invalid arguments or configuration.
401	Authentication or authorization denied.
404	Resource or parent is unavailable.
409	Resource state conflicts with the operation.
412	Inspect the returned error details.
500	The request encounters a server error.

Related API operations

• DELETE /mtls-certificates/{mtlsCertificateId}
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}
• GET /mtls-certificates
• GET /mtls-certificates/{mtlsCertificateId}
• PATCH /http-loadbalancers/{httpLbId}/groups/{groupId}
• POST /mtls-certificates

API reference

• Delete an mTLS client certificate

• Get HTTP group

• List mTLS client certificates

• Get mTLS client certificate

• Update an HTTP group configuration

• Upload an mTLS client certificate and private key

• Groups and Routes

• mTLS Certificates

Need Help?

Contact your account manager or use the Balancer portal.