App Engine SSL support offers globally distributed SSL endpoints andbuilt-in load balancing to serve your app securely, reliably, and quickly to aworldwide audience.

By default, HTTPS connections on your custom domain are enabledautomatically using managed SSL certificates. Aftermapping a custom domain to your application and updating yourDNS records,App Engine provisions a managed SSL certificate, renews the certificate,and revokes it when you remove the custom domain from your application.

Before you begin

• Make sure you have alreadyset up your customdomainin your App Engine project.

• If you useCloud Load Balancing andserverless NEGS toroute traffic to your App Engine app, we recommend that you map yourcustom domain to the load balancer instead of directly to your app, and useSSL certificates that are created for the load balancer. This eliminates theneed to manage separate SSL certificates for each serverless app. In addition,with Cloud Load Balancing you can set SSL policies that control the featuresof SSL that your load balancer negotiates with clients.For more information, see the following pages:

  • Using Google-managed SSL certificates
  • Using self-managed SSL certificates
  • SSL policies

  Note the following limitation:

  • We recommend that youuse ingress controlsso that your app only receives requests sent from the load balancer(and the VPC if you use it). Otherwise, users can use your app'sApp Engine URL to bypass the load balancer, Cloud Armorsecurity policies, SSL certificates, and private keys that are passed throughthe load balancer.

Verify a managed certificate

After youset up your custom domain and update the DNSrecords,a managed SSL certificate is automatically provided within a few minutes.Selection of the certificate authority is automatic; the managed certificate issigned either by Google Trust Services (GTS) orLet's Encrypt.

To verify that the certificate was provisioned:

1. In the Google Cloud console, go toApp Engine >Settings >Custom Domains:

   Go to Custom Domains

2. TheSSL security displays asGoogle-managed.

Troubleshoot managed SSL certificates

• You might need toupdate the DNS records for your custom domainto verify your domain name. App Engine cannot provision certificates forunverified domains.

• You can check the status of your certificate with the Admin API by using anAuthorizedCertificate.GET request.

• If a managed certificate has not been provisioned because the DNS recordsare not available, theManagedCertificate.ManagementStatusfield might beFAILED_RETRYING_NOT_VISIBLE. Verify that your DNS recordsare up to date, wait a few minutes, then try again. It can take up to 24 hoursfor DNS records to become available.

• If the status isFAILED_PERMANENT, then all renewal attempts have failed.Check your DNS settings then update your custom domain mapping by followingthe steps toupdate to managed SSL certificates.

Upgrade to managed SSL certificates

Before you upgrade to Google-managed SSL certificates, note that managedcertificatesdo not support wildcard mappings.

If you are using subdomains and the certificate is issued by Let's Encrypt,there is a limit of50 managed certificates per week for each base domain. If you encounter the limit, App Enginekeeps trying to issue managed certificates until all requests have beenfulfilled.

To move from your own SSL certificates to Google-managed SSL certificates, or toadd managed SSL certificates to an existing app with a custom domain, updateyour domain mapping:

1. In the Google Cloud console, go toApp Engine >Settings >Custom Domains:

   Go to Custom Domains

2. Select the domain you want to secure, and clickEnable managed security.

Disable managed SSL certificates

To disable managed SSL certificates:

1. In the Google Cloud console, go toApp Engine >Settings >Custom Domains:

   Go to Custom Domains

2. Select the domain and clickDisable managed security.

Use your own SSL certificates

Instead of using managed SSL certificates, you can use your own certificate. If yourcertificate does not have atransparency proof,your app may show SSL warnings in Chrome due to certificate transparency proofenforcement. For more information on certificate transparency proofs and how tocomply, readEnforcing Certificate Transparency.

To use and manage your own SSL certificates instead of Google-managedcertificates:

1. Make sure you have alreadyset up your customdomain in your App Engineproject.

2. Disable the default Google-managed certificates.

3. Get a certificate for your domain from the certificate authority (CA) of yourchoice. The exact procedure can vary depending on the authority but seeObtaining a certificate for the typical steps.

4. Convert your private key and SSL certificate files into formats that aresupported by App Engine. Before you can upload your files, yourprivate key must be converted to an RSA private key and your SSL certificatesmust be concatenated into a single file. For more information, seeConvert your private keys and concatenate your SSL certificates.

5. Ensure you have the right permissions in theGoogle Cloud console andverified ownership(step 3) of all related domains or their parent domains. For example:

   • If the certificate is forwww.example.com you can verify ownership ofeitherwww.example.com orexample.com.
   • If the certificate is forwww.example.com andsub.example.com you caneither verify ownership of bothwww.example.com andsub.example.com,or ofexample.com.
   • If the certificate is for*.example.com you must verify ownership ofexample.com.

6. Upload your private key and SSL certificate, and then map your domainto your app:

   1. In the Google Cloud console, go toApp Engine >Settings >SSL certificates:

      Go to SSL Certificates

   2. ClickUpload a new certificate.

   3. Upload your concatenated SSL certificate underPEM encoded X.509 public key certificate, for exampleconcat.crt, and then upload your RSA private key underUnencrypted PEM encoded RSA private key, for examplemyserver.key.pem.
   4. ClickUpload. Each SSL certificate that you upload is visible and available for use by all of your other Google Cloud projects so you don't have to upload the same certificate repeatedly.Note: If you upload an SSL certificate but never assign it to a domain, that certificate is automatically deleted after 30 days.
   5. Select the certificate that you want to assign to a domain and then clickSave to use SSL for that domain.

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

   Note: Once the private key is uploaded, it is stored securely at Google andcannot be viewed.

Transfer mappings from a serving certificate to a new certificate

When a certificate nears its expiration date, you'll need toupload a new certificate and transfer the old certificate's existing mappingsto that new certificate. The following procedure assumes that the existingcertificate 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) ofyour choice. SeeObtaining a certificate for thetypical steps.

2. Convert your private key and SSL certificate files into formats that aresupported by App Engine. For details, seeConvert your private keys and concatenate your SSL certificates.

3. Upload your RSA private key and concatenated SSL certificate:

   1. Upload the SSL certificate in theSSL certificates page.

      Go to SSL Certificates

      1. ClickUpload a new certificate.

      2. Upload your concatenated SSL certificate underPEM encoded X.509 public key certificate, for exampleconcat.crt, and then upload your RSA private key underUnencrypted PEM encoded RSA private key, for examplemyserver.key.pem.
      3. ClickUpload.
   2. Select the new certificate you just added from the certificate list, then select the domain being served by the old certificate.
   3. ClickSave to transfer the mappings from the old certificate to the new one.

Obtain a certificate

The process for getting an SSL certificate will vary depending on thecertificate authority that you use. The instructions provided here mightneed to be adjusted slightly. Typically, each certificate authority providesinstructions 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 usingtheopenssl tool:

   1. Run the following command from a directory where you want to create theserver.csr file:

      opensslreq-nodes-newkeyrsa:2048-keyout[MY_PRIVATE_KEY].key-out[MY_CSR].csr

      where:

      • [MY_PRIVATE_KEY].key is the generated file where your private keyis stored. Example:myserver.key
      • [MY_CSR].csr is the generated file for your certificate signingrequest. 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 acompany.
      • Your organizational unit orNA 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 acertificate. For example, you can use:SSLMate,Thawte,Comodo, or anyother certificate authority.

   For details about the types of supported certificates, seeApp Engine support for SSL certificates.

3. When your CA requests the contents of your CSR file, follow theirinstructions for copying and pasting contents from your.csr file thatyou generated earlier, for exampleserver.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 willneed to configure an email address in your domain account, for exampleadmin@example.com, so that you can receive and respond to the CA'sapproval request.Note: After you submit the request for your certificate, it can take a fewdays 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 a zip file. Unzip that file to a workingdirectory so that you canconcatenate thosecertificatesfor upload to App Engine.

Convert private keys and concatenate SSL certificates

You must convert your private key into an RSA private key and concatenate allof your SSL certificates, before uploading your private key and SSL certificatesto App Engine.

1. Convert the private key file that you generated earlier, into an unencryptedRSA private key. For example, you can run the followingopenssl rsa command:

   opensslrsa-in[MY_PRIVATE_KEY].key-out[MY_RSA_KEY].key.pem

   where:

   • [MY_PRIVATE_KEY].key is the generated file that contains yourprivate key is stored. Example:myserver.key

   • [MY_RSA_KEY].key is the generated file that contains unencryptedRSA private key. Example:myserver.key.pem

     Example:

     opensslrsa-inmyserver.key-outmyserver.key.pem

2. Concatenate all of the.crt files from your CA into one file, using thefollowing 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:

     catwww_example_com.crtAddTrustExternalCARoot.crtRSADomainValidationSecureServerCA.crtRSAAddTrustCA.crt >concat.crt

3. Verify your SSL certificate and private key:

   1. To verify that the private key and certificatematch,you can use theopenssl x509 andopenssl rsa commands. Examples:

      opensslx509-noout-modulus-inconcat.crt|opensslmd5opensslrsa-noout-modulus-inmyserver.key.pem|opensslmd5

      Both theopenssl x509 andopenssl rsa commands should return the same output.

   2. To verify that a certificate and its CA chain are valid, you can use theopenssl verify command. For example:

      opensslverify-verbose-CAfileconcat.crtconcat.crt

4. When you are ready, you canupload your RSA private key and concatenatedcertificates 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 includeschained and intermediate certificates.
• All subject names on the host certificate should match or be subdomains of theuser's verified domains.
• Private keys must use RSA encryption.
• Maximum allowed key modulus: 2048 bits

If the host certificate requires an intermediate or chainedcertificate, as many Certificate Authorities (CAs) issue, you mustappend the intermediate or chained certificates to the end of the publiccertificate file.

Some App Engine features usespecial 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, itmakes sense to set up a SAN or wildcard certificate. Wildcard certificates onlysupport one level of subdomain.

Remove custom SSL certificates

To stop using a custom SSL certificate, perform the following steps:

1. In the Google Cloud console, go to the App EngineSSLcertificates settings page.

   Go to SSL certificate settings

2. Click on the certificate that you want to remove from your domain.

3. Unselect the domain name that you no longer want to use the SSL certificatefor, then clickSave.

Use Strict-Transport-Security headers

For security reasons, all applications should encourage clients to usehttps connections. To instruct the browser to preferhttps overhttp,use theStrict-Transport-Security header.

View enabled TLS versions and ciphers

1. Installnmap Network Mapper on your computer if it isn't already available.Seehttps://nmap.org/ for installation instructions.

2. To see which TLS versions and ciphers are enabled for your app, enter thefollowing command:

   nmap -sV --script ssl-enum-ciphers -p 443HOSTNAME

   ReplaceHOSTNAME with the hostname for your app. Youcan use either your custom domain or theappspot.com hostname thatApp Engine created for your app. For example:

   nmap -sV --script ssl-enum-ciphers -p 443 example.uc.r.appspot.com

Disable TLS versions and ciphers

If you useCloud Load Balancing and serverless NEGSto route traffic to your App Engine app, you can disable a TLSversion or cipher by defining aSSL security policythat specifies which TLS versions and ciphers can be used for HTTPS or SSLconnections.