Setting Up Certificates

2 months ago • 4 min read

Server v2.x Admin

CircleCI Server version 2.x is no longer a supported release. Please consult your account team for help in upgrading to a supported release.

This document provides a script for using a custom Root Certificate Authority and the process for using an Elastic Load Balancing (ELB) certificate.

Using a Custom Root CA
Setting up ELB Certificates
- Using Self-Signed Certificates
Setting up TLS/HTTPS on CircleCI Server

Using a Custom Root CA

Any valid certificates added to the following path will be trusted by CircleCI services: usr/local/share/ca-certificates/

The following example openssl command is one way of placing the certificate. It is also possible to pull a certificate from a vault/PKI solution within your company.

Some installation environments use internal Root Certificate Authorities (RCAs) for encrypting and establishing trust between servers. If you are using a customer Root certificate, you will need to import and mark it as a trusted certificate at CircleCI GitHub Enterprise instances. CircleCI will respect such trust when communicating with GitHub and webhook API calls.

CA Certificates must be in a format understood by Java Keystore, and include the entire chain.

The following script provides the necessary steps:

GHE_DOMAIN=github.example.com

# Grab the CA chain from your GitHub Enterprise deployment.
openssl s_client -connect ${GHE_DOMAIN}:443 -showcerts < /dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /usr/local/share/ca-certificates/ghe.crt

Then, navigate to the system console at port 8800 and change the protocol to upgraded. You can change the protocol to HTTPS (TLS/SSLEnabled) setting and restart the services. When trying Test GitHub Authentication you should get Success now rather than x509 related error.

Setting up ELB Certificates

CircleCI requires the following steps to get ELB certificates working as your primary certs. The steps to accomplish this are below. You will need certificates for the ELB and CircleCI server v2.x as described in the following sections.

Opening the port for HTTP requests will allow CircleCI to return a HTTPS redirect.

From Server v2.19.02 and up, Classic Load Balancer (CLB) is no longer supported.

Open the following ports on your ELB:

Load Balancer Protocol	Load Balancer Port	Instance Protocol	Instance Port	Cipher	SSL Certificate
HTTP	80	HTTP	80	N/A	N/A
SSL	443	SSL	443	Change	your-cert
SSL	3000	SSL	3000	Change	your-cert
HTTPS	8800	HTTPS	8800	Change	your-cert
SSL	8081	SSL	8081	Change	your-cert
SSL	8082	SSL	8082	Change	your-cert

Add the following security group on your ELB:

The sources below are left open so that anybody can access the instance over these port ranges. If that is not what you want, then feel free to restrict them. Users will experience reduced functionality if your stakeholders are using IP addresses outside of the Source Range.

Type	Protocol	Port Range	Source
SSH	TCP	22	0.0.0.0
HTTPS	TCP	443	0.0.0.0
Custom TCP Rule	TCP	8800	0.0.0.0
Custom TCP Rule	TCP	64535-65535	0.0.0.0

Next, in the management console for CircleCI, upload a valid certificate and key file to the Privacy Section. These don’t need to be externally signed or even current certs as the actual cert management is done at the ELB. But, to use HTTPS requests, CircleCI requires a certificate and key in which the "Common Name (FQDN)" matches the hostname configured in the admin console.
It is now possible to set your GitHub Authorization Callback to https rather than http.

Using Self-Signed Certificates

Because the ELB does not require a current certificate, you may choose to generate a self-signed certificate with an arbitrary duration.

Generate the certificate and key using openssl command openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 1 -out certificate.pem
Provide the appropriate information to the prompts.

The Common Name provided must match the host configured in CircleCI.
Save the certificate.pem and key.pem file locally.

Setting up TLS/HTTPS on CircleCI Server

You may use various solutions to generate valid SSL certificate and key file. Two solutions are provided below.

Using Certbot

This section describes setting up TLS/HTTPS on your server v2.x install using Certbot by manually adding a DNS record set to the Services machine. Certbot generally relies on verifying the DNS record via either port 80 or 443, however this is not supported on CircleCI server installations as of v2.2.0 because of port conflicts.

Stop the Service CircleCI server Management Console (<circleci-hostname>:8800).
SSH into the Services machine.

Install Certbot and generate certificates using the following commands:

sudo apt-get update
sudo apt-get install software-properties-common
sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update
sudo apt-get install certbot
certbot certonly --manual --preferred-challenges dns

You will be instructed to add a DNS TXT record.
After the record is successfully generated, save fullchain.pem and privkey.pem locally.

If you are using Route 53 for your DNS records, adding a TXT record is straightforward. When you’re creating a new record set, be sure to select type → TXT and provide the appropriate value enclosed in quotes.

Adding the certificate to CircleCI server

Once you have a valid certificate and key file in .pem format, you must upload it to CircleCI Server.

To do so, navigate to hostname:8800/console/settings
Under "Privacy" section, check the box for "SSL only (Recommended)"
Upload your newly generated certificate and key
Click "Verify TLS Settings" to ensure everything is working
Click "Save" at the bottom of the settings page and restart when prompted

Ensure the hostname is properly configured from the Management Console (<circleci-hostname>:8800) and that the hostname used matches the DNS records associated with the TLS certificates.

Make sure the Auth Callback URL in GitHub/GHE matches the domain name pointing to the Services machine, including the protocol used, for example https://info-tech.io/.

Adding the certificate to Replicated

The Replicated Management Console (<circleci-hostname>:8800) runs on a different web server, so you also need to apply the certificate used above for Replicated. To do so, follow these steps:

Navigate to <circleci-hostname>:8800/console/settings#tls-key-cert
Upload your newly generated certificate and key.
Click Save at the bottom of the page and restart the Replicated UI when prompted.

When the TLS certificate has expired and you can not access the Replicated UI using the domain name, you will still be able to access the Replicated UI using the IP address. Then, you can update the TLS certificate and key from the UI.

Alternatively, you can upload the certificate and key by running the following command on the Services machine, substituting your hostname, path-to-key and path-to-certificate:

$ sudo replicated console cert set <circleci-hostname> /path/to/key /path/to/cert
$ replicatedctl app stop
$ replicatedctl app start

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Suggest an edit to this page (please read the contributing guide first).
To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.