Using Custom Domains and SSL

App Engine allows applications to be served via a custom domain, such as example.com, instead of the default appspot.com address. You can create a domain mapping for your App Engine app so that it uses a custom domain with or without SSL.

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.

Use this page to learn how to create a domain mapping for your app that is running on App Engine and, optionally, how to set up SSL for your custom domain.

Before you begin

  • Purchase a new domain, unless you already have one that you want to use. You can use any domain name registrar, including Google Domains.

  • If you choose to use the gcloud tool commands:

    1. Install and initialize the Cloud SDK:

      Download and install

    2. Install the beta component by running:

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

Adding a custom domain for your application

To add a custom domain for your App Engine app:

  1. Verify that you are the owner of your domain through the Webmaster Central page:

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

      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 Select the domain you want to use section, enter the name of the domain that you want to use, for example example.com, and then click Verify to open a new tab to the Webmaster Central page.
      1. Use Webmaster Central to verify ownership of your domain.

        Important: Verifying domain ownership by using a CNAME record is the preferred option for App Engine. If you choose to use a TXT record, you must avoid configuring your domain's DNS with a CNAME record because the CNAME record overrides the TXT record and causes your domain to appear unverified.

        If the verification methods for your domain do not offer the CNAME record option, you can select Other as your domain provider and then choose Add a CNAME record:

        1. Click Alternate methods and then Domain name provider.
        2. In the menu, select Other.
        3. In the Having trouble section, click Add a CNAME record and then following the instructions to verify ownership of your domain.

          Remember: It might take a minute before your CNAME is set at your domain registrar.

      2. Return to the Add new custom domain form in the Cloud Platform Console.
    gcloud
    1. Run the following gcloud beta domains command to open the Webmaster Central page:

      gcloud beta domains verify DOMAIN

      where DOMAIN is the domain for which you want to verify ownership.

      Example:

      gcloud beta domains verify example.com
    2. Use Webmaster Central to verify ownership of your domain.

      Important: Verifying domain ownership by using a CNAME record is the preferred option for App Engine. If you choose to use a TXT record, you must avoid configuring your domain's DNS with a CNAME record because the CNAME record overrides the TXT record and causes your domain to appear unverified.

      If the verification methods for your domain do not offer the CNAME record option, you can select Other as your domain provider and then choose Add a CNAME record:

      1. Click Alternate methods and then Domain name provider.
      2. In the menu, select Other.
      3. In the Having trouble section, click Add a CNAME record and then following the instructions to verify ownership of your domain.

        Remember: It might take a minute before your CNAME is set at your domain registrar.

      Example
      To add the following CNAME record to your domain's DNS configuration:
      CNAME Label / Host: a1b2c3d4e5.example.com.
      CNAME Destination / Target: gv-abcdefghijk.dv.googlehosted.com
      You map the Label / Host and Destination / Target values to the corresponding fields of your domain's DNS configuration. For example, in Google Domains, you set the CNAME as follows:
      NAMETYPETTLDATA
      a1b2c3d4e5CNAME1hgv-abcdefghijk.dv.googlehosted.com.

      For more information about adding a CNAME record, including domain specific instructions, see the support page.

    HTTPS
    1. Navigate to the Webmaster Central page by opening the following address in your web browser:

      https://www.google.com/webmasters/verification/home

    2. Click Add a property and then enter the domain for which you want to verify ownership.
    3. Follow the instructions for verifying ownership.

      Important: Verifying domain ownership by using a CNAME record is the preferred option for App Engine. If you choose to use a TXT record, you must avoid configuring your domain's DNS with a CNAME record because the CNAME record overrides the TXT record and causes your domain to appear unverified.

      If the verification methods for your domain do not offer the CNAME record option, you can select Other as your domain provider and then choose Add a CNAME record:

      1. Click Alternate methods and then Domain name provider.
      2. In the menu, select Other.
      3. In the Having trouble section, click Add a CNAME record and then following the instructions to verify ownership of your domain.

        Remember: It might take a minute before your CNAME is set at your domain registrar.

      Example
      To add the following CNAME record to your domain's DNS configuration:
      CNAME Label / Host: a1b2c3d4e5.example.com.
      CNAME Destination / Target: gv-abcdefghijk.dv.googlehosted.com
      You map the Label / Host and Destination / Target values to the corresponding fields of your domain's DNS configuration. For example, in Google Domains, you set the CNAME as follows:
      NAMETYPETTLDATA
      a1b2c3d4e5CNAME1hgv-abcdefghijk.dv.googlehosted.com.

      For more information about adding a CNAME record, including domain specific instructions, see the support page.

  2. Ensure that your domain has been verified:

    console

    If your domain is not already listed, click Refresh domains.

    gcloud

    Run the following gcloud beta domains command to list your verified domains:

    gcloud beta domains list-user-verified

  3. If you need to delegate the ownership of your domain to other users or service accounts, you can add permission through the Webmaster Central page:

    1. Opening the following address in your web browser:

      https://www.google.com/webmasters/verification/home

    2. Under Properties, click the domain for which you want to add a user or service account.

    3. Scroll down to the Verified owners list, click Add an owner, and then enter a Google Account email address or service account ID.

      To view a list of your service accounts, open the Service Accounts page in the Cloud Platform Console:

      Go to Service Accounts page

  4. After you verify ownership of your domain, you can map that domain to your App Engine app:

    console

    Continue to the next step of the Add new custom domain form to select the domain that you want to map to your App Engine app:

    1. Specify the domain and subdomains that you want to map. The naked domain and www subdomain are pre-populated in the form.
      • 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.
    3. In the final step of the Add new custom domain form, note the resource records that are listed, including their type and canonical name (CNAME), because you need to add these details to the DNS configuration of your domain.

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

      Add a custom domain
    gcloud

    Run the following gcloud beta app domain-mappings command to map your domain to your App Engine app:

    gcloud beta app domain-mappings create DOMAIN

    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'

    Example:

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

    Note the resource records that are now listed, including their type and canonical name (CNAME), because you need to add these details to the DNS configuration of your domain.

  5. Add the resource records that you receive to the DNS configuration of your domain registrar:

    1. Log in to your account at your domain registrar and then open the DNS configuration page.

    2. Locate the host records section of your domain's configuration page and then add each of the resource records that you received when you mapped your domain to your App Engine app.

      Typically, you list the host name along with the canonical name as the address. For example, if you registered a Google Domain, then one of the records that you add to your DNS configuration is the www host name along with the ghs.googlehosted.com address. Alternatively, to specify a naked domain, you would instead use @ with the ghs.googlehosted.com address.

      For more information about mapping your domain, see the following Using subdomains and Wildcard mappings sections.

    3. Save your changes in the DNS configuration page of your domain's account. It can take a while for these changes to take effect.

  6. Test for success by browsing to your app via its new domain URL, for example 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 your services in App Engine.

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 G Suite 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 domain that you mapped to your App Engine app:

  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 (CA) of your choice. The exact procedure can vary depending on the authority but see Obtaining a certificate for the typical steps.

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

  4. 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 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.
  5. 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.

      Upload a cert
    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 Cloud Platform projects so you don't have to upload the same certificate repeatedly.
    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 beta app ssl-certificates command to upload your SSL certificate and private key:
      gcloud beta 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 beta app ssl-certificates create --display-name example.com --certificate ./cert.crt --private-key ./private.key
    2. Run the following gcloud beta app domain-mappings command to create the mapping between your domain and your App Engine app using SSL:
      gcloud beta 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 beta app domain-mappings create '*.example.com' 1234

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

Transferring mappings from a serving certificate to a new certificate

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.

        Upload a cert
      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 beta app ssl-certificates command to update your SSL certificate and private key:

    gcloud beta 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 beta app ssl-certificates update 1234 --certificate ./cert.crt --private-key ./private.key

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 admin@example.com, 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

Before you upload your private key and SSL certificates to App Engine, you must convert your private key into an RSA private key and then concatenate all of your SSL certificates.

  1. Convert the private key file that you generated earlier, into an unencrypted RSA private key, that is supported by App Engine. 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.

Send feedback about...

App Engine flexible environment for Python docs