Creating or Obtaining an SSL Key and Certificate

This page describes how to get a private key and an SSL certificate for HipChat Server. These are used to provide HTTPS-encrypted access to the web-based administration pages and to encrypt the messages sent through HipChat Server.

How SSL certificates work

If you're unfamiliar with or you just need a refresher on SSL certificates, you can learn about how they work here.

HipChat Server and SSL certificates

Each HipChat Server installation already has a unique private key and a self-signed certificate. This is provided for you to use while you're testing HipChat Server. When you're ready to deploy HipChat Server for your organization, we highly recommend you use your own private key and SSL certificate.

This page

Use your own private key and SSL certificate when you deploy HipChat Server to your organization. The self-signed certificate presents some functionality limitations to the native HipChat Clients and the HipChat integrations and, like all self-signed certificates, is vulnerable to a man-in-the-middle-attack.

You can get your own private key and SSL certificate in the following ways:

Generating a private key and CSR to get an SSL certificate

If your organization doesn't already have a private key and SSL certificate, follow the instructions in this section. It explains how to generate your own private key and a certificate signing request (CSR), which you can then use to get an SSL certificate.

  1. Generate a private key.
  2. Generate a certificate signing request (CSR).  
  3. Send the CSR to a certificate authority (CA), who will then send you an SSL certificate. (You can search online for a CA.)
  4. When you have your SSL certificate, replace HipChat Server's default private key and self-signed certificate with your own. 

Generating a private key

If you don't already have a private key, you can generate your own private key using openssl.

  1. Access the command line interface (CLI):
    • If you deployed HipChat Server using an open archive (OVA) file, open your virtual machine's console. 
    • If you deployed HipChat Server using an Amazon machine image (AMI), open a command line interface (CLI) and type:

      ssh admin@hipchat.example.com

      where hipchat.example.com is your fully qualified domain name (FQDN) (Or, you can use the HipChat Server's IP address.)

  2. To generate the private key, run the following command:

    openssl genrsa -out <fqdn>.key 2048

    where fqdn is your fully qualified domain name, such as hipchat.example.com.
    This command outputs your new private key, for example, hipchat.example.com.key.

  3. To download the private key from the server to to your local machine's current directory, run the following commands:

    scp admin@fqdn.com:/path/to/fqdn.key .

    where fqdn is your fully qualified domain name, such as hipchat.example.com

    You can also run the command less fqdn.key  to view, then copy your private key.

    If you deployed using an Amazon machine image (AMI), use the -i option to provide your private ssh key.

  4. Enter HipChat Server's ssh password when prompted. 
  5. Save your private key in a safe place. We recommend you use a secure password manager, like KeePass.
  6. Follow the steps in the next section to generate a CSR.

Generating a CSR

  1. Access the command line interface (CLI):
    • If you deployed HipChat Server using an open archive (OVA) file, open your virtual machine's console. 
    • If you deployed HipChat Server using an Amazon machine image (AMI), open a command line interface (CLI) and type:
      ssh admin@hipchat.example.com
      where hipchat.example.com is your fully qualified domain name (FQDN) (Or, you can use the HipChat Server's IP address.) 
  2. Run the following command:
    openssl req -new -key <fqdn>.key -out <fqdn>.csr   
    where <fqdn>.key is the private key you generated in the previous section and fqdn is your fully qualified domain name, such as hipchat.example.com 
  3. Answer the questions that appear on the screen.
    Note: Some CA's web parsing tools do not accept a CSR with the email address field or other optional fields included.
  4. If you deployed HipChat Server using an open archive (OVA) file:
    1. To download the CSR from the server to to your local machine's current directory, run the following command:
      scp admin@fqdn.com/fqdn.csr .
      where fqdn is your fully qualified domain name, such as hipchat.example.com 
      Note: You can also run the command less fqdn.csr to view, then copy your CSR.
    2. Enter HipChat Server's SSH password when prompted. 
  5. If you deployed HipChat Server using an Amazon machine image (AMI), run:
     scp -i path/to/aws.key admin@fqdn.com/fqdn.csr
    where fqdn is your fully qualified domain name, such as hipchat.example.com and aws.key is HipChat Server's SSH password
    Note: You can also run the command less fqdn.csr to view, then copy your CSR.
  6. Save your CSR in a safe place. 
  7. Send your CSR to a certificate authority (CA), who creates the SSL certificate for you. (You can search online for a CA.)
  8. When you have your certificate, replace HipChat Server's default private key and self-signed certificate with your own. 

Replacing HipChat Server's default key and self-signed certificate

Once you have your own private key and signed certificate, you can replace HipChat Server's default private key and self-signed certificate with yours.

Your private key must not require a passphrase. 

 

  1. In a text editor, concatenate your private key and SSL certificate in the following format: 

    -----BEGIN CERTIFICATE----- 
    (Primary SSL certificate: your_domain_name.crt) 
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE----- 
    (All required intermediate certificate files: intermediates.crt) 
    -----END CERTIFICATE----- 
    -----BEGIN RSA PRIVATE KEY----- 
    (The private key you generated: fqdn.key) 
    -----END RSA PRIVATE KEY-----
  2. Save the file using the following filename format: your_domain_name.pem 
    Note: A .pem file is just a Base64-encoded .der file.
  3. Copy the text of your .pem file.
  4. Log into HipChat Server using HipChat Server's fully qualified domain name (for example, https://hipchat.example.com) or HipChat Server's IP address (for example, https://IPv4).
  5. Click Server admin > SSL.
  6. Paste the text in the field provided.
  7. Click Modify.
    Note: Services are restarted with the new private key and SSL certificate. They can take a few minutes to restart. After they restart, you should see a lock symbol next to HipChat Server's url in your browser. (If you don't see the lock symbol, then the SSL certificate is not trusted by the browser. Check your private key and SSL certificates in your .pem file to ensure they're correct.)
  8. Click the lock symbol to verify that the new certificate is active. If it's active, you will see it trusted by your browser with the SSL details showing your certificate's Common Name and Organization.

We do not recommend including the Root CA certificate within the SSL certificate chain as this may cause trust issues.

Viewing the current private key and SSL certificate

You can view the key and certificate that is currently configured for HipChat Server from HipChat Server's web UI.

  1. Log into HipChat Server using HipChat Server's fully qualified domain name (for example, https://hipchat.example.com) or HipChat Server's IP address (for example, https://IPv4).
  2. Click Server admin > SSL.
    Note: This doesn't show the self-signed certificate that is included with HipChat Server.

You can also type the following command in the CLI:

  1. Access the command line interface (CLI):
    If you deployed HipChat Server using an open archive (OVA) file, open your virtual machine's console. 
    If you deployed HipChat Server using an Amazon machine image (AMI), open a command line interface (CLI) and type:
    ssh admin@hipchat.example.com
    where hipchat.example.com is your fully qualified domain name (FQDN) (Or, you can use the HipChat Server's IP address.)
  2. Type the following command:
    hipchat ssl --show
    Note: This command does show the self-signed certificate included with HipChat Server.

Installing SSL certificates for integrations

If you're integrating other applications with HipChat Server, you may need to install SSL certificates from other certificate authorities (CAs) for the integrations.

  1. Copy your integration's SSL certificate files to the following directory:
    /usr/local/share/ca-certificates 
  2. Run the following commands to update your SSL certificates:
    sudo update-ca-certificates
    hipchat service --restart 
    Services are restarted with the new SSL certificates. 

Tips for Ubuntu Desktop users

If you're using Ubuntu Desktop and the HipChat Linux Client, you can use the following commands when you need to update the trusted root CA certificates (and any intermediate certificates) to connect to HipChat Server:

/etc/ssl/certs				# the major default certificates (.crt)
/usr/local/share/ca-certificates	# user imported certificates
copy or create /usr/local/share/ca-certificates/MyNewCA.crt
sudo update-ca-certificates

Troubleshooting

Many certificate issues arise from badly formed pem files. Try the following:

  1. Create the pem file, again. Ensure you preserve line returns.
  2. Log in to HipChat Server using HipChat Server's fully qualified domain name (for example, https://hipchat.example.com) or HipChat Server's IP address (for example, https://IPv4).
  3. Click Server admin > SSL.
  4. Paste the key and certificate text in the field provided.
  5. Click Modify.

If the web user interface cannot be accessed within ten minutes of installing an SSL certificate or key, revert to the self-signed certificate.

Please check the HipChat Server SSL Installation and Troubleshooting Guide and the HipChat Knowledge Base for more troubleshooting information on configuring SSL certificates.

Reverting to a self-signed certificate

If you're having issues with the private key or SSL certificate you installed, you can revert to a self-signed certificate.

To generate and activate a new self-signed certificate, run the following command:

hipchat command line
hipchat certificates --selfsign

The self signed certificate has a CommonName equal to the current FQDN of HipChat Server.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport