Configuring mutual TLS authentication at the pool level

Configure mutual TLS (mTLS) authentication at the pool level to verify back-end server certificates and present client certificates when connecting to back-end servers.

Before you begin

Before you configure authentication at the pool level, ensure that you have:

  • An application load balancer with a profile that supports mTLS (check the mtls_supported property)
  • A pool configured with the HTTPS protocol
  • (Optional) A valid CA certificate in PEM format stored in Secrets Manager to verify back-end server certificates
  • (Optional) A valid client certificate with private key in PEM format stored in Secrets Manager to present to back-end servers
  • The appropriate IAM permissions to manage load balancers and access certificates in Secrets Manager

Understanding mTLS pool-level authentication

Pool-level authentication provides two distinct capabilities for securing connections between the load balancer and back-end servers:

Server authentication
Verify the identity of back-end servers by validating their certificates against a configured CA certificate. This ensures that the load balancer connects only to trusted back-end servers.
Client authentication
Present a client certificate from the load balancer to back-end servers when the back-end infrastructure requires mTLS. This allows back-end servers to verify the identity of the load balancer.

These capabilities can be configured independently or together, depending on your security requirements.

Server mTLS authentication configuration

Server authentication consists of two components:

Verify certificate
A boolean flag that enables or disables back-end server certificate verification. When enabled, the load balancer validates back-end server certificates during the TLS handshake.
Certificate Authority (CA) certificate
An optional CA certificate used to verify back-end server certificates. If server verification is enabled but no CA certificate is provided, the load balancer uses the system trust store to validate back-end server certificates.

Client mTLS authentication configuration

Client authentication requires:

Client certificate
A certificate with private key that the load balancer presents to back-end servers when they request client authentication during the TLS handshake. The certificate must be stored in Secrets Manager.

Configuring mTLS pool authentication in the console

To configure authentication for a pool in the IBM Cloud console:

  1. Navigate to the Load balancers for VPC page.
  2. Click the name of your Application Load Balancer.
  3. Click the Back-end pools tab.
  4. For an existing pool, click the Actions menu Actions menu and select Edit. To create a new pool, click Create.
  5. In the pool configuration:
    • Ensure that Protocol is set to HTTPS.
  6. In the Server authentication section:
    • Select Verify server certificate to enable back-end server certificate verification.
    • (Optional) For Certificate authority, select the CA certificate from Secrets Manager that will be used to verify back-end server certificates. If not specified, the system trust store is used.
  7. In the Client authentication section:
    • For Client certificate, select the certificate from Secrets Manager that the load balancer will present to back-end servers.
  8. Click Save or Create.

Configuring mTLS pool authentication from the CLI

Creating a pool with mTLS server authentication

To create a pool with back-end server certificate verification enabled, use the ibmcloud is load-balancer-pool-create command:

ibmcloud is load-balancer-pool-create POOL_NAME LOAD_BALANCER ALGORITHM PROTOCOL \
  HEALTH_DELAY HEALTH_RETRIES HEALTH_TIMEOUT HEALTH_TYPE \
  --server-auth-verify-cert true \
  [--server-auth-ca-crn CA_CERT_CRN]

Where:

  • POOL_NAME is the name for your pool.
  • LOAD_BALANCER is the ID or name of your load balancer.
  • ALGORITHM is the load balancing algorithm (round_robin, weighted_round_robin, or least_connections).
  • PROTOCOL must be https for mTLS support.
  • CA_CERT_CRN is the optional CRN of the CA certificate used to verify back-end server certificates.

Example:

ibmcloud is load-balancer-pool-create my-pool my-load-balancer round_robin https \
  20 2 5 http \
  --server-auth-verify-cert true \
  --server-auth-ca-crn crn:v1:bluemix:public:secrets-manager:us-south:a/aa5a471f75bc456fac416bf02c4ba6de:aace9348-39da-4498-b132-e5ab918237f4:secret:e3bd96ce-1e4c-f642-d1f2-0d0ab025f511

Creating a pool with mTLS client authentication

To create a pool with client certificate presentation enabled:

