SSL for a Custom Domain

App Engine allows applications to be served via a custom domain, such as example.com, instead of an appspot.com address. If you're not going to use HTTPS, a simple setup procedure for this is described under Using a Custom Domain. However, if you want to provide an HTTPS address (i.e., use SSL security) with your custom domain, the setup is a bit more involved, and you'll need to use the information and instructions on this page instead.

SSL support for your App Engine application is provided through Google Apps, a configurable Google service that delivers a customized suite of applications over the Web. The SSL support in Google Apps 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.

To use SSL, you'll create a Google Apps account using your custom domain, add your App Engine app as one of the apps to serve, assign a subdomain (such as "www."), and enable SSL security for the app. (If you prefer to use a "naked" domain, Google Apps allows you to automatically redirect it to a subdomain.) Most of this setup is handled through the Google Apps admin console. The process requires:

• an App Engine application
• a Google Apps account (which uses a login ID that's listed as an owner of the App Engine project)
• a domain (acquired through a domain registrar and configured at their site)
• an SSL certificate (acquired through a certificate authority and uploaded to Google Apps)

This page provides an overview, the initial instructions, and other important information you'll need during the setup. Then it links you to the final instructions, on the page Activate SSL for custom domains.

About using App Engine with Google Apps

Serving your App Engine app through Google Apps provides slightly different features than serving it directly through App Engine. Here are three key differences:

• Google Apps does not support "secondary" domains for your App Engine app, as explained here. You can still use secondary domains with other apps you offer through Google Apps, but your App Engine app can only be accessed with your account's primary domain or its aliases.

• "Naked" domains (that is, domain names without a subdomain, such as http://example.com) are also not supported in Google Apps. However, you can configure the naked domain to be automatically redirected to a subdomain, such as http://www.example.com or http://myapp.example.com.

• The authentication method you use in App Engine must be compatible with your custom domain. Specifically, the authentication type must be set either to Google Accounts API or to the domain you're using. To adjust the authentication method in the Developers Console, select your application, then App Engine > Settings > Google Authentication.)

Suspended Google Apps accounts

If your 30-day free trial of Google Apps ends before you've signed up for billing, your account is suspended. However, at that time you can still log in as account administrator. This allows you to enable billing to continue service, if you choose, or delete the account to release your custom domain for other uses.

Setup instructions

There are multiple ways to perform this setup. Below is a typical workflow that should work well for most users, along with some tips and suggestions.

1. Create an App Engine project, if you haven't already done so, by starting here.

2. Purchase a domain. You can use a domain you already own, purchase one in advance from a domain registrar, or purchase one through Google during the setup process for the Google Apps account (the next step below).

3. Set up a Google Apps account. While signing up for a Google Apps account, you must specify a domain. You should use your intended custom domain, rather than some other domain that you control. You'll be prompted to specify an email address at that domain, to use as your Google Apps login. To keep your workflow simple, register this email address as a project owner in the Permissions page for the App Engine project. You will also be required to make a few edits to the DNS records at the registrar site. For this purpose, if you purchased your domain through Google Apps, you'll find the login credentials for editing your domain records under the Google Apps menu by clicking More controls (at the bottom of the page), then Domains > Advanced DNS settings.

4. After you've looked over the rest of the information on this page, continue by following the instructions on the Google Apps help page Activate SSL for custom domains. That will guide you through the final four steps, which are:

   • Add the App Engine application as a service of the Google Apps account.
   • Add a subdomain URL in Google Apps for your App Engine application.
   • Enable SSL for the application.
   • Configure an SSL certificate. You'll need an SSL certificate from a certificate authority that meets our certificate requirements below.

Choosing an SSL type

App Engine supports two types of SSL for custom domains. You can configure your domain to use either or both.

Server Name Indication (SNI)

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.

Virtual IP (VIP)

A dedicated IP address is 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 DNS A records should not be used. Use a CNAME record to avoid any issues caused by Virtual IP changes.

Certificate requirements

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 domains associated with the account in the Google Apps Control Panel.
• 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.

Changing the number of SNI certificate slots

SNI certificate slots can be increased and decreased on the Google Apps SSL Billing Status page. Click the Increase SNI Certificate Slots button to buy five slots for serving additional certificates via SNI. If your application has five unused slots available, there is also a Decrease SNI Certificate Slots button. To change the serving status of a certificate, please see the Uploading and Configuring Certificates section.

Adding and removing VIPs

Virtual IP addresses (VIPs) are allocated and removed individually on the Google Apps SSL Billing Status page. To add a VIP, click the Add a VIP button. The option to delete a VIP is only available if a VIP is not serving a certificate. To unassign certificates from a VIP, please see the Uploading and Configuring Certificates section.

If you add a VIP and then remove it immediately, you will still be billed for an entire day.

Uploading and configuring certificates

The help pages for Google Apps provide detailed instructions for uploading certificates.

In general, certificates are uploaded and managed at the Google Apps Control Panel. The menu option for this, SSL for Custom Domains, is only visible within the Security menu if you have already added your App Engine app to the Google Apps account. To reach the Google Apps Control Panel, sign in at https://www.google.com/a/<yourdomain> (e.g., https://www.google.com/a/example.com).

Replacing a certificate

You can replace one certificate with another. App Engine only allows this if it can assign all of the current certificate's URLs to the new certificate and the new certificate is in "Not serving" mode.

Replacing a certificate moves all URLs from the current certificate to the new one. If the current certificate uses VIP, it will be moved to the other certificate. The new certificate's serving mode will be set to the current certificate's serving mode. The current certificate's serving mode will be reset to "Not serving".

• Upload the new certificate.
• For the certificate you wish to replace, choose the new certificate from its "Replace with" list and click the Select button.
• Click the Save button at the bottom of the page to save your changes.

Changing the billed application

You can change the application to which SSL charges are billed. This is done in the Google Apps console, under Security > Show more > SSL for Custom Domains > Billing Status.

To change the billed application:

• Click on the Change link next to the current billed application ID.
• Enter the Application ID of the application you wish to have SSL related charges billed through and click Change. All SSL charges from this Google Apps account will be added to the given application's bill.
• You will be redirected to the Admin Console of the application named in the previous step. (You may need to log in to the App Engine application if you use an account that's not an owner of the Google Apps account.)
• Confirm that you wish to bill all SSL-related charges to this application.
• You will be redirected back to the SSL tab in the Google Apps Control Panel.

Disabling SSL

Removing a certificate

Before removing the certificate, change your DNS configuration. The CNAME records for the certificate's URLs should be ghs.googlehosted.com. (Work with your domain provider to change your DNS configuration.) Because DNS servers cache records, you probably want to change this at least 24 hours before removing the certificate.

You can manage certificates in the SSL section of the Domain Settings tab of the Google Apps control panel. To reach this section:

• Sign in to the Google Apps Control Panel for your domain (e.g., http://www.google.com/a/example.com).
• If you're not already on the Configure SSL page, press the Configure SSL Certificates button.

In the SSL section of the Domain Settings tab of the Google Apps control panel, you can remove certificates:

• Click Delete Certificate on the certificate you wish to remove
• Click Save at the bottom of the page

Disabling SSL billing

The help pages for Google Apps provide detailed instructions for disabling SSL billing.

Quotas and limits

The following limits apply specifically to the use of SSL for custom domains: