Securing Custom Domains with SSL

Python 2.7/3.7 |Java 8 |PHP 5.5/7.2 |Go 1.9/1.11 |Node.js 8

SSL support for your App Engine app goes above and beyond basic SSL by offering globally-distributed SSL endpoints and built-in load balancing to serve your app securely, reliably, and quickly to a worldwide audience.

By default, HTTPS connections on your custom domain will be enabled automatically using managed SSL certificates. Once your custom domain is mapped to your application and you have configured your DNS records, App Engine provisions a managed SSL certificate, handles renewing the certificate before it expires, and revokes it when you remove the custom domain from your application.

Before you begin

• Make sure you have already set up your custom domain in your App Engine project.

• If you choose to use the gcloud tool commands:

  1. Install and initialize the Cloud SDK:

     Download and install

• If you choose to use the Admin API, see the prerequisite information in Accessing the Admin API.

Note: Some of the gcloud commands and Admin API methods that are used in this topic are beta-level features.

Verify a managed certificate has been provisioned

After you set up your custom domain and update the DNS records, a managed SSL certificate is automatically provided within a few minutes. The managed certificate is signed by Let's Encrypt.

To verify that the certificate has been provisioned:

console

1. In the Google Cloud Platform Console, go to App Engine > Settings > Custom Domains:

   Go to the custom domains page

2. The SSL security, should display as Google managed:

   

gcloud

1. Run the following gcloud app domain-mappings command to verify your certificate has been provisioned for your App Engine app:

   gcloud app domain-mappings list

2. You should see a list of your domains, subdomains, and all their corresponding certificates, for example:

   ID               SSL_CERTIFICATE_ID
   example.com      123456
   www.example.com  234567

   It might take a few minutes for the certificate to be provisioned. During this time, the certificate shows up as PENDING_AUTO_CERT.

Troubleshooting managed SSL certificates

• You might need to update the DNS records for your custom domain to verify your domain name. App Engine cannot provision certificates for unverified domains.

• You can check the status of your certificate with the Admin API by using an AuthorizedCertificate.GET request.

• If a managed certificate has not been provisioned because the DNS records are not available, the ManagedCertificate.ManagementStatus field might be FAILED_RETRYING_NOT_VISIBLE. Verify that you your DNS records are up to date, wait a few minutes, then try again. It can take up to 24 hours for DNS records to become available.

• If the status is FAILED_PERMANENT, then all renewal attempts have failed. Check your DNS settings then update your custom domain mapping by following the steps to update to managed SSL certificates.

Upgrading to managed SSL certificates

Before you upgrade to Google-managed SSL certificates, note that managed certificates do not support wildcard mappings.

If you are using subdomains, there is a limit of 20 managed certificates per week for each base domain. If you encounter the limit, App Engine keeps trying to issue managed certificates until all requests have been fulfilled.

To move from your own SSL certificates to Google-managed SSL certificates, or to add managed SSL certificates to an existing app with a custom domain, update your domain mapping:

console

1. In the Google Cloud Platform Console, go to App Engine > Settings > Custom Domains:

   Go to the custom domains page

2. Select the domain you want to secure, and click Enable SSL security.

   

gcloud

Run the following gcloud app domain-mappings command to update the mapping of the domain to your application:

gcloud app domain-mappings update DOMAIN --certificate-management='AUTOMATIC'

API

To programmatically update your domain mapping to move to managed SSL certificates, see the apps.domainMappings.patch method in the Admin API.

Disabling managed SSL certificates

To disable managed SSL certificates:

console

1. In the Google Cloud Platform Console, go to App Engine > Settings > Custom Domains:

   Go to the custom domains page

2. Select the domain and click Disable SSL security.

   

gcloud

You can disable a managed SSL certificate that is already associated with a domain mapping. Alternatively, you can choose not to use a managed SSL certificate when you first map the custom domain.

• To remove a certificate from an existing mapping, run the following gcloud app domain-mappings command:

  gcloud app domain-mappings update DOMAIN --certificate-management='MANUAL'
  

• To specify not using a managed SSL certificate when you first map a new custom domain to your application:

  gcloud app domain-mappings create DOMAIN --certificate-management='MANUAL'
  

API

To programmatically disable managed SSL certificates, specify manual SSL management with the apps.domainMappings.patch method in the Admin API.

Using your own SSL certificates

Instead of using managed SSL certificates, you can use your own certificate. If your certificate does not have a transparency proof, your app may show SSL warnings in Chrome due to certificate transparency proof enforcement. For more information on certificate transparency proofs and how to comply, read Enforcing Certificate Transparency.

To use and manage your own SSL certificates instead of Google-managed certificates:

1. Make sure you have already set up your custom domain in your App Engine project.

2. Disable the default Google-managed certificates.

3. Get a certificate for your domain from the certificate authority (CA) of your choice. The exact procedure can vary depending on the authority but see Obtaining a certificate for the typical steps.

4. Convert your private key and SSL certificate files into formats that are supported by App Engine. Before you can upload your files, your private key must be converted to an RSA private key and your SSL certificates must be concatenated into a single file. For more information, see Converting your private keys and concatenating your SSL certificates.