ibmcloud is load-balancer-pool-create POOL_NAME LOAD_BALANCER ALGORITHM PROTOCOL \
  HEALTH_DELAY HEALTH_RETRIES HEALTH_TIMEOUT HEALTH_TYPE \
  --client-auth-cert-crn CLIENT_CERT_CRN

Example:

ibmcloud is load-balancer-pool-create my-pool my-load-balancer round_robin https \
  20 2 5 http \
  --client-auth-cert-crn crn:v1:bluemix:public:secrets-manager:us-south:a/aa5a471f75bc456fac416bf02c4ba6de:aace9348-39da-4498-b132-e5ab918237f4:secret:e3bd96ce-1e4c-f642-d1f2-0d0ab025f512

Creating a pool with both server and client mTLS authentication

To create a pool with both server verification and client certificate presentation:

ibmcloud is load-balancer-pool-create my-pool my-load-balancer round_robin https \
  20 2 5 http \
  --server-auth-verify-cert true \
  --server-auth-ca-crn crn:v1:bluemix:public:secrets-manager:us-south:a/aa5a471f75bc456fac416bf02c4ba6de:aace9348-39da-4498-b132-e5ab918237f4:secret:e3bd96ce-1e4c-f642-d1f2-0d0ab025f511 \
  --client-auth-cert-crn crn:v1:bluemix:public:secrets-manager:us-south:a/aa5a471f75bc456fac416bf02c4ba6de:aace9348-39da-4498-b132-e5ab918237f4:secret:e3bd96ce-1e4c-f642-d1f2-0d0ab025f512

Updating a pool to enable mTLS server authentication

To update an existing pool to enable server authentication:

ibmcloud is load-balancer-pool-update LOAD_BALANCER POOL \
  --server-auth-verify-cert true \
  [--server-auth-ca-crn CA_CERT_CRN]

Example:

ibmcloud is load-balancer-pool-update my-load-balancer my-pool \
  --server-auth-verify-cert true \
  --server-auth-ca-crn crn:v1:bluemix:public:secrets-manager:us-south:a/aa5a471f75bc456fac416bf02c4ba6de:aace9348-39da-4498-b132-e5ab918237f4:secret:e3bd96ce-1e4c-f642-d1f2-0d0ab025f511

Updating a pool to enable mTLS client authentication

To update an existing pool to enable client authentication:

ibmcloud is load-balancer-pool-update LOAD_BALANCER POOL \
  --client-auth-cert-crn CLIENT_CERT_CRN

Disabling mTLS server authentication

To disable server authentication for a pool:

ibmcloud is load-balancer-pool-update LOAD_BALANCER POOL --reset-server-auth

Disabling mTLS client authentication

To disable client authentication for a pool:

ibmcloud is load-balancer-pool-update LOAD_BALANCER POOL --reset-client-auth

Configuring pool authentication with the API

Creating a pool with mTLS server and client authentication

To create a pool with both server and client authentication enabled, call the POST /load_balancers/{load_balancer_id}/pools method:

curl -X POST \
  "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools?version=2026-05-06&generation=2" \
  -H "Authorization: Bearer $iam_token" \
  -d '{
    "name": "my-pool",
    "algorithm": "round_robin",
    "protocol": "https",
    "health_monitor": {
      "delay": 20,
      "max_retries": 2,
      "timeout": 5,
      "type": "http"
    },
    "server_authentication": {
      "verify_certificate": true,
      "certificate_authority": {
        "crn": "crn:v1:bluemix:public:secrets-manager:us-south:a/aa5a471f75bc456fac416bf02c4ba6de:aace9348-39da-4498-b132-e5ab918237f4:secret:e3bd96ce-1e4c-f642-d1f2-0d0ab025f511"
      }
    },
    "client_authentication": {
      "certificate_instance": {
        "crn": "crn:v1:bluemix:public:secrets-manager:us-south:a/aa5a471f75bc456fac416bf02c4ba6de:aace9348-39da-4498-b132-e5ab918237f4:secret:e3bd96ce-1e4c-f642-d1f2-0d0ab025f512"
      }
    }
  }'

Updating a pool to enable mTLS server authentication

To update an existing pool to enable server authentication, call the PATCH /load_balancers/{load_balancer_id}/pools/{id} method:

