Mutual TLS authentication

Typically with HTTPS communication, the authentication works only one way: the client verifies the identity of the server.

For applications that require the load balancer to authenticate the identity of clients that connect to it, use mutual TLS (mTLS).

With mTLS, the load balancer requests that the client send a certificate to authenticate itself during the TLS handshake with the load balancer. You can configure a trust store that the load balancer uses to validate the client certificate's chain of trust.

The following Application Load Balancers support mTLS:

Global external Application Load Balancer
Classic Application Load Balancer
Regional external Application Load Balancer
Regional internal Application Load Balancer
Cross-region internal Application Load Balancer

Architecture

The following resources are required for load balancers to support an mTLS authentication deployment:

A Client Authentication (also known as ServerTLSPolicy) resource. Lets you specify the server-side TLS mode and the TrustConfig resource to use when validating client certificates. You can specify all the mTLS authentication related parameters in the server TLS policies. Server TLS policies can be attached to the target HTTPS proxy resource.
A TrustConfig resource. A Certificate Manager resource. TrustConfig contains a single trust store resource that is used to validate client certificates. For more information, see Manage trust configs.

You can upload certificates that are added to an allowlist to the TrustConfig. A certificate that is added to an allowlist is always considered valid as long as the certificate is parseable, proof of private key possession is established, and constraints on the SAN field of the certificate are met. Expired certificates are also considered valid when they are in an allowlist.
A trust store. Contains the trust anchor and intermediate certificate authority (CA) certificates that are used to validate the client certificate chain. A CA is used to issue trusted certificates for the client. The CA is identified by the load balancer's trust anchor root certificate or the intermediate CA certificates.

You can upload the following types of client certificates to the trust store:
- Certificates issued by third-party CAs of your choice.
- Certificates issued by private CAs in your control, as described in Set up mutual TLS with a private CA.
- Signed certificates, as described in Set up mutual TLS with user-provided certificates.

The following image shows mTLS components:

global

The following diagram shows the components of an external Application Load Balancer deployment. This architecture also applies to the cross-region internal Application Load Balancer, which is an internal Application Load Balancer that uses global components.

regional

The following diagram shows the components of a regional internal Application Load Balancer deployment. This architecture also applies to the regional external Application Load Balancer, which is an external Application Load Balancer that uses regional components.

For more information about the components of an Application Load Balancer deployment, see the following sections:

Features

The features supported by mTLS for load balancers let you do the following:

Verify proof of possession of the private key of the certificate presented by the client.
Validate client certificates in either of two modes:
- Reject requests if we cannot validate the client certificate chain against a trust store.
- Pass all requests to the backend even if they don't provide a client certificate.
Perform client certificate validation against an uploaded PKI anchor. Support the addition of multiple PKI anchors separately to facilitate no-downtime migration from an old PKI to a new one.
Provide additional intermediate certificates to be used for validation path building against specified PKI anchors. The intermediate certificates let you use mTLS with clients that don't pass the full certificate chain.
Generate and pass a fingerprint of the certificate to the backend as a custom request header.
Pass selected fields extracted from the certificate to the backend by using custom request headers.
Pass the validation result and any validation errors to the backend by using custom request headers.

For a more detailed description of the validation process, see the Client certificate validation steps section later on this page.

MTLS client validation modes

When the client presents an invalid certificate or no certificate to the load balancer, the clientValidationMode specifies how the client connection is handled.

The clientValidationMode values are as follows:

ALLOW_INVALID_OR_MISSING_CLIENT_CERT allows the connection from the client even if certificate chain validation of the client certificate failed or no client certificate was presented. The proof of possession of the private key is always checked when the client certificate is presented.

You can use custom header variables with this mode to indicate to the backend whether the client provided a certificate, whether the certificate validation succeeded, and other information extracted from the certificate.
REJECT_INVALID rejects the connection if a client does not provide a certificate or if the certificate validation failed.

