Set up frontend mTLS with a private CA

A valid client certificate must show a chain of trust back to the trust anchorin the trust store. This page provides instructions for creating your own trustchain using the root certificate of a private CA (certificateauthority), which is in your control. In this setup, the private CA is created using theCertificate Authority Service.

After obtaining the root certificate of the private CA, this documentoutlines the process to upload the certificate to the trust store of theCertificate ManagerTrustConfig resource. This is followed by linkingthe trust config to the Client Authentication (ServerTLSPolicy)resource and then attaching the Client Authentication resource to thetarget HTTPS proxy resource of the load balancer.

Before you begin

  • Review theMutual TLS overview.
  • Review the guide toManage trustconfigs.

  • Install the Google Cloud CLI. For a complete overview of the tool,see thegcloud CLI overview. You canfind commands related to load balancing in theAPI and gcloud CLI reference.

    If you haven't run the gcloud CLI previously, first rungcloud init to authenticate.

  • Review the guide tocreate a CA pool.

  • If you are using global external Application Load Balancer or classic Application Load Balancer, make sureyou have set up a load balancer with any of the following supported backends:

    • VM instance group backends
    • Cloud Storage buckets(Supported only if there is at least one backend service also attached tothe load balancer, in addition to the backend bucket)
    • Cloud Run, App Engine, or Cloud Run functions
    • Hybrid connectivity

  • If you are using regional external Application Load Balancer, cross-region internal Application Load Balancer,or regional internal Application Load Balancer, make sure you have set up a load balancer with anyof the following supported backends:

    • VM instance group backends
    • Cloud Run
    • Hybrid connectivity

Permissions

To get the permissions that you need to complete this guide, ask your administrator to grant you the following IAM roles on the project:

  • To create load balancer resources such asTargetHTTPProxy:Compute Load Balancer Admin (roles/compute.loadBalancerAdmin)
  • To use Certificate Manager resources:Certificate Manager Owner (roles/certificatemanager.owner)
  • To create security and networking components: Compute Network Admin (roles/compute.networkAdmin) and Compute Security Admin (roles/compute.securityAdmin)
  • To create a project (optional):Project Creator (roles/resourcemanager.projectCreator)

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Note:IAM basic roles might also contain permissions to complete this guide. You shouldn't grant basic roles in a production environment, but you can grant them in a development or test environment.

Get the root CA's certificate

The root CA has a self-signed certificate that you need to add to the truststore. The root CA's certificate is at the top of the certificate chain.

To get the root CA's certificate, you need to first create aCA pool, which is empty on creation. You then need create a root CA and add itto the CA pool. The root CA and the CA pool is created using theCertificate Authority Service as outlined in the following steps.

  1. To create a CA pool, use thegcloud privateca pools create command:

    gcloud privateca pools createCA_POOL \   --location=us-central1

    ReplaceCA_POOL with the ID or name of theparent CA pool.

  2. To create a root CA and add it to the CA pool, use thegcloud privateca roots create command:

    gcloud privateca roots createCA_ROOT \   --pool=CA_POOL \   --subject="CN=my-ca, O=Test LLC" \   --location=us-central1

    Replace the following:

    • CA_ROOT: the ID or name of the root CA.
    • CA_POOL: the ID or name of the parent CA pool.

  3. Extract the PEM-encoded certificate that identifies the root CA.

    gcloud privateca roots describeCA_ROOT \   --pool=CA_POOL \   --location=us-central1 \   --format='value(pemCaCertificates)' > root.cert

    Replace the following:

    • CA_ROOT: the ID or name of the private CA.
    • CA_POOL: the ID or name of the parent CA pool.

    The root certificate (root.cert) needs to be uploaded to the trust store.This step will be carried out in the following section.

For more information on using Certificate Authority Service to create a CA pool and a rootCA, see the following:

Format the root CA certificate

To include the root certificate in a trust store, format the certificate intoa single line and store it in an environment variable, so that it can bereferenced by the trust config YAML file.

exportROOT=$(catroot.cert|sed's/^[ ]*//g'|tr'\n'$|sed's/\$/\\n/g')

Create a trust config resource

A trust config is a resource that represents your Public Key Infrastructure (PKI) configuration in Certificate Manager.

