How Certificate Manager works

Stay organized with collections Save and categorize content based on your preferences.

Certificate Manager uses a flexible mapping mechanism that provides you with granular control over which certificates you can assign and how to serve them for each hostname in your environment. The mechanism comprises the following entities:

  • Certificates
  • Certificate maps
  • Certificate map entries
  • Domain authorizations

The following diagram illustrates the relationships between these entities for a typical target proxy specified in a load balancer forwarding rule:

Certificate Manager entities
Certificate Manager entities

Certificate Manager supports target HTTPS proxies and target SSL proxies. For more information on the differences between these proxy types, see Using target proxies.

Certificates

By default, a certificate represents a single X.509 Transport Layer Security (TLS) (SSL) certificate that is issued for specific hostnames or domain wildcards.

Certificate Manager supports the following types of certificates:

  • Google-managed certificates are certificates that Google Cloud obtains and manages for you.
  • Self-managed certificates are certificates that you obtain, provision, and renew yourself.

When you issue a certificate using a publicly trusted CA, the CA publishes information about the associated domain to Certificate Transparency logs, which are publicly accessible. This is part of the standard certificate issuance process adopted by all publicly trusted CAs, and it applies to both Google-managed certificates and self-managed certificates. However, if you use the Certificate Authority Service to issue your Google-managed certificate, Certificate Manager does not publish any information to Certificate Transparency logs.

For more information, see Certificate Transparency.

To learn how to deploy a certificate with Certificate Manager, see Deployment overview.

Google-managed certificates

Certificate Manager lets you manage the lifecycle of your Google-managed TLS (SSL) certificates from issuance to renewal. You can verify relevant domain ownership by using either load balancer-based or DNS-based authorization. Certificate Manager supports RSA Google-managed certificates.

By default, Google-managed certificates are issued by the Google CA. If you cannot obtain a certificate from the Google CA for a particular domain, Certificate Manager falls back to the Let's Encrypt CA. For example, the Google CA might refuse to issue a certificate for the domain, or your CA Authorization record explicitly prohibits the Google CA from issuing certificates for that domain.

For instructions about how to restrict the CAs that can issue certificates for your domains, see Specifying the CAs that can issue your Google-managed certificate.

Google-managed certificates issued by the Certificate Authority Service

If you want to use your own trust chain rather than rely on Google-approved public CAs to issue your certificates, you can configure Certificate Manager to use a CA pool from the Certificate Authority Service as the certificate issuer instead. For more information about CA pools, see Creating CA Pools.

Self-managed certificates

If your business requirements do not allow you to use Google-managed certificates, you can upload certificates issued by external CAs along with their associated keys. You are responsible for manually issuing and renewing self-managed certificates.

Certificate maps

A certificate map references one or more certificate map entries that assign specific certificates to specific hostnames. Certificate map entries also define the selection logic that the load balancer follows when establishing client connections. You can associate a certificate map with multiple target proxies for reuse across multiple load balancers.

If a client requests a hostname specified in a certificate map, the load balancer serves the certificates mapped to that hostname. Otherwise, the load balancer serves the primary certificate. For more information, see Certificate selection logic.

Certificate map entries

A certificate map entry is a list of certificates served for a specific hostname. You can define different sets of certificates for different hostnames, such as domains or subdomains. For example, you can upload an ECDSA and an RSA certificate and map them to the same hostname. When a client connects to that hostname, the load balancer negotiates the type of certificate to serve to the client during the handshake.

Domain authorizations

Certificate Manager lets you prove ownership of domains for which you want to issue Google-managed certificates as described in the following table:

Load balancer authorization DNS authorization
Setup complexity Does not require additional configuration steps or changes to your DNS configuration. Requires you to create a DNS authorization and add its corresponding CNAME record to your DNS configuration.
Network security The load balancer must be fully accessible from the Internet on port 443, including the DNS configuration for all domains served by the certificate. Does not work with other configurations. Works with high-complexity configurations, such as ports other than 443 and CDN layers in front of the target proxy.
Provisioning speed You can provision certificates only after the load balancer has been fully set up and is serving network traffic. You can provision certificates in advance, before the target proxy is ready to serve network traffic.

See Domain authorizations for Google-managed certificates to understand how Certificate Manager verifies domain ownership using each method.

Certificate issuance configs

A certificate issuance config is a resource that allows Certificate Manager to use a CA pool from your own Certificate Authority Service instance to issue Google-managed certificates instead of the Google CA or the Lets Encrypt CA. It allows you to specify a number of parameters that govern certificate issuance and expiration as well as select the key algorithm for certificates issued this way.

Certificate selection logic

At a high level, the load balancer selects a certificate as follows:

  1. A client initiates a handshake. During this step, it provides the load balancer with a list of cryptographic algorithms it can use to complete the handshake, and, optionally, a hostname.
  2. Depending on whether the client supplies a hostname and how closely it matches the hostnames configured in the provisioned certificate map entries, the load balancer completes one or more of the following steps:
    • If the client supplies a hostname, the load balancer searches for a certificate map entry which matches it exactly. If one exists, the load balancer searches within that certificate map entry for a certificate compatible with one of the cryptographic algorithms specified by the client. If it finds one, it uses that certificate to complete the handshake.
    • If the client-supplied hostname does not exactly match any hostnames specified in the provisioned certificate map entries, the load balancer then searches for a certificate map entry containing a wildcard. For example, a wild card entry configured as *.example.com covers first-level subdomains under the example.com domain. If one exists, the load balancer searches within that certificate map entry for a certificate compatible with one of the cryptographic algorithms specified by the client. If it finds one, it uses that certificate to complete the handshake.
    • If the client supplies a hostname that does not match any exact or wildcard hostnames specified in all provisioned certificate map entries, or does not supply a hostname at all, and you have configured a primary certificate map entry, the load balancer searches within its primary certificate map entry for a certificate compatible with the cryptographic algorithms specified by the client. If it finds one, it uses that certificate to complete the handshake. If it does not find one, or if you have not configured a primary certificate map entry, the handshake fails and the load balancer rejects the connection.

Certificate priority

The load balancer selects a certificate within a certificate map entry based on the following:

  • Certificate type. If the connecting client supports the more secure ECDSA certificates, the load balancer prioritizes them over RSA certificates. If the client does not indicate support for ECDSA certificates, the load balancer serves an RSA certificate instead.
  • Certificate size. The load balancer prioritizes certificates from smallest to largest.

Wildcard hostnames

The following rules apply to wildcard hostnames:

  • An exact match takes precedence over a wildcard when both are defined in the entry. For example, if you configured certificate map entries for www.example.com and *.example.com, a connection request against www.example.com always selects the entry for www.example.com even if an entry for *.example.comalso exists.
  • Wildcard hostnames only match down to one subdomain level. For example, a connection request for host1.example.com selects a certificate map entry for *.example.com but not one for host1.hosts.example.com.

Public CA

To use the public CA feature of Certificate Manager, you must be familiar with the following concepts:

  • ACME client. An Automatic Certificate Management Environment (ACME) client is a certificate management client that uses the ACME protocol. Your ACME client must support external account binding (EAB) to work with Certificate Manager Public CA.

  • External account binding (EAB). You must bind each ACME account you are using with Certificate Manager public CA to the target Cloud project using external account binding. To do this, you must register each ACME account using a secret linked to its corresponding Cloud project. For more information, see External account binding.

Public CA challenges

When you use Certificate Manager Public CA to request a certificate, Certificate Manager asks you to prove your control over the domains listed in that certificate. You can prove domain control by solving challenges. Certificate Manager Public CA authorizes the domain names after you prove your control of the target domains.

After you obtain the required authorizations, you can request certificates that are valid only for a specific time duration. After this duration, you must revalidate the domain name by solving one of the three challenge types to continue requesting certificates.

Challenge types

Certificate Manager Public CA supports the following types of challenges:

  • HTTP challenge. This challenge involves creating a file at a well-known location on an HTTP server (port 80) for Certificate Manager Public CA to retrieve and verify. For more information, see HTTP challenge.

  • TLS-Application Layer Protocol Negotiation (ALPN) challenge. Requires a server to provide a specific certificate during a TLS negotiation on port 443 to prove control over a domain. For more information, see ACME TLS-ALPN challenge extension.

  • DNS challenge. Requires adding a specific DNS record at a defined location to prove control over a domain. For more information, see DNS challenge.

If you use the HTTP challenge or the TLS-ALPN challenge to validate a domain name, the client can only request the validated domain names to be included in a certificate. If you use the DNS challenge, the client can also request subdomains of that domain name to be included in a certificate.

For example, if you validate *. example.com using the DNS challenge then subdomain1.example.com and subdomain2.example.com are automatically covered by the wildcard certificate. However, if you validate example.com using an HTTP or TLS-ALPN challenge the client can only request to include example.com in the certificate and you cannot validate *. example.com using the non-DNS challenges.

Challenge solution logic

The public CA challenge logic is as follows:

  1. Certificate Manager Public CA provides a random token.
  2. The client makes the token available at a well-defined location. The location depends on the challenge.
  3. The client indicates to Certificate Manager Public CA that it has prepared the challenge.
  4. Certificate Manager Public CA checks if the token present at the expected location matches the expected value.

The domain name is authorized after this process is completed. The client can request a certificate with that domain name in it. You need to solve only one challenge per domain name.