You can view logs for mTLS client certificate validation when logging is enabled on the backend service.

Custom header values passed to the backend

The following table shows all the mutual TLS custom header variable values that are always passed to the backend (request type "Pass request to backend"). Custom headers are passed to the backend when the clientValidationMode is set to ALLOW_INVALID_OR_MISSING_CLIENT_CERT or the client certificate passes certificate validation.

Client certificate status	clientValidationMode	Custom headers
The client certificate chain is too long (more than 10 intermediate certificates included with the client certificate).	`ALLOW_INVALID_OR_MISSING_CLIENT_CERT`	`client_cert_present: true` `client_cert_chain_verified: false` `client_cert_error: client_cert_chain_exceeded_limit` `client_cert_sha256_fingerprint: <cert hash>`
A client or an intermediate certificate has an invalid RSA key size. No validation is performed. RSA keys can be from 2048 to 4096 bits.	`ALLOW_INVALID_OR_MISSING_CLIENT_CERT`	`client_cert_present: true` `client_cert_chain_verified: false` `client_cert_error: client_cert_invalid_rsa_key_size` `client_cert_sha256_fingerprint: <cert hash>`
A client or an intermediate certificate is using an unsupported elliptic curve. No validation is performed. Valid elliptic curves are P-256 and P-384.	`ALLOW_INVALID_OR_MISSING_CLIENT_CERT`	`client_cert_present: true` `client_cert_chain_verified: false` `client_cert_error: client_cert_unsupported_elliptic_curve_key` `client_cert_sha256_fingerprint: <cert hash>`
A client or an intermediate certificate is using a non-RSA, non-ECDSA algorithm. No validation is performed.	`ALLOW_INVALID_OR_MISSING_CLIENT_CERT`	`client_cert_present: true` `client_cert_chain_verified: false` `client_cert_error: client_cert_unsupported_key_algorithm` `client_cert_sha256_fingerprint: <cert hash>`
The PKI to be used for validation has more than ten intermediate certificates that share the same Subject and Subject Public Key Info. No validation is performed.	`ALLOW_INVALID_OR_MISSING_CLIENT_CERT`	`client_cert_present: true` `client_cert_chain_verified: false` `client_cert_error: client_cert_pki_too_large` `client_cert_sha256_fingerprint: <cert hash>`
An intermediate certificate provided for validation had more than 10 name constraints.	`ALLOW_INVALID_OR_MISSING_CLIENT_CERT`	`client_cert_present: true` `client_cert_chain_verified: false` `client_cert_error: client_cert_chain_max_name_constraints_exceeded` `client_cert_sha256_fingerprint: <cert hash>`
The client certificate doesn't have `Extended Key Usage (EKU)` that includes `clientAuth`	`ALLOW_INVALID_OR_MISSING_CLIENT_CERT`	`client_cert_present: true` `client_cert_chain_verified: false` `client_cert_error: client_cert_chain_invalid_eku` `client_cert_sha256_fingerprint: <cert hash>`
The time limit is exceeded while attempting to validate the certificate chain.	`ALLOW_INVALID_OR_MISSING_CLIENT_CERT`	`client_cert_present: true` `client_cert_chain_verified: false` `client_cert_error: client_cert_validation_timed_out` `client_cert_sha256_fingerprint: <cert hash>`
The depth or iteration limit is reached while attempting to validate the certificate chain. The maximum depth for a certificate chain is ten, including the root and client certificates. The maximum iterations is 100 (certificates examined to validate the client certificate chain).	`ALLOW_INVALID_OR_MISSING_CLIENT_CERT`	`client_cert_present: true` `client_cert_chain_verified: false` `client_cert_error: client_cert_validation_search_limit_exceeded` `client_cert_sha256_fingerprint: <cert hash>`
You configured mTLS without setting up a `TrustConfig` resource. No validation can be performed, but the cert hash is forwarded to the backend.	`ALLOW_INVALID_OR_MISSING_CLIENT_CERT`	`client_cert_present: true` `client_cert_chain_verified: false` `client_cert_error: client_cert_validation_not_performed` `client_cert_sha256_fingerprint: <cert hash>`
No client certificate.	`ALLOW_INVALID_OR_MISSING_CLIENT_CERT`	`client_cert_present: false` `client_cert_chain_verified: false` `client_cert_error: client_cert_not_provided` `client_cert_sha256_fingerprint: <empty>`
Client certificate fails validation against the `TrustConfig` resource.	`ALLOW_INVALID_OR_MISSING_CLIENT_CERT`	`client_cert_present: true` `client_cert_chain_verified: false` `client_cert_error: client_cert_validation_failed` `client_cert_sha256_fingerprint: <cert hash>`
Client certificate passes cert verifier validation.	Not applicable	`client_cert_present: true` `client_cert_chain_verified: true` `client_cert_error: <empty>` `client_cert_sha256_fingerprint: <cert hash>` `client_cert_serial_number: <serial_number>` `client_cert_valid_not_before: <date>` `client_cert_valid_not_after: <date>` `client_cert_uri_sans: <list>` `client_cert_dnsname_sans: <list>` `client_cert_issuer_dn: <issuer>` `client_cert_subject_dn: <subject>` `client_cert_leaf: <certificate>` `client_cert_chain: <list>`