To create a trust config resource, complete the following steps:

Console

  1. In the Google Cloud console, go to theCertificate Manager page.

    Go to Certificate Manager

  2. On theTrust Configs tab, clickAdd Trust Config.

  3. Enter a name for the configuration.

  4. ForLocation, selectGlobal orRegional.

    The location denotes where the trust config resource is stored. For global external Application Load Balancers, classic Application Load Balancers, and cross-region internal Application Load Balancers, create aglobal trustconfig resource. For regional external Application Load Balancers andregional internal Application Load Balancers, create aregional trust config resource.

    If you selectedRegional, select the region.

  5. In theTrust store section, clickAdd trust anchor and upload thePEM-encoded certificate file, or copy the contents of the certificate.

  6. ClickAdd.

  7. ClickCreate.

Verify that the new trust config resource appears in the list of configurations.

gcloud

  1. Create a trust config YAML file (trust_config.yaml) that specifies thetrust config parameters. In this example, the trust config resource is atrust store with a single trust anchor that represents a rootcertificate. This root certificate is generated using the private CA.

    cat << EOF > trust_config.yamlname:TRUST_CONFIG_NAMEtrustStores:-trustAnchors:-pemCertificate:"${ROOT?}"EOF

  2. To import the trust config YAML file, use thegcloud certificate-manager trust-configs import command:

    global

    For global external Application Load Balancers, classic Application Load Balancers, andcross-region internal Application Load Balancers, specifyglobal as the location wherethe trust config resource is stored.

    gcloud certificate-manager trust-configs importTRUST_CONFIG_NAME  \    --source=trust_config.yaml \    --location=global

    Replace the following:

    • TRUST_CONFIG_NAME: the name of the trust config resource.

    regional

    For regional external Application Load Balancers and regional internal Application Load Balancers, specifythe region where the trust config resource is stored.

    gcloud certificate-manager trust-configs importTRUST_CONFIG_NAME  \    --source=trust_config.yaml \    --location=LOCATION

    Replace the following:

    • TRUST_CONFIG_NAME: the name of the trust config resource.
    • LOCATION: the region where the trust configresource is stored. The default location isglobal.

Create a Client Authentication resource

A Client Authentication (also calledServerTLSPolicy) resource letsyou specify the server-side TLS mode and the trust config resource to usewhen validating client certificates. When the client presents an invalidcertificate or no certificate to the load balancer, theclientValidationModespecifies how the client connection is handled. For more information, seemTLS client validation modes.

  • When theclientValidationMode is set toALLOW_INVALID_OR_MISSING_CLIENT_CERT,all requests are passed to the backend even if the validation fails or theclient certificate is missing.
  • When theclientValidationMode is set toREJECT_INVALID, only requests thatsupply a client certificate that can be validated against aTrustConfigresource are passed to the backend.

To create a Client Authentication (ServerTlsPolicy) resource,complete the following steps:

Console

  1. In the Google Cloud console, go to theAuthentication Configuration page.

    Go to Authentication Configuration

  2. On theClient Authentication tab, clickCreate.

  3. Enter a name for the Client Authentication resource.

  4. ForLocation, selectGlobal orRegional.

    For global external Application Load Balancers, classic Application Load Balancers, andcross-region internal Application Load Balancers, set the location to global. Forregional external Application Load Balancers and regional internal Application Load Balancers, set the location tothe region where the load balancer is configured.

  5. ForClient Authentication mode, selectLoad balancing.

  6. Select a client validation mode.

  7. Select the trust config resource that you created earlier.

  8. ClickCreate.

Verify that the Client Authentication (ServerTlsPolicy) is displayed.

