RUN@cloud » Application SSL

Application SSL

Last modified by Spike Washburn on 2014/01/17 00:33

Note: using an SSL entry point on your application is the way to have a fixed inbound IP address your application. Keep in mind that this will only provide a fixed IP address for clients of your web application (web browsers, other apps) but it will not give you a fixed outbound IP address for your application to access backed service. If you want a fixed outbound IP address, please use dedicated RUN@cloud servers.

The new CloudBees SSL feature allows you to setup dedicated SSL routers on your CloudBees account that can be used to route requests to your applications using your own SSL certificates.  This feature is a little complex to setup initially, but once it is setup, it is very easy to associate your applications with your SSL certificate.

Basic Steps

To create a dedicated application SSL router, you will need to use the CloudBees SDK commands listed below.  You will also need to have a your own Domain Name and SSL certificates.  

Note: SSL certificates must be obtained for your own domain. You cannot create certificates for the cloudbees.net domain. 

Here are the basic steps for setting up SSL:

  • Acquire a Domain Name that you want to associate with your app from someone an Internet domain registrar (like GoDaddy).
  • Setup a DNS server (probably via a hosted DNS provider) to let you manage your domain entries for the your domain
  • Purchase an SSL certificate from a certificate authority (ex: Verisign, RapidSSL or DigiCert). This will generate a certificate and a private key.
  • Create a CloudBees SSL router (using the bees commands documented below) by passing the SSL certificate and private key. This will create a router with an IP address for inbound requests
  • Associate your application with your new router and assign it the domain name you want to use as an alias. You do this by selecting the router from the SSL pulldown on the app config page, and by entering the hostname you want to use to access the app via SSL in the alias box.
  • Finally, use your DNS management interface (provided by your DNS server/provider) to register an A Record the maps the domain name you want to use for accessing your app to the IP address of the CloudBees router.

After your DNS is updated, and the DNS entries propagate (which can take up to 24 hours), requests issued by clients using your hostname will be directed to the IP address of the cloudbees router, which will then map incoming requests matching your aliased app hostname to the application instance.

Test the SSL certificate

Before creating a router, you can test if your certificate is valid by running the following SDK command (v1.1 or greater):

$ bees app:cert:validate -a ACCOUNT -cert SSL_CERT_FILE  -pk SSL_PRIVATE_KEY

Where:

  • SSL_CERT_FILE is a certificate such as www_cyrilleleclerc_com.chain.crt (a text file several -BEGIN CERTIFICATE-... blocks: one for your certificate and others for the Certificate Authority)
  • SSL_PRIVATE_KEY is a private such as www_cyrilleleclerc_com.pem (a text file with -BEGIN CERTIFICATE-...)

Sample:
bees app:cert:validate -a cyrille-leclerc -cert www_cyrilleleclerc_com.chain.crt -pk www_cyrilleleclerc_com.pem
Certificate and private key: OK

Create a dedicated SSL router

Create a router resource with the SDK:
$ bees app:router:create -ac ACCOUNT -cert SSL_CERT_FILE  -pk SSL_PRIVATE_KEY  ROUTER_NAME

This will launch a dedicated SSL router that can be used by applications on your account. 

Where:

  • SSL_CERT_FILE is a certificate such as www_cyrilleleclerc_com.chain.crt (a text file several -BEGIN CERTIFICATE-... blocks: one for your certificate and others for the Certificate Authority)
  • SSL_PRIVATE_KEY is a private such as www_cyrilleleclerc_com.pem (a text file with -BEGIN CERTIFICATE-...)
  • acme-ssl is the name of your created router

Sample:

$ bees app:router:create -ac cyrille-leclerc  -cert www_cyrilleleclerc_com.chain.crt  -pk www_cyrilleleclerc_com.pem www-cyrilleleclerc-com-ssl
Resource: cyrille-leclerc/www-cyrilleleclerc-com-ssl
config:
  region=us
  SSL=true
  ROUTER_SERVICE=cyrille-leclerc-2c0d8695.revproxy
  ROUTER_URL=https://23.23.186.221

To begin sending application requests to this router, you will need to configure your DNS records to point the hostname associated with the SSL certificate to your router's IP address, and then configure a hostname alias (or aliases) for your application that use this hostname. Finally, you will need to bind your application to the SSL router.

Updating a dedicated SSL router

Example: Update an existing router named acme-sll with a new certificate by running the following SDK command  (v1.1 or greater):

bees app:router:update acme-ssl -cert SSL_CERT_FILE  -pk SSL_PRIVATE_KEY
This will restart the existing dedicated SSL router with the new certificate.

Obtaining an SSL Certificate

To enable SSL for your application, you need to provide an SSL certificate.  Certificates can be obtained from numerous companies including Verisign, GoDaddy and Digicert. 

Which webserver type do I need a certificate for?

The CloudBees HTTP/HTTPS routers are based on Nginx, so if your certificate vendor offers you several webservers, choose Nginx.