Logged errors for closed connections

The following errors result in a closed client connection when the clientValidationMode is set to either ALLOW_INVALID_OR_MISSING_CLIENT_CERT or REJECT_INVALID. For more information, see Regional external Application Load Balancer logging and monitoring and internal Application Load Balancer logging and monitoring. These errors are logged to Cloud Logging and described in the following table.

Client certificate status	Request	Logged error
Client certificate fails signature match during handshake.	Terminate SSL handshake	None
Service is unable to perform certificate chain validation.	Terminate connection	`client_cert_validation_unavailable`
Internal error validating certificate chain.	Terminate connection	`client_cert_validation_internal_error`
Matching `TrustConfig` not found.	Terminate connection	`client_cert_trust_config_not_found`
The client certificate payload (including any intermediate certificates) is too large (more than 16 KB).	Terminate connection	`client_cert_exceeded_size_limit`

Logged errors with `REJECT_INVALID` validation

The following errors result in a closed connection (request type "Terminate connection") when clientValidationMode is set to REJECT_INVALID. For more information, see For more information, see Regional external Application Load Balancer logging and monitoring and internal Application Load Balancer logging and monitoring. These errors are logged to Cloud Logging and described in the following table.

Client certificate status	Logged error
The client certificate chain is too long (more than 10 intermediate certificates included with the client certificate).	`client_cert_chain_exceeded_limit`
A client or an intermediate certificate has an invalid RSA key size. No validation is performed. RSA keys can be from 2048 to 4096 bits.	`client_cert_invalid_rsa_key_size`
A client or an intermediate certificate is using an unsupported elliptic curve. No validation is performed. Valid curves are P-256 and P-384.	`client_cert_unsupported_elliptic_curve_key`
A client or an intermediate certificate is using a non-RSA or non-ECDSA algorithm. No validation is performed.	`client_cert_unsupported_key_algorithm`
The PKI to be used for validation has more than ten intermediate certificates that share the same Subject and Subject Public Key Info. No validation is performed.	`client_cert_pki_too_large`
An intermediate certificate provided for validation had more than 10 name constraints.	`client_cert_chain_max_name_constraints_exceeded`
The client certificate does not have an `Extended Key Usage (EKU)` extension that includes `clientAuth`	`client_cert_chain_invalid_eku`
The time limit is exceeded while attempting to validate the certificate chain.	`client_cert_validation_timed_out`
The depth or iteration limit is reached while attempting to validate the certificate chain. The maximum depth for a certificate chain is ten, including the root and client certificates. The maximum number of iterations is 100 (certificates examined to validate the client certificate chain).	`client_cert_validation_search_limit_exceeded`
You configured mTLS without setting up a `TrustConfig` resource.	`client_cert_validation_not_performed`
The client did not provide the requested certificate during the handshake.	`client_cert_not_provided`
The client certificate fails validation with the `TrustConfig` resource.	`client_cert_validation_failed`