gcloud

  1. Based on how you want to handle the connection, select one of thefollowing options to define the Client Authentication(ServerTlsPolicy) resource in YAML format.

    • Option 1:clientValidationMode is set toALLOW_INVALID_OR_MISSING_CLIENT_CERT.

      global

      For global external Application Load Balancers, classic Application Load Balancers, andcross-region internal Application Load Balancers, create a YAMLfile that declaratively specifies the client validation mode and a global trust config resource:

      cat<< EOF > server_tls_policy.yamlname:SERVER_TLS_POLICY_NAMEmtlsPolicy:    clientValidationMode: ALLOW_INVALID_OR_MISSING_CLIENT_CERT    clientValidationTrustConfig: projects/PROJECT_ID/locations/global/trustConfigs/TRUST_CONFIG_NAMEEOF

      regional

      For regional external Application Load Balancers and regional internal Application Load Balancers, createa YAML file that declaratively specifies the client validationmode and a regional trust config resource:

      cat<< EOF > server_tls_policy.yamlname:SERVER_TLS_POLICY_NAMEmtlsPolicy:    clientValidationMode: ALLOW_INVALID_OR_MISSING_CLIENT_CERT    clientValidationTrustConfig: projects/PROJECT_ID/locations/REGION/trustConfigs/TRUST_CONFIG_NAMEEOF

    • Option 2:clientValidationMode is set toREJECT_INVALID.

      global

      For global external Application Load Balancers, classic Application Load Balancers, andcross-region internal Application Load Balancers, create a YAMLfile that declaratively specifies the client validation mode and aglobal trust config resource:

      cat<< EOF > server_tls_policy.yamlname:SERVER_TLS_POLICY_NAMEmtlsPolicy:    clientValidationMode: REJECT_INVALID    clientValidationTrustConfig: projects/PROJECT_ID/locations/global/trustConfigs/TRUST_CONFIG_NAMEEOF

      regional

      For regional external Application Load Balancers and regional internal Application Load Balancers, createa YAML file that declaratively specifies the client validationmode and a regional trust config resource:

      cat<< EOF > server_tls_policy.yamlname:SERVER_TLS_POLICY_NAMEmtlsPolicy:      clientValidationMode: REJECT_INVALID      clientValidationTrustConfig: projects/PROJECT_ID/locations/REGION/trustConfigs/TRUST_CONFIG_NAMEEOF

      Replace the following:

      SERVER_TLS_POLICY_NAME: the name of the Client Authentication (ServerTlsPolicy) resource.

      PROJECT_ID: the ID of your Google Cloud project.

      LOCATION: for global external Application Load Balancers, classic Application Load Balancers,and cross-region internal Application Load Balancers, useglobal.For regional external Application Load Balancer or regional internal Application Load Balancer, use the regionwhere you configured the load balancer.

      TRUST_CONFIG_NAME: the name of the trust config resourcethat you created earlier.

  2. To import the Client AuthenticationServerTlsPolicy resource,use thegcloud network-security server-tls-policies importcommand:

    global

    For global external Application Load Balancers, classic Application Load Balancers, andcross-region internal Application Load Balancers, set the--location flag toglobal.

    gcloud network-security server-tls-policies importSERVER_TLS_POLICY_NAME \  --source=server_tls_policy.yaml \  --location=global

    Replace the following:

    SERVER_TLS_POLICY_NAME: the name of the Client Authentication (ServerTlsPolicy) resource.

    regional

    For regional external Application Load Balancers and regional internal Application Load Balancers, set the--location flag to the region where the load balancer is configured.

    gcloud network-security server-tls-policies importSERVER_TLS_POLICY_NAME \  --source=server_tls_policy.yaml \  --location=LOCATION

    Replace the following:

    SERVER_TLS_POLICY_NAME: the name of the Client Authentication (ServerTlsPolicy) resource.

  3. Optional: To list all the Client Authentication(ServerTlsPolicies) resources, use thegcloud network-security server-tls-policies list command:

    gcloud network-security server-tls-policies list \  --location=LOCATION

    Replace the following:

    LOCATION: For global external Application Load Balancers,classic Application Load Balancers, and cross-region internal Application Load Balancers, useglobal. For regional external Application Load Balancer orregional internal Application Load Balancer, use the region where you configured the loadbalancer.

Note: To modify the Client Authentication (ServerTlsPolicy) resource,you must first delete the existing Client Authentication resource andthen create a new Client Authentication resource. You can then attachthe Client Authentication resource to the target HTTPS proxy of the loadbalancer.

Attach the Client Authentication resource to the load balancer

For mutual TLS authentication to work, after you set up your load balancer, youneed to attach the Client Authentication (ServerTLSPolicy) resourceto the target HTTPS proxy resource of the load balancer.

Console

  1. In the Google Cloud console, go to theLoad balancing page.

    Go to Load balancing

  2. From the list of load balancers, select the load balancer to which you need to attach the Client Authentication (ServerTLSPolicy) resource to.

  3. ClickEdit.

  4. In theFrontend configuration section for an HTTPS frontend, expandtheShow Advanced features section.

  5. From theClient Authentication list, select the Client Authenticationresource.

  6. ClickDone.

  7. ClickUpdate.

gcloud

  1. To list all the target HTTPS proxy resources in your project, use thegcloud compute target-https-proxies list command:

    gcloud compute target-https-proxies list

    Note the name of the target HTTPS proxy to attach theServerTLSPolicy resource to.This name is referred to asTARGET_HTTPS_PROXY_NAMEin the following steps.

  2. To export a target HTTPS proxy's configuration to a file, use thegcloud compute target-https-proxies export command.

    global

      gcloud compute target-https-proxies exportTARGET_HTTPS_PROXY_NAME \      --destination=TARGET_PROXY_FILENAME \      --global

    Replace the following:

    • TARGET_HTTPS_PROXY_NAME: the name of the targetproxy.
    • TARGET_PROXY_FILENAME: the name of the target proxy's configuration file in YAML format.For example,mtls_target_proxy.yaml.

    regional

    gcloud compute target-https-proxies exportTARGET_HTTPS_PROXY_NAME \    --destination=TARGET_PROXY_FILENAME \    --region=REGION

    Replace the following:

    • TARGET_HTTPS_PROXY_NAME: the name of the targetproxy.
    • TARGET_PROXY_FILENAME: the name of the target proxy's configuration file in YAML format.For example,mtls_target_proxy.yaml
    • REGION: the region where you configured theload balancer.

  3. To list all the Client Authentication(ServerTlsPolicy) resources, use thegcloud network-security server-tls-policies list command:

    gcloud network-security server-tls-policies list \    --location=LOCATION

    Replace the following:

    LOCATION: for cross-region internal Application Load Balancer,global external Application Load Balancer, or classic Application Load Balancer, useglobal. For regional external Application Load Balancer or regional internal Application Load Balancer,use the region where you configured the load balancer.

    Note the name of the Client Authentication (ServerTLSPolicy)resource to configure mTLS. This name is referred to asSERVER_TLS_POLICY_NAME in the next step.

  4. Append the Client Authentication (ServerTlsPolicy) to thetarget HTTPS proxy.

    echo "serverTlsPolicy://networksecurity.googleapis.com/projects/PROJECT_ID/locations/LOCATION/serverTlsPolicies/SERVER_TLS_POLICY_NAME" >>TARGET_PROXY_FILENAME

    Replace the following:

    • PROJECT_ID: the ID of your Google Cloud project.
    • LOCATION: for global external Application Load Balancers orclassic Application Load Balancers, andcross-region internal Application Load Balancers, useglobal. For regional external Application Load Balancer or regional internal Application Load Balancer,use the region where you configured the load balancer.
    • SERVER_TLS_POLICY_NAME: the name of the Client Authentication (ServerTLSPolicy) resource.
    • TARGET_PROXY_FILENAME: the name of the target proxy'sconfiguration file in YAML format.

  5. To import a target HTTPS proxy's configuration from a file, use thegcloudcompute target-https-proxies import command.

    global

      gcloud compute target-https-proxies importTARGET_HTTPS_PROXY_NAME \      --source=TARGET_PROXY_FILENAME \      --global

    Replace the following:

    • TARGET_HTTPS_PROXY_NAME: the name of the targetproxy.
    • TARGET_PROXY_FILENAME: the name of the target proxy's configuration file in YAML format.For example,mtls_target_proxy.yaml.

    regional

      gcloud compute target-https-proxies importTARGET_HTTPS_PROXY_NAME \      --source=TARGET_PROXY_FILENAME \      --region=REGION

    Replace the following:

    • TARGET_HTTPS_PROXY_NAME: the name of the targetproxy.
    • TARGET_PROXY_FILENAME: the name of the target proxy'sconfiguration file in YAML format. For example,mtls_target_proxy.yaml
    • REGION: the region where you configured theload balancer.

Add mTLS custom headers

