Domain Management and Custom SSL Certificates

All OpenShift Online plans allow you to create and use a custom subdomain, along with the ability to use your own custom domain name. All applications can also utilize a shared SSL certificate. Premium plans allow the creation and management of more than one domain and the ability to use a custom SSL certificate.

In This Guide

Creating Additional Domains

Premium plan users can create a new domain in either the web console or by using the command line (rhc).

If you are using the command line with multiple domains to create and manage applications, you will need to use the -n <domain> flag for most commands to identify the domain you are referencing.

Web Console

If you have already created an application on OpenShift Online, you will see a list of your existing applications. If you are a premium plan user, click on the Create link in the applications list as highlighted in the screenshot below. You can also create and manage domains from the Settings tab in the top navigation:

Creating a new domain part 1

Next, provide your desired domain name:

Creating a new domain part 2

The additional domain is then ready to use. On the Applications screen, you can see an empty domain has been created:

Creating a new domain part 3

You can now select the new domain when creating additional applications:

Creating a new domain part 4

Command Line (rhc)

$ rhc domain create <domain_name>
If you are using the command line with multiple domains to create and manage applications, you will need to use the -n <domain> flag for most commands to identify the domain you are referencing.

Using a Custom Domain

The web console allows you to configure your application’s hostname, and set up secure access to custom domains through the SSL certificate configuration area. Once you have your own domain name and at least one application, you can start the configuration process.

Step 1: Configure a Domain Alias in the OpenShift Web Console or Command Line (rhc)

First, open your OpenShift web console, and select the app that you would like to modify. On the application’s settings page, there is a Change link next to your initial OpenShift-provided hostname:

Adding a domain alias

Clicking this link will open up the new hostname configuration page:

Adding a domain alias part 2

Here you can enter a valid domain name that you would like to associate with your application. The above example uses

Configuring your application to be available on a subdomain is generally easier.

Click Save, at the bottom of the page when you’re ready to save your settings.

You should see a notification message if the host alias was configured successfully:

Adding a domain alias success
Command Line (rhc)

You can add a custom domain name to an existing application with the following command, specifying the application name and custom domain name:

$ rhc alias add <application name> <custom domain name>

Additional host aliases can be added as needed.

Step 2: Configure your DNS Host Records

OpenShift takes advantage of CNAME records to route requests to your application instance.

CNAME records are nice because they can defer to OpenShift’s DNS system for IP address resolution (which isn’t guaranteed to be static in OpenShift Online). However, CNAME records can also come with a few hidden limitations:

  1. Not all Domain registrars allow you to set your base host name as a CNAME ( is allowed, while may not be).

  2. If your registrar does allow you to configure a root-level CNAME record, then all additional Host records will like be limited to the CNAME record type as well. This means that you would not be able to configure MX records on any host that uses a CNAME for it’s root host record ("@").

