Using Custom Domains and SSL

App Engine allows applications to be served via a custom domain, such as example.com, instead of an appspot.com address. You can use a custom domain with or without SSL.

SSL support for your App Engine application 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.

This page describes how to use a custom domain with an App Engine app and, optionally, how to set up SSL for the custom domain.

Support for Virtual IPs (VIPs) is deprecated as of May 31, 2016. While Google will support applications using the VIP service in the App Engine production environment per our terms of service, you can no longer purchase new VIPs, and eventually all VIPs will be migrated to the server name indication (SNI) protocol. For more information, see Virtual IP (VIP) Transition to Server Name Indication (SNI).

Before you begin

• Purchase a new domain, unless you already have one you want to use. You can use any domain name registrar, including Google Domains.
• Create and deploy an App Engine project. If you want to use the project from the Quickstart, make sure you keep your project instead of deleting it.

Adding a custom domain for your application

To add a custom domain for your App Engine application:

1. In the Google Cloud Platform Console, go to Custom Domains page.

   Go to the custom domains page

2. Click Add a custom domain to display the Add a new custom domain form:

   

3. In the Add new custom domain form, verify that you own the custom domain you want to use:

   1. Supply the domain name ("example.com") and click Verify. This opens up a new tab titled Webmaster Central.
   2. Follow the directions provided by the Webmaster Central tab, then click Verify.
   3. Return to the Add new custom domain form in the Cloud Platform Console.
   4. If the domain still isn't verified, click Refresh domains.

4. Continue to the next step of the Add new custom domain form and select the custom domain you want to point to your App Engine app:

   1. Specify the domain and subdomains you want to map.

      • A naked domain, such as example.com, maps to http://example.com.
      • A subdomain, such as www, maps to http://www.example.com.

   2. Click Submit mappings to create the desired mapping.

5. In the final step of the Add new custom domain form, note the resource records listed along with their type and canonical name.

   In the example below, CNAME is one of the types listed, and ghs.googlehosted.com is its canonical name.

   

6. Add the resource records listed to the DNS configuration of your custom domain:

   1. Log in to your account at your domain registrar and open the DNS configuration page.
   2. In the host records section, add each of the records listed in the Add new custom domain form. Typically you list the host name along with the canonical name as the address. In our example, one of the records you would add is the host name www with the address ghs.googlehosted.com. (If you use a naked domain, you would use @ as the host name and a corresponding value from the Add new custom domain form.)
   3. Save your changes in your domain account. It can take awhile for these changes to take effect.

7. Test for success by browsing to your app via its new custom domain URL: www.example.com.

Using subdomains

If you set up a wildcard subdomain mapping for your custom domain, then your application serves requests for any subdomain that matches.

• If the user browses a domain that matches an application version name or service name, the application serves that version.
• If the user browses a domain that matches a service name, the application serves that service.

Wildcard mappings

Note that wildcard mappings will work with App Engine services.

You can use wildcards to map subdomains at any level, starting at third-level subdomains. For example, if your domain is example.com and you enter text in the web address field:

• Entering * maps all subdomains of example.com to your app.
• Entering *.private maps all subdomains of private.example.com to your app.
• Entering *.nichol.sharks.nhl maps all subdomains of nichol.sharks.nhl.example.com to your app.
• Entering *.excogitate.system maps all subdomains of excogitate.system.example.com to your app.

If you use Google Apps with other subdomains on your domain, such as sites and mail, those mappings have higher priority and are matched first, before any wildcard mapping takes place. In addition, if you have other App Engine apps mapped to other subdomains, those mappings also have higher priority than any wildcard mapping.

Note that some DNS providers might not work with wildcard subdomain mapping. In particular, a DNS provider must permit wildcards in CNAME host entries.

The above wildcard routing rules also apply to URLs that contain components for services, versions, and instances, following the service routing rules for the App Engine.

Using Strict-Transport-Security headers in a custom domain

You cannot use Strict-Transport-Security headers unless your domain is whitelisted. To place your domain in the whitelist, contact [email protected].

Adding SSL to your custom domain

To enable SSL for the custom domain used with your App Engine application:

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

2. Get a certificate for your domain from the certificate authority of your choice. The exact procedure can vary depending on the authority: see Obtaining a certificate for details.

3. Ensure you have the right permissions in the Cloud Platform Console. In order to upload an SSL certificate, you must have verified ownership (step 3) of all domains that it may serve, 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.

4. Upload the SSL certificate to be used with your domain in the SSL certificates page.
   Go to the SSL certificates page
   

   1. Click Upload a new certificate.

      

   2. Follow the prompts to upload the public certificate and the unencrypted private key. (For more details on what these are and how to get them, see the last step under Obtaining a certificate.)

   3. Click Upload. After you upload an SSL certificate, it is visible to and usable by all of your projects in the Google Cloud Platform Console: you don't have to upload the same certificate for each project.

5. Select the certificate you want to configure from the list, select the domain you are enabling for SSL, and then click Save.

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

Transfering mappings from a serving certificate to a new certificate

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

To transfer mappings from an actively serving certificate:

1. Get a certificate for your domain from the certificate authority of your choice. The exact procedure can vary depending on the authority: see Obtaining a certificate for details.

2. Upload the SSL certificate in the SSL certificates page.
   Go to the SSL certificates page
   

   1. Click Upload a new certificate.

      

   2. Follow the prompts to upload the public certificate and the unencrypted private key. (For more details on what these are and how to get them, see the last step under Obtaining a certificate.)

   3. Click Upload.

3. Select the new certificate you just added from the certificate list, then select the domain being served by the old certificate.

4. Click Save to transfer the mappings from the old certificate to the new one.

Obtaining a certificate

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

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

1. Generate a certificate signing request (CSR):

   1. Invoke the openssl tool:

      openssl req -nodes -newkey rsa:2048 -keyout myserver.key -out server.csr
      

   2. When prompted, supply:

      • your 2 digit country code (e.g., US for United States),
      • your city name
      • your company name (or your own name if you don't have a company)
      • your organizational unit or NA if you don't have this
      • your domain name: www.example.com
      • your email address

   You don't need to supply the other, optional values. The resulting CSR file is server.csr, which you'll use in a moment.

2. Locate the certificate authority (CA) that you want to use, such as Let's Encrypt, SSLMate, Thawte, Comodo, or other certificate authority, and purchase a certificate.

3. The CA will request the contents of your CSR file: copy and paste the contents of server.csr as directed by your CA.

4. The CA will request domain owner approval: follow the prompts to do this. You might find it easiest to use the email approval method, in which case you might need to set up an expected email address at your domain account so you can receive the approval request email from the CA and follow the instructions provided in that email. A typical expected address is [email protected].

5. After you provide domain owner approval, the CA sends the certificate to you, typically as a .zip file: unzip this file.

6. Convert the private key you created above (myserver.key) into the format expected by App Engine, unencrypted:

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

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

   cat www_example_com.crt ASecureServerCA.crt ATrustCA.crt ATrustExternal.crt > concat.crt
   

   When you upload the private key and the concatenated certs using the Google Cloud Platform Console SSL page within the App Engine settings for your project, in the file selector for private key, supply the private key file you just converted into a pem file: myserver.key.pem. And in the file selector for PEM encoded X.509 public key certificate, supply the concatenated file containing all the certificates from your CA: concat.crt

To verify that the private key and certificate match, use the following commands:

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

Both commands should return the same output.

To verify that a certificate and its CA chain is valid, the openssl verify command can be useful:

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

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.