When you enable mTLS, you can pass information about the mTLS connectionusing custom headers. You can also enable logging so thatmTLS connection failuresare captured in the logs.

Add mTLS custom headers to backend services

For global external Application Load Balancers or classic Application Load Balancers, you can usecustom headers to pass information about the mTLS connectiontobackend services.

  1. To list all the backend services in the project, use thegcloudcompute backend-services list command:

    gcloud compute backend-services list

    Note the name of the backend service to enable custom headers and logging.This name is referred to asBACKEND_SERVICE inthe following step.

  2. To update the backend service, use thegcloudcompute backend-services update command:

    gcloud compute backend-services updateBACKEND_SERVICE \  --global \  --enable-logging \  --logging-sample-rate=1 \  --custom-request-header='X-Client-Cert-Present:{client_cert_present}' \  --custom-request-header='X-Client-Cert-Chain-Verified:{client_cert_chain_verified}' \  --custom-request-header='X-Client-Cert-Error:{client_cert_error}' \  --custom-request-header='X-Client-Cert-Hash:{client_cert_sha256_fingerprint}' \  --custom-request-header='X-Client-Cert-Serial-Number:{client_cert_serial_number}' \  --custom-request-header='X-Client-Cert-SPIFFE:{client_cert_spiffe_id}' \  --custom-request-header='X-Client-Cert-URI-SANs:{client_cert_uri_sans}' \  --custom-request-header='X-Client-Cert-DNSName-SANs:{client_cert_dnsname_sans}' \  --custom-request-header='X-Client-Cert-Valid-Not-Before:{client_cert_valid_not_before}' \  --custom-request-header='X-Client-Cert-Valid-Not-After:{client_cert_valid_not_after}'
Note:

You can provide your own custom header names. The names used in the--custom-request-header options are just examples.

You can enable some or all of the mTLS custom headers.

Add mTLS custom headers to URL map

For cross-region internal Application Load Balancer, regional external Application Load Balancer, orregional internal Application Load Balancer, you can usecustom headers to pass information about the mTLS connection to theURL map.

To list all the URL maps in the project, use thegcloud compute url-maps list command:

   gcloud compute url-maps list

Note the name of the URL map to enable custom headers and logging. This name is referred to asURL_MAP_NAME in the following step.

global

To edit the URL map for a cross-region internal Application Load Balancer, use thegcloud compute url-maps edit command:

   gcloud compute url-maps editURL_MAP_NAME --global

Following is a sample YAML file that shows you how to use variables in custom request headers (requestHeadersToAdd). You can use the same variables to send custom response headers (responseHeadersToAdd).

   headerAction:      requestHeadersToAdd:      - headerName: "X-Client-Cert-Present"        headerValue: "{client_cert_present}"      - headerName: "X-Client-Cert-Chain-Verified"        headerValue: "{client_cert_chain_verified}"      - headerName: "X-Client-Cert-Error"        headerValue: "{client_cert_error}"      - headerName: "X-Client-Cert-Hash"        headerValue: "{client_cert_sha256_fingerprint}"      - headerName: "X-Client-Cert-Serial-Number"        headerValue: "{client_cert_serial_number}"      - headerName: "X-Client-Cert-SPIFFE"        headerValue: "{client_cert_spiffe_id}"      - headerName: "X-Client-Cert-URI-SANs"        headerValue: "{client_cert_uri_sans}"      - headerName: "X-Client-Cert-DNSName-SANs"        headerValue: "{client_cert_dnsname_sans}"      - headerName: "X-Client-Cert-Valid-Not-Before"        headerValue: "{client_cert_valid_not_before}"      - headerName: "X-Client-Cert-Valid-Not-After"        headerValue: "{client_cert_valid_not_after}"      - headerName: "X-Client-Cert-Issuer-Dn"        headerValue: "{client_cert_issuer_dn}"      - headerName: "X-Client-Cert-Subject-Dn"        headerValue: "{client_cert_subject_dn}"      - headerName: "X-Client-Cert-Leaf"        headerValue: "{client_cert_leaf}"      - headerName: "X-Client-Cert-Chain"        headerValue: "{client_cert_chain}"

regional