Client certificate validation steps

When validating a client certificate, the load balancer takes the following steps:

The load balancer verifies the client's signature to prove that the client possesses the client certificate's private key. If this step fails, the load balancer always fails the TLS handshake, even if your configuration allows invalid or missing client certificates, and no information is logged for global external Application Load Balancers, but a TLS error is logged in the proxyStatus field for regional external Application Load Balancers and internal Application Load Balancers.
If the configuration includes a TrustAnchor, the load balancer verifies a chain of trust between the client certificate and the configured TrustAnchor. Specifically, the load balancer verifies the following:
- The client, intermediate and root certificates comply with the certificate requirements.
- The subject field in parent certificates matches the issue field in child certificates.
- The Subject Key Identifier (SKID) of the parent certificate matches the Authority Key identifier (AKID) in the child certificate.
- The SAN of a child certificate does not violate the NameConstraints field in the parent certificate.
If verifying the chain of trust succeeds, then the request is forwarded to the backend with any mTLS custom headers configured for the endpoint.
If verifying the chain of trust fails:
- If ClientValidationMode is set to REJECT_INVALID, the load balancer terminates the connection and logs the reason to Cloud Logging.
- If ClientValidationMode is set to ALLOW_INVALID_OR_MISSING_CLIENT_CERTIFICATE, the load balancer still forwards the request to the backend. You can use custom request headers to indicate to the backend that the validation failed, and the reason for the failure. For cross-region internal Application Load Balancers, regional external Application Load Balancers, or regional internal Application Load Balancers, in addition to custom request headers, you can configure mTLS optional fields to check the reason for the failure.

Certificate requirements

Modern cryptography tools form the basis of mTLS authentication. Certificates must use either RSA or ECDSA algorithms for key exchange. Hashing algorithms must use SHA-256 or a stronger cryptographic hash function. Hashing algorithms such as MD4, MD5, and SHA-1 aren't supported.
For client (leaf) certificates:
- The Basic Constraints extension must not contain CA=true.
- The Extended Key Usage extension must contain clientAuth.
- The Extended Key Usage extension must not contain the codeSigning, timeStamping, or OCSPSigning fields.
- The certificate must not be expired.
- The client certificate cannot be a self-signed certificate.
For root and intermediate certificates:
- The Basic Constraints extension must contain CA=true.
- The Key Usage extension must be set to keyCertSign.
- The Extended Key Usage extension should contain the clientAuth field.
- The certificate must not be expired.

Limitations

The load balancer does not perform revocation checks on client certificates.
Application Load Balancers let you upload a trust config with a single trust store that contains at most 100 trust anchors and 100 intermediate certificates and 500 certificates that are added to an allowlist. All intermediate certificates must not have more than three certificates that share the same Subject and Subject Public Key info. For more information, see Quotas and limits.
The maximum depth for a certificate chain is ten, including the root and client certificates. The maximum number of times that intermediate certificates can be evaluated when attempting to build the chain of trust is 100. For more information, see Quotas and limits.
Keys of certificates uploaded and passed from the client are restricted to the following:
- RSA keys can be from 2048 to 4096 bits. For more information, see Quotas and limits.
- ECDSA keys can use the P-256 or P-384 curves.
The accepted certificate chain received from the client is limited to up to 16 KB and 10 certificates. For more information, see Quotas and limits.
Root certificates used for validation cannot contain more than 10 name constraints. For more information, see Quotas and limits.
Self-signed client certificates are always considered to be invalid by the load balancer.