Adding SSL

Last Updated October 2014

Pagoda Box makes the process of adding a Secure Socket Layer (SSL) to your site easy. Encrypting data is necessary for protecting information, but the process of adding SSL encryption can sometimes be a pain. This doc walks through the simple steps of adding SSL certificates to your Pagoda Box app. After reading it, you will understand how to:

  • Enable SSL for your app

Before You Get Started

Before you get started, there’s a few things to know. Nothing major, just things to keep in mind.

Pagoda Box is Not an SSL Provider

Pagoda Box does not sell SSL certificates. We provide a simple way to install and use SSL certificates purchased from 3rd party providers. Below are examples of SSL providers.

This list is by no means exhaustive and we make no official recommendations. Your choice of SSL providers is completely up to you.

Verisign
Digicert
Thawte

Only Necessary When Using a Custom Domain

Adding SSL is only necessary when you need to use https on your own custom domain. If you’re using your gopagoda.io dev URL, you can use the free Piggy Back SSL.

Free Piggy Back SSL

Pagoda Box's Piggy Back SSL allows you to use Pagoda Box's SSL as your own. It's ideal for development environments that need data encryption. Every app automatically has access to the Piggy Back SSL for free. No setup required. All you need to do is use the https protocol instead of http. Piggy Back SSL is only available for Pagoda Box subdomains: (https://your-app.gopagoda.io), not custom domains.

Note: The piggy back SSL is a Self-Signed certificate. The first time you visit your app using https, your browser will likely throw an error giving you the option to trust the certificate. You will have to trust the certificate in order to view your site using https.

Adding an SSL Certificate

To add an SSL certificate, in your App Dashboard, go to Network > SSL certificates and click “Add an SSL Certificate”.

Add SSL

Provide the Required Information

Fill out the necessary information to generate your SSL certificate. The domain must match the domain you’re trying to secure exactly. More information about using Wildcard Certificates is provided below. All the information is required to properly create your SSL certificate. It is included in your certificate and viewable to anyone who inspects its authoritative chain. It is important that the provided information is accurate.

SSL Information

Wildcard SSL Certificates

Wildcard SSL Certificates are simple to use on Pagoda Box. When providing the domain in the SSL creation process, include an asterisk in place of the subdomain in the domain you provide (*.myapp.com). This will allow you to use the SSL certificate on any sub domain of your top level domain.

Submit Your CSR to Your SSL Provider

After inputting the certificate information, click “Save & Continue”. Once submitted, we automatically generate a Certificate Signing Request (CSR). Copy and submit your CSR to your 3rd Party SSL provider.

SSL Certificate Signing Request

Paste Your Certificate & Certificate Authority

After submitting the Certificate Request, your SSL provider will give you a Signed Certificate, a Certificate Authority, and possibly an Intermediate Certificate. More information on how to identify which is which below. Once you receive these, click "Save & Continue" to move onto the next step.

Paste the Certificate and the Certificate Authority into the corresponding fields. If an Intermediate Certificate is provided, past it in the Certificate Authority field along with the Certificate Authority. Click “Finish & Create” and your SSL will be added to your app's list of available certificates.

Before you’ll be able to use the certificate, you’ll need to bind it to a dedicated inbound IP.

Transferring an SSL Cert from Another Host

If transferring a certificate that is currently in use on another host, you will have to go through the same process of creating a new certificate, during which we generate a private key and an associated CSR. For security reasons, Pagoda Box will never require or accept private keys generated outside of our system. You must rekey your existing certificate using the CSR provided by Pagoda Box.

Uptime While Transferring Certificates

Depending on how your SSL provider manages the rekeying of certificates, this process may affect the SSL functionality of the site where the certificate is currently in use.

Bind Your SSL to a Dedicated Inbound IP

In order to use your SSL certificate on Pagoda Box, you must first bind it to a dedicated inbound IP. If you haven’t already added one, the Inbound IPs doc walks through how.

With a dedicated inbound IP in place, on the right of your installed SSL certificate, you will see a dropdown of available IPs to which the certificate can be bound. Select the IP to which you’d like to bind your SSL and click “Save”.

SSL Dropdown

Test Your SSL Before You Change Your DNS

It is possible (and recommended) to test your SSL certificate before you point your A-Record to your IP. To do this, add a host entry to your local hosts file pointing your custom domain to the IP to which your SSL certificate is bound. Below is an example for Mac OSX. The location of your hosts file depends on your operating system.

Modifying Your Local Hosts File

  127.0.0.1       localhost
  123.45.67.89    yourdomain.com
/private/etc/hosts

Note that this change will only affect requests from your machine. After you are finished testing, it's recommended that you remove the host entry from your hosts file.

Point Your A-Record to Your Unique IP

Once your certificate is bound to an IP, point your DNS A-Record to that IP to begin using the certificate on your app. Once the DNS change propagates, you'll be able to use the https protocol to encrypt data through on your custom domain.

Turn Your TTL Down

Turning your DNS Time to Live (TTL) down 48-72 hours before adding SSL will prevent any downtime caused by DNS propagation. Once the transition is made, turn your TTL back up, and you should be good to go.

Managing an SSL Certificate

Once and SSL certificate is installed, there are some simple management options available. To see these options, click on the gear icon next to your certificate.

SSL Edit Options

Edit / View Details

This allows you to view and, if necessary, edit your SSL’s Certificate and Certificate Authority.

Pagoda Box Will Never Display or Provide Private Keys

For security and liability reasons, Pagoda Box will never provide or display private keys associated with SSL certificates. If a key is required to transfer a certificate to another host, you must have a new key generated and rekey the certificate.

