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:

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.

Mutual TLS with global external Application Load Balancer components.
Figure 1. Mutual TLS with global external Application Load Balancer components (click to enlarge).

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.

Mutual TLS with regional internal Application Load Balancer components.
Figure 1. Mutual TLS with regional internal Application Load Balancer components (click to enlarge).

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:

  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 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.
  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 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:
  • For root and intermediate certificates:

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.

What's next