5. Ensure you have the right permissions in the GCP Console and verified ownership (step 3) of all related domains or their parent domains. For example:

   • If the certificate is for www.example.com you can verify ownership of either www.example.com or example.com.
   • If the certificate is for www.example.com and sub.example.com you can either verify ownership of both www.example.com and sub.example.com, or of example.com.
   • If the certificate is for *.example.com you must verify ownership of example.com.

6. Upload your private key and SSL certificate, and then map your domain to your app:

   console

   1. In the Google Cloud Platform Console, go to App Engine > Settings > SSL certificates:

      Go to the SSL certificates page

   2. Click Upload a new certificate.

      
   3. Upload your concatenated SSL certificate under PEM encoded X.509 public key certificate, for example concat.crt, and then upload your RSA private key under Unencrypted PEM encoded RSA private key, for example myserver.key.pem.
   4. Click Upload. Each SSL certificate that you upload is visible and available for use by all of your other GCP projects so you don't have to upload the same certificate repeatedly.
      Note: If you upload an SSL certificate but never assign it to a domain, that certificate is automatically deleted after 30 days.
   5. Select the certificate that you want to assign to a domain and then click Save to use SSL for that domain.

   gcloud

   1. Run the following gcloud app ssl-certificates command to upload your SSL certificate and private key:

      gcloud app ssl-certificates create --display-name CERT_DISPLAY_NAME --certificate CERT_DIRECTORY_PATH --private-key KEY_DIRECTORY_PATH

      where

      • CERT_DISPLAY_NAME is the display name that you choose for the certificate.
        Example: example.com
      • CERT_DIRECTORY_PATH is the directory path and file name of the certificate.
        Example: ./cert.crt
      • KEY_DIRECTORY_PATH is the directory path and file name of the private key.
        Example: ./private.key

      Example:

      gcloud app ssl-certificates create --display-name example.com --certificate ./cert.crt --private-key ./private.key

   2. Run the following gcloud app domain-mappings command to create the mapping between your domain and your App Engine app using SSL:

      gcloud app domain-mappings create DOMAIN --certificate-id CERT_ID

      where

      • DOMAIN is the domain that you want to map to your App Engine app.
        Example: *.example.com

        Tip: Use quotes around your domain if you receive an error when using wildcard mappings: '*.example.com'

      • CERT_ID is the ID of a certificate that you want to use for SSL.
        Example: --certificate-id 1234

      Example:

      gcloud app domain-mappings create '*.example.com' 1234

   API

   To programmatically map your domain to your App Engine app and use SSL, see the app.authorizedCertificates.create and app.domainMappings.create methods in the Admin API.

7. Test your changes by visiting your domain in your browser, using https, for example, https://www.example.com.

   Note: Once the private key is uploaded, it is stored securely at Google and cannot be viewed.

Transferring mappings from a serving certificate to a new certificate

Important: The instructions that follow apply to certificates serving in SNI serving mode only.

When a certificate nears its expiration date, you'll need to upload a new certificate and transfer the old certificate's existing mappings to that new certificate. The following procedure assumes that the existing certificate has not yet expired and is currently serving your custom domain.

To transfer mappings from an actively serving certificate:

1. Get a new certificate for your domain from the certificate authority (CA) of your choice. See Obtaining a certificate for the typical steps.

2. Convert your private key and SSL certificate files into formats that are supported by App Engine. For details, see Converting your private keys and concatenating your SSL certificates.

3. Upload your RSA private key and concatenated SSL certificate:

   console

   1. Upload the SSL certificate in the SSL certificates page.

      Go to the SSL certificates page

      1. Click Upload a new certificate.

         
      2. Upload your concatenated SSL certificate under PEM encoded X.509 public key certificate, for example concat.crt, and then upload your RSA private key under Unencrypted PEM encoded RSA private key, for example myserver.key.pem.
      3. Click Upload.
   2. Select the new certificate you just added from the certificate list, then select the domain being served by the old certificate.
   3. Click Save to transfer the mappings from the old certificate to the new one.

   gcloud

   Run the following gcloud app ssl-certificates command to update your SSL certificate and private key:

   gcloud app ssl-certificates update CERT_ID --certificate CERT_DIRECTORY_PATH --private-key KEY_DIRECTORY_PATH

   where

   • CERT_ID is the ID of the SSL certificate that you want to update.
     Example: 1234
   • CERT_DIRECTORY_PATH is the directory path and file name of the SSL certificate.
     Example: ./cert.crt
   • KEY_DIRECTORY_PATH is the directory path and file name of the private key.
     Example: ./private.key

   Example:

   gcloud app ssl-certificates update 1234 --certificate ./cert.crt --private-key ./private.key

   API

   To programmatically update your SSL certificate, see the app.authorizedCertificates.patch method in the Admin API.

Obtaining a certificate

The process for getting an SSL certificate will vary depending on the certificate authority that you use. The instructions provided here might need to be adjusted slightly. Typically, each certificate authority provides instructions to assist you through the process.

To obtain a certificate for use with your App Engine app:

1. Generate your private key and a certificate signing request (CSR) by using the openssl tool:

   1. Run the following command from a directory where you want to create the server.csr file:

      openssl req -nodes -newkey rsa:2048 -keyout [MY_PRIVATE_KEY].key -out [MY_CSR].csr
      

      where:

      • [MY_PRIVATE_KEY].key is the generated file where your private key is stored. Example: myserver.key
      • [MY_CSR].csr is the generated file for your certificate signing request. Example: server.csr

   2. When prompted, enter the following information:

      • Your 2 digit country code, for example, US for United States.
      • Your city name.
      • Your company name. You can use your own name if you don't have a company.
      • Your organizational unit or NA if you don't have this.
      • A common name that represents your domain, for example: www.example.com
      • Your email address.

   You don't need to provide any of the other values, they are all optional.

2. Determine which certificate authority works for you and then purchase a certificate. For example, you can use: SSLMate, Thawte, Comodo, or any other certificate authority.

   For details about the types of supported certificates, see App Engine support for SSL certificates.

3. When your CA requests the contents of your CSR file, follow their instructions for copying and pasting contents from your .csr file that you generated earlier, for example server.csr.

4. Follow the prompts when your CA requests domain owner approval.

   Tip: You might find it easiest to use the email approval method. You will need to configure an email address in your domain account, for example [e-mail], so that you can receive and respond to the CA's approval request.

   Note: After you submit the request for your certificate, it can take a few days before you receive the actual certificate from your CA.

5. After you provide domain owner approval, the CA sends the certificate to you, which is typically in the .zip file format. Unzip that file to a working directory so that you can concatenate those certificates for upload to App Engine.

Converting private keys and concatenating SSL certificates

You must convert your private key into an RSA private key and concatenate all of your SSL certificates, before uploading your private key and SSL certificates to App Engine.

1. Convert the private key file that you generated earlier, into an unencrypted RSA private key. For example, you can run the following openssl rsa command:

   openssl rsa -in [MY_PRIVATE_KEY].key -out [MY_RSA_KEY].key.pem
   

   where:

   • [MY_PRIVATE_KEY].key is the generated file that contains your private key is stored. Example: myserver.key
   • [MY_RSA_KEY].key is the generated file that contains unencrypted RSA private key. Example: myserver.key.pem

   Example:

   openssl rsa -in myserver.key -out myserver.key.pem
   

2. Concatenate all of the .crt files from your CA into one file, using the following command:

   cat [MY_DOMAIN_CERT].crt [MY_SecureServerCA].crt [MY_TrustCA].crt [MY_TrustExternalCARoot].crt > [MY_CONCAT_CERT].crt
   

   where

   • [MY_DOMAIN_CERT].crt is the certificate for your domain. Example: www_example_com.crt
   • [MY_SecureServerCA].crt, [MY_TrustCA].crt, and [MY_TrustExternalCARoot].crt are the other certificate files that are provided by your CA.
   • [MY_CONCAT_CERT].crt is the concatenated file that contains all of your .crt certificate files from your CA. Example: concat.crt

   Example:

   cat www_example_com.crt AddTrustExternalCARoot.crt RSADomainValidationSecureServerCA.crt RSAAddTrustCA.crt > concat.crt
   

3. Verify your SSL certificate and private key:

   1. To verify that the private key and certificate match, you can use the openssl x509 and openssl rsa commands. Examples:

      openssl x509 -noout -modulus -in concat.crt | openssl md5
      openssl rsa -noout -modulus -in myserver.key.pem | openssl md5
      

      Both the openssl x509 and openssl rsa commands should return the same output.

   2. To verify that a certificate and its CA chain are valid, you can use the openssl verify command. For example:

      openssl verify -verbose -CAfile concat.crt concat.crt
      

4. When you are ready, you can upload your RSA private key and concatenated certificates to App Engine.

App Engine support for SSL certificates

App Engine supports the following certificate types:

• Single Domain/Hostname
• Self-signed
• Wildcard
• Subject Alternative Name (SAN) / Multi Domain

It requires some things of your certificates and keys:

• Private Key and Certificate should be uploaded in PEM format.
• Private Keys must not be encrypted.
• A certificate file can contain at most five certificates; this number includes chained and intermediate certificates.
• All subject names on the host certificate should match or be subdomains of the user's verified domains.
• Private keys must use RSA encryption.
• Maximum allowed key modulus: 2048 bits

If the host certificate requires an intermediate or chained certificate (as many Certificate Authorities (CAs) issue), you will need to append the intermediate or chained certificates to the end of the public certificate file.

Some App Engine features use special subdomains. For example, an application can use subdomains to address application services, or to address different versions of your application. To use these with SSL, it makes sense to set up a SAN or wildcard certificate. Wildcard certificates only support one level of subdomain.

Using Strict-Transport-Security headers

For security reasons, all applications should encourage clients to use https connections. You can use the Strict-Transport-Security header to instruct the browser to prefer https over http.

You should implement HTTP Strict Transport Security with caution: clients that have received the header in the past will refuse to connect if https becomes non-functional or is disabled for any reason. To learn more, see Cheat Sheet on HTTP Strict Transport Security.