Renew / Rekey

This process allows you to renew or rekey and existing certificate. We will generate a new CSR for you to submit to your SSL provider. They will give you a new Certificate and Certificate authority. Your currently running SSL certificate will not be affected until the renewal/rekeying process is complete.

Delete

This is self-explanatory. This will delete your SSL certificate. This action cannot be undone without going through the SSL creation process again. Once you delete the certificate, requests routed to your custom IP to which the SSL was bound will no longer be able to use the https protocol.

Identifying Certificates, Certificate Authorities, & Intermediate Certificates

While Certificates, Certificate Authorities, and Intermediate Certificates are standardized, their naming is not. Every SSL provider has their own name for each and it can be hard to know which is which. Below are just some tips that may help to identify what is what.

Certificates

Certificates contain a single body of text beginning with “BEGIN CERTIFICATE” and ending with “END CERTIFICATE”. Below is a generic example showing the pattern:

Certificate Pattern

  -----BEGIN CERTIFICATE-----
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    -----END CERTIFICATE-----

Another give away for certificates is in the naming of the file your SSL provider gives you. If the file name contains your domain in some form, it is likely your certificate. For example, yourdomain-com.crt would be your certificate.

Be sure to include all contents of this file, including the BEGIN CERT… and END CERT… tags when pasting into the “Certificate” field in the SSL creation process. These are part of your certificate.

Certificate Authorities

Certificate Authorities (CA) typically contain two or more bodies of text beginning with “BEGIN CERTIFICATE” and ending with “END CERTIFICATE”. Below is a generic example showing the pattern:

Certificate Authority Pattern

  -----BEGIN CERTIFICATE-----
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  -----END CERTIFICATE-----
  -----BEGIN CERTIFICATE-----
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  -----END CERTIFICATE-----

Note that CAs do not always contain two bodies of text. In some cases they will only contain one. In these cases, it’s likely that a separate file was provided containing the intermediate certificate.

You can typically identify CAs by the filenames as well. Filenames usually contain the name of the SSL provider and/or terms like “root,” “ca,” or “bundle.”

Be sure to paste the full contents of the Certificate Authority in the “Certificate Authority” field in the SSL creation process.

Intermediate Certificates

Intermediate Certificates are not required and are not always provided. They can also be a little harder to identify. Typically, they are identified through a process of elimination. If it’s not the Certificate or the CA, it’s likely the Intermediate Certificate.

They will contain one or more bodies of text beginning with “BEGIN CERTIFICATE” and ending with “END CERTIFICATE”.

There are also give-aways in file naming, but they aren’t as reliable. Many SSL providers use the same conventions in naming CAs and Intermediate Certificates. But some things to look for are “external,” “add trust,” or “chain.”

The full contents of the Intermediate Certificate should be pasted into the “Certificate Authority” field during the SSL creation process along with the full contents of the CA.

A General Rule of Thumb

As a general rule of thumb, once you've identified which file is your certificate, it's safe to assume all other files provided by your SSL provider are required to complete your certificate's authoritative chain. Everything but your certificate should be pasted into the "Certificate Authority" field.

The one caveat to this is any txt files provided by your SSL provider. Only a few SSL providers include these with your certificate and CA, but if they do, they are not part of your CA and should not be pasted into the CA field.

SSL Troubleshooting

HTTPS Goes to *.gopagoda.io

If after installing your SSL and navigating to your custom domain using the https protocol, you see an error something to the effect of "You attempted to reach yourdomain.com, but instead you actually reached a server identifying itself as *.gopagoda.io," there's a number of possible causes:

  1. Your A-Record Isn't Pointed to the Correct IP

    In order to use SSL, you must bind your SSL cert to one or more of your dedicated inbound IPs. Once bound, you can then point your DNS A-Record to those IPs and your app will be able to use https once the change has propagated. The last step of pointing your A-Record to the new IP(s) is the most commonly missed.

    In may cases, users get their app up and running before adding a dedicated inbound IP or adding SSL. In this case, the DNS Alias would've been pointed to one of the Pagoda Box public IPs. To use SSL on a custom domain, you must first add a dedicated inbound IP, bind your SSL certificate to one or more of your dedicated inbound IPs, then point your DNS A-record to your dedicated IP(s).

  2. You've Modified Your A-Record but the Changes Haven't Fully Propagated

    If you've modified your A-Record to point to the correct IP and you're still getting this error, it means the DNS change hasn't fully propagated. The time it takes to fully propagate a DNS change can be drastically reduced by reducing your domains TTL before making the change. There's not a whole lot you can do at this point other than wait.

    If you want to test the SSL while waiting for the changes to propagate, you can modify your hosts file to point your custom domain directly to your custom IP.

Certificate Works in Some Browsers but Not Others

This issue is typically associated with Comodo certificates and means that the Intermediate Certificate was not installed correctly. In order for Comodo certificates to work in all browsers, they must be installed with an Intermediate Certificate.

To fix it, edit your SSL and copy the full contents of the Intermediate Certificate provided by your SSL provider into the “Certificate Authority” field along with the full contents of the Certificate Authority and save.

Redirect to https

Once SSL up and running, it's very likely you'll want to direct all visitors to the https/secure version of your domain. Because apps on Pagoda Box sit behind a load-balancing routing mesh, https redirects must be handled a little differently. You'll need to use the X-Forwarded-Proto header. Below is an example using an Apache .htaccess rewrite:

.htaccess Rewrite to https Apache

  RewriteEngine On
  RewriteCond %{HTTP:X-Forwarded-Proto} =http
  RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
.htaccess

If you have any questions, suggestions, or corrections, let us know.