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.
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. It assumes that you already have an App Engine project created and deployed.
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.
Adding a custom domain for your application
To add a custom domain for your App Engine application:
Purchase a new domain, unless you already have one you want to use. You can use any domain name registrar,including Google Domains.
Create a new App Engine project in the Google Developers Console by clicking Create Project, unless you already have a App Engine project you want to use.
Add the domain to your app by clicking Add a custom domain in the custom domains console page for your project: to display the Add a new custom domain form:
In the Add new custom domain form, verify that you own the custom domain you want to use:
- Supply the domain name (e.g, "example.com") and click Verify: this opens up a new tab titled Webmaster Central:
- Follow the directions provided by the Webmaster Central tab, then click Verify.
- Return to the Add new custom domain form in the Developers Console.
Continue to the next step the Add new custom domain form, selecting the custom domain you want to point to your App Engine app:
- Refresh the console domain page so it will list the domains properly.
- If you want to use a subdomain, such as
www, use the second option (
- If you want to use a naked domain,
use the first option to specify a naked domain (such as
- Click Add to create the desired mapping.
In the final step in the Add new custom domain form, note the resource record(s) listed along with their type (CNAME in our example) and the canonical name (
ghs.googlehosted.comin our example). You'll need to add the resource record(s) listed to the DNS configuration of your custom domain:
- Log into your account at your domain registrar and open the DNS configuration page.
- 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, we would add the host name
wwwwith 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.)
- Save your changes in your domain account. It may take awhile for these changes to take effect.
Test for success by browsing to your app via its new custom domain URL:
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 module name, the application serves that version.
- If the user browses a domain that matches a module name, the application serves that module.
Note that wildcard mappings will work with App Engine modules.
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:
*maps all subdomains of
example.comto your app.
*.privatemaps all subdomains of
private.example.comto your app.
*.nichol.sharks.nhlmaps all subdomains of
nichol.sharks.nhl.example.comto your app.
*.excogitate.systemmaps all subdomains of
excogitate.system.example.comto your app.
If you use Google Apps with other subdomains on your domain, such as
Note that some DNS providers might not work with wildcard subdomain mapping. In particular, a DNS provider must permit wildcards in CNAME host entries.
Wildcards and modules/versions
The above wildcard routing rules apply to URLs that contain components for
modules, versions, and instances as well, following
the module routing rules for the App Engine
(Java | Python | Go | PHP) SDK.
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
Adding SSL to your custom domain
To enable SSL for the custom domain used with your App Engine application:
Make sure you have already set up your custom domain in your App Engine project.
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.
Open your App Engine project in the Google Developers Console.
Ensure you have the right permissions. In order to upload an SSL certificate, you must have verified ownership (step 4) of all domains that it may serve, or their parent domains. For example:
- If the certificate is for
www.example.comyou may verify ownership of either
- If the certificate is for
sub.example.comyou may either verify ownership of both
sub.example.com, or of
- If the certificate is for
*.example.comyou must verify ownership of
- If the certificate is for
Upload the SSL certificate to be used with your domain by clicking Upload a new certificate in the SSL certificates page.
- Follow the prompts to upload the public certificate and the unencrypted private key. (See the last step under Obtaining a certificate for more details on what these are and how to get them.)
- Click Upload.
Select the certificate you want to configure in the list displayed in the SSL certificates page for your App Engine project, then select the domain you are enabling for SSL and click Save.
Test your changes by visiting your custom domain in your browser, using
https, for example,
Obtaining a certificate
The process for getting an SSL certificate will vary depending on the certificate authority you use. So instructions we provide here may 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:
Generate a certificate signing request (CSR), as follows:
Invoke the oppenssl tool as follows:
openssl req -nodes -newkey rsa:2048 -keyout myserver.key -out server.csr
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.
The CA will request the contents of your CSR file: copy and paste the contents of
server.csras directed by your CA.
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 may 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
After you provide domain owner approval, the CA sends the certificate to you, typically as a
.zipfile: unzip this file.
Convert the private key you created above (
myserver.key) into the format expected by App Engine, unencrypted:
openssl rsa -in myserver.key -text > myserver.key.pem
Concatenate all of the
.crtfiles 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 Developers 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:
More about App Engine support for SSL certificates
App Engine supports the following certificate types:
- Single Domain/Hostname
- 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 modules, 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.
Purchasing a virtual IP (VIP)
VIP versus SNI
By default, App Engine SSL support uses server name indication (SNI): you don't need to set up or purchase anything to use it. Server Name Indication is a feature that extends SSL and TLS. This extension allows multiple domains to share the same IP address while still allowing separate valid certificates for all the domains. Some older browsers and operating systems don't support SNI, most notably Internet Explorer and Safari on Windows XP and the default Android browser pre-Honeycomb. When a user visits an SNI site with a client that does not support SNI they will be unable to view the page when connecting via HTTPS. We recommend detecting browsers that do not support SNI and recommending a browser that supports it.
However, if you wish, you could alternatively use a virtual IP (VIP). A VIP is a dedicated IP address assigned for your application. This allows TLS to be used without the SNI extension and as such it will work on any browser or OS that supports SSL. Each VIP only supports one certificate. The Virtual IP address may change and therefore you should not use DNS A records; instead, use a CNAME record to avoid any issues caused by Virtual IP changes.
Be aware that SNI slots are free; VIPs are not. If you need to use a virtual IP (VIP) you will need to purchase it first: these are about $39 per month per VIP.
How to purchase
To purchase a VIP:
Set up a Google Apps account for your custom domain. When you sign up for this account, you must use your custom domain email as your login, for example,
Enable billing for your application in the Google Developers Console billing page.
Set the daily budget high enough to pay for your VIPs, using the application settings page.
Register the email address you used for your Google Apps account as a project owner in the Permissions page for your App Engine project.
Log into the Google Apps admin console.
Click the Security icon.
Click Show more > SSL for App Engine Apps to display the VIP form:
Click Add a VIP once for each VIP you wish to add. You will be charged monthly for each VIP. Note that if you add a VIP and then remove it immediately, you will still be billed for an entire day.
Return to the SSL certificates page in the Google Developers Console, then click on the certificate you are using with this VIP.
In the dropdown menu under Select SSL serving mode, select SNI+VIP:
Locate the CNAME that is displayed under the cert. You'll need to log into your domain account and open the DNS configuration page, then copy this value into the CNAME records for all domains using the certificate. Allow time for the DNS changes to propagate out.
Your SSL cert will now be served as a VIP.