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, both the global external Application Load Balancer and the classic Application Load Balancer support 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.

Architecture

The following resources are required for global external Application Load Balancers and classic Application Load Balancers to support an mTLS authentication deployment:

• A server TLS policy (ServerTLSPolicy) resource. Lets you specify the server-side TLS mode and the TrustConfig resource to use when validating client certificates. Server TLS policies support mTLS authentication. Server TLS policies can be attached to the target HTTPS proxy resource.

• A TrustConfig resource. A Certificate Manager resource. TrustConfig can be used only with a global external Application Load Balancer and a classic Application Load Balancer. TrustConfig contains a single trust store resource that is used to validate client certificates. For more information, see Manage trust configs.

• 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.

To learn more about the components of an external Application Load Balancer deployment, see Architecture in the External Application Load Balancer overview.

Figure 1. Mutual TLS with external Application Load Balancer components.

Features

The features supported by mTLS for a global external Application Load Balancer and a classic Application Load Balancer enable you to 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 easy 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 enable us to use mTLS with clients that do not 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>
Either the client certificate or its issuer does not 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>

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 statusDetails HTTP failure messages. 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

Custom header values 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 statusDetails HTTP failure messages. 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
Either the client certificate or its issuer does not have Extended Key Usage (EKU) 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 external Application Load Balancer takes the following steps:

1. 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.
2. 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.
3. If verifying the chain of trust succeeds, then the request is forwarded to the backend with any mTLS custom headers configured for the endpoint.
4. 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 back end that the validation failed, and the reason for the failure.

Certificate requirements

• Certificates must use either RSA or ECDSA ciphers.
• 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. This is required for the certificate that issues the client certificate.
  • The certificate must not be expired.

Limitations

• The load balancer does not perform revocation checks on client certificates.

• An external Application Load Balancer allows you to upload a trust config with a single trust store that contains at most 100 trust anchors and 100 intermediate certificates. 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.

What's next

• Set up mutual TLS with user-provided certificates

• Set up mutual TLS with a private CA

• Variables that can appear in the header value

• Set up mutual TLS for a global external Application Load Balancer

• Set up mutual TLS for a classic Application Load Balancer