Set up frontend mTLS with user-provided certificates

A valid client certificate must show a chain of trust back to the trust anchor(root certificate) in the trust store. This page provides instructions forcreating your own trust chain by configuring your own root and intermediatecertificates using theOpenSSL library.

After creating the roots of trust, this document outlines the process to uploadthem to the trust store of the Certificate ManagerTrustConfig resource. This is followed by linking the trust config to theClient Authentication (ServerTLSPolicy) resource and then attachingthe Client Authentication resource to the target HTTPS proxy resourceof 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 can findcommands related to load balancing in theAPI and gcloud CLI reference.

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

  • Enable the following APIs: Compute Engine API, Certificate Manager API,Network Security, and Network Services API. To learn more, seeEnabling APIs.

  • 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
    • Private Service Connect backends

  • 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
    • Private Service Connect backends

  • Set your project.

    gcloud

    gcloud config set projectPROJECT_ID

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 asTargetHTTPSProxy: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.

Create the root and intermediate certificates

Note:

If you already have certificates to upload to the trust store, you can skipthis step and jump toFormat the certificates.

If you need to use a self-signed, expired, or otherwise invalid certificate, or if root and intermediate certificates are unavailable, you cancreate a self-signed certificate and then add it to an allowlist in the trust config.

This section uses theOpenSSL library to createthe root certificate (trust anchor) and the intermediate certificate.

A root certificate is at the topof the certificate chain. An intermediate certificate is a part of the chainof trust back to the root certificate. The intermediate certificate iscryptographically signed by the root certificate. When the load balancerreceives a client certificate, the load balancer validates it by establishing achain of trust from the client certificate back to the configured trust anchor.

Use the following commands to create the root and intermediate certificates. The creation of the intermediate certificate is optional. However, in this setup, we areusing the intermediate certificate to sign the client certificate.

  1. Create anOpenSSL configurationfile.

    In the following example, the configuration file (example.cnf) containsthe[ca_exts] section, which specifies X.509 extensions that mark thecertificate as suitable for a CA. To learn more about the requirements forroot and intermediate certificates, seeCertificaterequirements.

    cat >example.cnf <<EOF[req]distinguished_name=empty_distinguished_name[empty_distinguished_name]# Kept empty to allow setting via -subj command-line argument.[ca_exts]basicConstraints=critical,CA:TRUEkeyUsage=keyCertSignextendedKeyUsage=clientAuthEOF

  2. Create a self-signed X.509 root certificate (root.cert). The rootcertificate is self-signed with its own private key (root.key).

    opensslreq-x509\-new-sha256-newkeyrsa:2048-nodes\-days3650-subj'/CN=root'\-configexample.cnf\-extensionsca_exts\-keyoutroot.key-outroot.cert

  3. Create the certificate signing request (int.req) for the intermediatecertificate.

    opensslreq-new\-sha256-newkeyrsa:2048-nodes\-subj'/CN=int'\-configexample.cnf\-extensionsca_exts\-keyoutint.key-outint.req

  4. Sign the CSR to create the X.509 intermediate certificate (int.cert). TheCSR is signed using the root certificate.

    opensslx509-req\-CAkeyroot.key-CAroot.cert\-set_serial1\-days3650\-extfileexample.cnf\-extensionsca_exts\-inint.req-outint.cert

Create a self-signed certificate that can be added to an allowlist

Note:

If you already have certificates to upload to the trust store, you can skipthis step and jump toFormat the certificates.

You can create a self-signed certificate and add it to anallowlist in the trust config.

Use the following OpenSSL command to create a self-signed X.509 certificate.

opensslreq-x509\-new-sha256-newkeyrsa:2048-nodes\-days3650-subj'/CN=localhost'\-keyoutallowlisted.key-outallowlisted.cert

This certificate is thenadded to anallowlistedCertificates field in thetrust config.

Format the certificates

To include new or existing certificates in aTrustStore, format thecertificates into a single line and store them in environment variables, so thatthey can be referenced by the trust config YAML file.

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

To include new or existing certificates that are added to an allowlist in atrust config, format the certificates into a single lineand store them in environment variables, so that they can be read into the YAMLfile. For certificates that are on an allowlist, use the following command toformat the certificates into a single line and store them in theALLOWLISTED_CERT environment variable.

exportALLOWLISTED_CERT=$(catallowlisted.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. In theTrust store section, clickAdd intermediate CA andupload the PEM-encoded certificate file, or copy the contents of the certificate.

    This step lets you add another level of trust between the root certificate andyour server certificate.

  8. ClickAdd to add the intermediary CA.

  9. Optional: In theAllowlistedcertificates section, clickAdd certificate and upload thePEM-encoded certificate file, or copy the contents of the certificate.

  10. ClickAdd to add the allowlisted certificate.

  11. 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. This example trust configresource contains a trust store with a trust anchor and an intermediatecertificate. It reads the certificate content from the environment variablescreated in the previousFormat the certificates step.

    cat << EOF > trust_config.yamltrustStores:-trustAnchors:-pemCertificate:"${ROOT_CERT?}"intermediateCas:-pemCertificate:"${INTERMEDIATE_CERT?}"EOF

    To create a trust store with additional trust anchors or intermediatecertificates, addpemCertificate rows in the appropriate section.

  2. Optional: Specify the certificate thatis added to the trust config YAML file in theallowlistedCertificatesfield. You don't need a trust store to add a certificate to an allowlist.

    cat << EOF >> trust_config.yamlallowlistedCertificates:-pemCertificate:"${ALLOWLISTED_CERT?}"EOF

    Acertificate that is added to anallowlistrepresents any certificate that can be encapsulated within the trustconfig so that it is always considered valid. You can specify multiplecertificates in an allowlist by using multiple instances of thepemCertificate field.

  3. 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}"

Sign the client certificate with the intermediate certificate

This section provides an additional configuration option to generate a client (leaf)certificate. If you have alreadycreated a TrustConfig resource that contains anintermediate certificate, do the following:

  1. Create a configuration file to generate the CSR for the client certificate.

    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

    If you want to attach aSPIFFE identity to the configuration file, do the following:

    • Add asubjectAltName field to the[extension_requirements] section asfollows:

      subjectAltName            = @sans_list

    • Add a new section ([sans_list]) at the bottom of theclient.configfile as follows:

      [sans_list]URI.1                     = spiffe://example.com/test-identity

  2. Create the CSR (client.csr) for the client certificate.

    opensslreq-new\-configclient.config\-keyoutclient.key-outclient.csr

  3. Sign the CSR to issue the X.509 client certificate (client.cert). The CSRis signed by the intermediate certificate.

    opensslx509-req\-CAkeyint.key-CAint.cert\-days365\-extfileclient.config\-extensionsextension_requirements\-inclient.csr-outclient.cert

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

    curl -v --key client.key --cert client.cert https://IP_ADDRESS

    ReplaceIP_ADDRESS with 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.