The simplest solution is to make your app available on a subdomain, as in the above example ( This configuration is supported by all domain registrars, and it doesn’t limit your ability to set up an external mail provider.

Here is a screenshot of the subdomain being tied to the Red Hat-hosted

Configuring DNS
When in doubt, check your domain registrar’s support documents for DNS Host record configuration assistance.

Shortly after adding the CNAME record, you will be able to connect to your application via the new hostname URL.

Using a Custom SSL Certificate

OpenShift includes support for Server Name Identification, which improves support for TLS by sending your OpenShift-configured domain alias as a part of the handshake.

Support for enabling HTTPS connections to custom, aliased hostnames is available for users of OpenShift Online’s premium plans.

If you are not using one of the premium plans, or if you are connecting to your app using secure web sockets, you can always take advantage of our * wildcard certificate in order to securely connect to any application via it’s original, OpenShift-provided hostname URL.

If you are still getting by on the Free Plan, you’ll see a warning message at the top of your application’s SSL configuration area. Upgrading to the Bronze or Silver plan adds support for providing your own SSL cert.

Web Console

SSL Certificate

Note If your SSL certificate includes a bundled file with primary certificate and intermediate certificate concatenated into a single file (a .crt or .pem file), this is the file you will need to upload. If your SSL provider does not provide a concatenated file, you will need to manually concatenate the files. From the directory on your server where your certificate files are, run the following command to create the concatenated file:

$ cat your_primary_cert.pem your_intermediate_cert.pem >> fullchain.pem

It is the concatenated file that you will upload to the web console.

After saving, you should be able to make HTTPS-based connections to your hosted application on your custom domain.

Command Line (rhc)

You can add a custom SSL certificate to an alias with the following command using the concatenated certificate file (see above):

$ rhc alias update-cert <application_name> <domain_name> --certificate <cert_file> --private-key <key_file>

If the private key is encrypted, specify the passphrase with the --passphrase option.

Generating a CSR (Certificate Signing Request)

Where should I generate the CSR?

You can either generate the CSR on your workstation (if you have openssl installed) or ssh to your gear (rhc app ssh) to generate your CSR. Either way should work fine.

It can help to create your files with the name of the domain that you are creating them for, this helps keep them all organized. The following guide uses to represent whatever domain you are creating your CSR for. Feel free to use this method, or your own.
Generate a private key

If generating the CSR from a workstation, enter the following command and hit Enter. This will create a 2048-bit key that you will use to create your CSR. You will also need this file when you load your SSL certificate into the OpenShift Web Console.

You must enter a passphrase during this step, but don’t worry, you can remove it later. If you plan on removing the passphrase just choose something simple like 'password'.

$ openssl genrsa -des3 -out 2048
Generating RSA private key, 2048 bit long modulus
e is 65537 (0x10001)
Enter pass phrase for
Verifying - Enter pass phrase for

If generating the CSR from an SSH session to your gear, ensure that the random state and key files are created in a directory where you have write permissions. Enter the below commands and hit Enter.

$ openssl genrsa -des3 -out $OPENSHIFT_DATA_DIR/ 2048
Generating RSA private key, 2048 bit long modulus
e is 65537 (0x10001)
Enter pass phrase for
Verifying - Enter pass phrase for
Generate the CSR

Now that you have a private key you can generate the CSR. Enter the below command and hit Enter, making sure that you are in the same directory as the key file you generated earlier. Enter the same passphrase that you used earlier when generating your key file.

Now you are ready to enter the information for the CSR. The most important part is to make sure that the "Common Name" matches the domain name that you are going to use with your OpenShift application. Fill in all of the other fields to the best of your knowledge. You do not need to include a "challenge password" or "optional company name".

$ openssl req -new -key -out
Enter pass phrase for
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:North Carolina
Locality Name (eg, city) []:Raleigh
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Red Hat, Inc
Organizational Unit Name (eg, section) []:OpenShift
Common Name (e.g. server FQDN or YOUR name) []
Email Address []

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:Red Hat, Inc

Now you should have two files,, and

(Optional) Remove the Passphrase from the Key file

You do NOT have to remove the passphrase from the key file, OpenShift supports key files with passphrases and provides a field to enter the passphrase when installing the certificate.

Use the below commands to remove the passphrase from your key file, make sure that you enter the same passphrase that you used when creating the key earlier.

$ cp
$ openssl rsa -in -out
Enter pass phrase for
writing RSA key
What do I do with all of these files?

The CSR file is what you submit to the company that you are purchasing your SSL Certificate from. Once you have submitted that file, they will send you a ZIP file with more files in it, including your SSL Certificate and any Chain Certificates that you might need.

For more information on how to install your new SSL Certificate on OpenShift click here.

Using Intermediary Certificates (certificate chaining)

You can creat your own custom SSL certificate and chain it together with the root certificate. You’ll need to combine your Certificate, Intermediary Certificate, and Root Certificate into a single file and upload this into your OpenShift alias.

$ rhc alias-update-cert <application> <alias> --certificate FILE --private-key FILE [--passphrase PASSPHRASE]

More information about this topic, along with common issues, can be found here