SSL Certificates and Bluemix Custom Domains

5 min read

SSL Certificates and Bluemix Custom Domains

Are you a Bluemix app developer using a custom domain? Do you want to be able to prove your identity to visitors accessing your app via SSL? If so, you’ll want to keep reading to learn all about the new SSL certificate feature added to the Bluemix UI as part of last month’s refresh. With these important updates, you can now upload your own certificates for use with your custom domains.


NOTE: There is a limit of one upload per organization for trial users and four uploads per organization for pay-as-you-go and subscription users (updated Dec. 7, 2014).

Why You Need Your Own SSL Certificates

More Info?

If you’d like more information about default SSL coverage, see my separate post, Redirecting HTTP to HTTPS with Node.js on IBM Bluemix. There I provide links to live Bluemix apps which allow you to see the results of different configurations in the browser.

Colleague Jeff Sloyer points out in his recent blog post, Inbound SSL in Bluemix, that an app using the default domain (which is gets SSL support automatically. This means without taking any other action, the app is accessible via https. In addition, traffic is secured with a fully trusted certificate provided by IBM (and issued by DigiCert).

Of course, this is pretty cool. However, it’s important to understand that this default support is inadequate when you introduce custom domains. If your app’s route uses a custom domain, you still technically get https for free. But, the browser will show an ugly domain mismatch error after inspecting the certificate. Understandably, errors like these scare away users.

Uploading SSL Certificates

With the new SSL certificate functionality in the Bluemix UI, you can solve these problems by using your own certificates with custom domains. There are several tasks you need to perform in order to get a working end-to-end solution. The remainder of this section will cover those tasks at a high-level. For a lower-level, step-by-step tutorial, see my separate post Bluemix UI: SSL Certificates and Custom Domains.


Before getting started with the Bluemix part of the setup, you should perform a couple prerequisites:

  1. Have (or acquire) ownership of a registered Internet domain name.

  2. Obtain (or create) an SSL certificate, private key, and (optionally) an intermediate certificate.

    • Certificate

      • Digital document that binds a public key to the identity of the certificate owner, thereby enabling the certificate owner to be authenticated.

      • Generally issued and signed by a certificate authority. However, for testing and development purposes you may use a self-signed certificate.

      • File types supported:

        • PEM (.pem.crt.cer, and .cert)

        • DER (.der or .cer)

        • PKCS #7 (.p7b.p7r.spc)

    • Private key

      • Algorithmic pattern used to encrypt messages that only the corresponding public key can decrypt. The private key is also used to decrypt messages that were encrypted by the corresponding public key.

      • File types supported:

        • PEM (.pem,.key)

        • PKCS #8 (.p8.pk8)

    • Intermediate certificate

      • You should use an intermediate certificate to verify the authenticity of the main certificate. Intermediate certificates are typically obtained from a trusted third-party. You might not require an intermediate certificate if using a self-signed certificate for testing prior to deploying your application to production.

See the Securing Apps article in the Bluemix Documentation for the most current information on supported certificate types.

Bluemix Setup

Once you’ve done the prep work, you will need to:

  1. Add a custom domain to your Bluemix organization.

  2. Setup a route for a Bluemix app that uses the custom domain.

  3. Configure your DNS so traffic is routed to your app.

    • NOTE: Specifically, you need to add a CNAME record that maps your domain to the hostname of the Bluemix router. The hostname will vary based on the region your app is deployed to US South (, London (, or Sydney (

  4. Upload an SSL certificate for your custom domain.

    • Once you have a custom domain defined on the Manage Domains panel, notice there is a new SSL Certificate column with a button that allows you to upload a certificate for the domain:
      SSL certificate
    • Click the button and the Upload Certificate dialog will be displayed. For each requested file type, click the Browse button and navigate to the file on your local system.
      Upload Certificate dialog
    • Click the Upload button and the upload process will begin. If the upload completes successfully, the dialog will go away and you will see the icon in the SSL Certificate column is now a green ribbon.
      Click the Upload button

Conclusion (and a Note on Redirecting to HTTPs)

At this point, you should be able to access your app using https (assuming your DNS was configured correctly). And, if you look at the certificate details in the browser, you should see your certificate instead of the default certificate for

However, if you’ve done nothing to prevent it, your app is probably also accessible via the non-secure httpprotocol. In his post, Sloyer presents some sample code for Node.js to ensure http traffic is redirected to https. As an alternative, I’ve also developed a slightly simpler approach for Node.js apps (which use Express), and I’ve made the code available on Github.

Be the first to hear about news, product updates, and innovation from IBM Cloud