To edit the URL map for a regional external Application Load Balancer or a regional internal Application Load Balancer, use thegcloud compute url-maps edit command:

   gcloud compute url-maps editURL_MAP_NAME --region=REGION

Following is a sample YAML file that shows you how to use variables in custom request headers (requestHeadersToAdd). You can use the same variables to send custom response headers (responseHeadersToAdd).

   defaultService: regions/REGION/backendServices/BACKEND_SERVICE_1      name: regional-lb-map      region: region/REGION   headerAction:      requestHeadersToAdd:      - headerName: "X-Client-Cert-Present"        headerValue: "{client_cert_present}"      - headerName: "X-Client-Cert-Chain-Verified"        headerValue: "{client_cert_chain_verified}"      - headerName: "X-Client-Cert-Error"        headerValue: "{client_cert_error}"      - headerName: "X-Client-Cert-Hash"        headerValue: "{client_cert_sha256_fingerprint}"      - headerName: "X-Client-Cert-Serial-Number"        headerValue: "{client_cert_serial_number}"      - headerName: "X-Client-Cert-SPIFFE"        headerValue: "{client_cert_spiffe_id}"      - headerName: "X-Client-Cert-URI-SANs"        headerValue: "{client_cert_uri_sans}"      - headerName: "X-Client-Cert-DNSName-SANs"        headerValue: "{client_cert_dnsname_sans}"      - headerName: "X-Client-Cert-Valid-Not-Before"        headerValue: "{client_cert_valid_not_before}"      - headerName: "X-Client-Cert-Valid-Not-After"        headerValue: "{client_cert_valid_not_after}"      - headerName: "X-Client-Cert-Issuer-Dn"        headerValue: "{client_cert_issuer_dn}"      - headerName: "X-Client-Cert-Subject-Dn"        headerValue: "{client_cert_subject_dn}"      - headerName: "X-Client-Cert-Leaf"        headerValue: "{client_cert_leaf}"      - headerName: "X-Client-Cert-Chain"        headerValue: "{client_cert_chain}"

Get a client certificate using a CSR

This section provides an additional configuration option to generate a client(leaf) certificate that is signed by the root CA's certificate.

To obtain a client certificate, generate a certificate signing request (CSR) and submit it to the CA pool.

  1. Create an OpenSSL configuration file to generate the CSR for the clientcertificate.

    The following configuration file (client.config) contains the[extension_requirements] section, which specifies the X.509 extensions to include in the CSR. To learn more about the requirements for client certificates, seeCertificate requirements.

    Note: If the key is used on a server, you can addserverAuth to theextendedKeyUsage field.
    cat >client.config <<EOF[req]default_bits=2048req_extensions=extension_requirementsdistinguished_name=dn_requirementsprompt=no[extension_requirements]basicConstraints=critical,CA:FALSEkeyUsage=critical,nonRepudiation,digitalSignature,keyEnciphermentextendedKeyUsage=clientAuth[dn_requirements]countryName=USstateOrProvinceName=CalifornialocalityName=SanFrancisco0.organizationName=exampleorganizationalUnitName=testcommonName=test.example.comemailAddress=test@example.comEOF

  2. Run the followingopenssl command to generate a CSR (csr.pem) and acorresponding private key (key.pem).

    openssl req -newkey rsa:2048 -nodes \    -config client.config \    -keyout key.pem \    -out csr.pem

  3. Run the followinggcloud privateca certificatescreate command tosubmit the CSR and request the X.509 client certificate from the CA in theCA pool.

    gcloud privateca certificates create \     --issuer-poolCA_POOL \     --issuer-location=us-central1 \     --csr csr.pem \     --cert-output-fileCERT_FILENAME

    Replace the following:

    • CA_POOL: the ID or name of the CA pool.
    • CERT_FILENAME: the PEM-encoded certificate chainfile that is ordered from leaf to root.

  4. Send a secure HTTPS request to the load balancer's IP address using theclient-side SSL certificate. The client presents its certificateto authenticate itself to the load balancer.

    curl -v --key key.pem --certCERT_FILENAME https://IP_ADDRESS

    Replace the following:

    • CERT_FILENAME: the PEM-encoded certificate chain file that is ordered from leaf to root.
    • IP_ADDRESS: the load balancer's IP address.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.