If possible, go for a "wildcard" certificate

Since your router will typically need to provide SSL for apps, each with a unique hostname, you'll probably want to consider getting a Wildcard SSL certificate. Wildcard certificates provide you with a pattern of hostnames that are valid for the certificate (example: *.acme.com), so you can associate apps

Certificate chains and intermediate certs

You can only provide one certificate file when uploading. Some SSL providers provide a chain of certificates between the root certificate (their cert) and your certificate - (that you just bought) - in this case you can concatenate the certificate chain together with your certificate file (with your certificate last), as text, and upload that file. 

Note: when you concatenate certificates, the order of certificates matters and must match the order of the chain of certificates starting with your certificate. Sample : "yourhost.com.crt -> intermediate-certificate-authority.crt -> root-certificate-authority.crt".

Example: creating valid certs for GoDaddy

Godaddy does not provide an Nginx option, but you can select Apache and then convert it into a valid Nginx certificate. GoDaddy provides you with the gd_bundle.crt as well as yourhost.com.crt. To convert this into a valid NGinx certificate, you'll need to combine them by appending the gd_bundle.crt to the yourhost.com.crt.

cat yourhost.com.crt gd_bundle.crt > yourhost.com.crt

After your cert is created, you can upload it using the bees app:router:create command described above.

Obtaining a Certificate Signing Request (CSR)

If your certificate provider asks you for a CSR, you can use OpenSSL to create one.  Please see this handy form at DigiCert that helps you through this process.

Displaying the IP address of your Cloudbees SSL Router

To display the IP address of your SSL router, run the Bees SDK command "bees app:resource:list":

$ bees app:resource:list
Resources:
router cb-app:acme/acme-ssl
  config:
    region=us
    SSL=true
    ROUTER_SERVICE=acme-8f72e7e4.revproxy
    ROUTER_URL=https://50.16.192.123

Configuring a custom application domain

Step 1 - Create a DNS address name record

To use your domain with your router, you'll need to update your domain's DNS record to point to your router's IP address using an "A" record. The tools for doing this will vary based on the DNS provider you use to manage your domain, but most providers should have some kind of web interface for creating a new A record. For example, let's assume I own the domain www.example.com, and I want to use this custom domain for my application that currently uses the default domain myapp.demouser.cloudbees.net. I would need to goto my DNS provider's web interface and add a new A record for www.example.com and set its value to the router's IP address (ex: 50.16.192.123)

www.example.com = 50.16.192.123

After updating your DNS record, you will need to wait for the DNS entry to propagate, which can take up to a day, but usually not more than an hour. After your DNS record has propogated, doing an nslookup command for www.example.com should then return the router's IP address.

# nslookup www.example.com

Step 2 - Update your application configuration

Once your custom domain is setup to forward to the router's IP address, you need to reconfigure your application to use ##www.example.com## as a custom domain name, and you need to bind the new router to your app.

  1. Login to the appconsole
  2. Select your application
  3. Open the configuration tab
  4. Add your custom domain name to the domain name aliases text box
  5. Select your router in the SSL configuration (your app must be using a paid app container to see this option)
  6. Click the save button

After your application is redeployed, all requests to ##www.example.com## will be forwarded to your CloudBees application via your dedicated router.

Sample:

ssl-router-app-configuration.png

Adding domain alias with the SDK

You can add an alias to an already running application (this will not restart the application but just update the routing to that application) with the "app:proxy:update" command.

$ bees app:proxy:update -a APP_ID -al ALIAS

Note that if more than one alias needs to be defined, the aliases need to be comma delimited

Application SSL Pricing

Charges for using SSL are added to the hourly cost of your application.  Please see the CloudBees pricing page for more information.

Deleting a router

To delete a router resource, use:
usage: bees app:resource:delete [options] RESOURCE_NAME
-a,--account <arg>   Account Name
-f,--force           force delete without prompting

Example: Delete the router named acme-ssl
bees app:resource:delete acme-ssl

Forcing HTTPS / SSL on an application

You can force all requests to use HTTPS / SSL configuring the routing proxy with redirect_ssl=true:

bees app:proxy:update -a APP_ID redirect_ssl=true

All the HTTP requests will be permanently redirected to the HTTPS URL (http code 301).

To rollback 

bees app:proxy:update -a APP_ID redirect_ssl=default

Troubleshooting

The most frequent reasons for untrusted SSL certificates are

  • Invalid domain name: the "common name" of your certificate does not match the domain name of your web site
  • Missing intermediate certificate authorities: you didn't concatenate your certificate (.crt) with the intermediate certificates of your Certificate Authority

Tools to diagnose SSL certificates configuration issues

  • Symantec SSL toolbox: very intuitive and detailed tool to diagnose SSL configuration issue on any SSL certificate (not limited to Symantec / Verisign certificates)
  • SSLShopper's SSL Checker: good SSL verification tool by an SSL Certificate comparison site
Tags: ssl
Created by Spike Washburn on 2011/07/20 04:31