curl -X PATCH \
  "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id?version=2026-05-06&generation=2" \
  -H "Authorization: Bearer $iam_token" \
  -d '{
    "server_authentication": {
      "verify_certificate": true,
      "certificate_authority": {
        "crn": "crn:v1:bluemix:public:secrets-manager:us-south:a/aa5a471f75bc456fac416bf02c4ba6de:aace9348-39da-4498-b132-e5ab918237f4:secret:e3bd96ce-1e4c-f642-d1f2-0d0ab025f511"
      }
    }
  }'

Updating a pool to enable mTLS client authentication

To update an existing pool to enable client authentication:

curl -X PATCH \
  "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id?version=2026-05-06&generation=2" \
  -H "Authorization: Bearer $iam_token" \
  -d '{
    "client_authentication": {
      "certificate_instance": {
        "crn": "crn:v1:bluemix:public:secrets-manager:us-south:a/aa5a471f75bc456fac416bf02c4ba6de:aace9348-39da-4498-b132-e5ab918237f4:secret:e3bd96ce-1e4c-f642-d1f2-0d0ab025f512"
      }
    }
  }'

Disabling mTLS server authentication

To disable server authentication, set the server_authentication property to null:

curl -X PATCH \
  "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id?version=2026-05-06&generation=2" \
  -H "Authorization: Bearer $iam_token" \
  -d '{
    "server_authentication": null
  }'

Disabling mTLS client authentication

To disable client authentication, set the client_authentication property to null:

curl -X PATCH \
  "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id?version=2026-05-06&generation=2" \
  -H "Authorization: Bearer $iam_token" \
  -d '{
    "client_authentication": null
  }'

Configuring mTLS pool authentication with Terraform

To configure authentication for a pool using Terraform, use the ibm_is_lb_pool resource with the server_authentication and client_authentication blocks:

resource "ibm_is_lb_pool" "example" {
  lb                 = ibm_is_lb.example.id
  name               = "my-pool"
  algorithm          = "round_robin"
  protocol           = "https"
  health_delay       = 20
  health_retries     = 2
  health_timeout     = 5
  health_type        = "http"

  server_authentication {
    verify_certificate = true
    certificate_authority_crn = "crn:v1:bluemix:public:secrets-manager:us-south:a/aa5a471f75bc456fac416bf02c4ba6de:aace9348-39da-4498-b132-e5ab918237f4:secret:e3bd96ce-1e4c-f642-d1f2-0d0ab025f511"
  }

  client_authentication {
    certificate_instance_crn = "crn:v1:bluemix:public:secrets-manager:us-south:a/aa5a471f75bc456fac416bf02c4ba6de:aace9348-39da-4498-b132-e5ab918237f4:secret:e3bd96ce-1e4c-f642-d1f2-0d0ab025f512"
  }
}

Verifying mTLS pool authentication configuration

After configuring pool authentication, verify that it's working correctly:

  1. Check the pool status to ensure back-end servers are healthy:

    ibmcloud is load-balancer-pool LOAD_BALANCER POOL

  2. If server verification is enabled, ensure that back-end servers present valid certificates signed by the configured CA.

  3. If client authentication is enabled, verify that back-end servers can validate the client certificate presented by the load balancer.

  4. Monitor load balancer logs for any TLS handshake errors that might indicate certificate validation issues.

Important considerations for mTLS pool-level authentication

Pool-level configuration applies to all back-end servers
Both server authentication and client authentication are configured at the pool level. All back-end servers within the pool use the same authentication settings. If you need different certificate policies for different back-end servers, create separate pools.
Multiple Certificate Authorities for back-end servers
When back-end servers in the same pool are signed by different Certificate Authorities, you can provide a bundled CA file containing all relevant root and intermediate certificates. All back-end servers are trusted if their certificate chains to any CA included in the bundle.
System trust store
If server verification is enabled but no CA certificate is provided, the load balancer uses the system trust store (Ubuntu Linux) to validate back-end server certificates. This works for certificates signed by well-known public CAs but not for self-signed certificates or private CAs.
Certificate updates
When you update certificates in Secrets Manager, the load balancer automatically retrieves the updated certificates. However, active connections might need to be re-established to use the new certificates.

Next steps