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:

    Add a custom domain

  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.

    Add a custom domain

  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 appengine-security-headers@google.com.

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.

      Upload a cert

    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.

      Upload a cert

    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 appr