Configure Jenkins with a Self Signed SSL Certificate and Root CA Certificate

This article will go over the steps required to create a root CA certificate and a self signed certificate for installation on a Jenkins linux server. Using a self signed certificate is great for a small organization or personal use where the server is on a private network. If the server is intended for public access on the open internet, then consider purchasing an SSL certificate signed by a known authority or use a free service such as Let’s Encrypt.

The root certificate will need to be installed on each device that will access the server. This is required so that the self signed certificate is trusted by your browser or whatever software is accessing the server. Here is an excellent tutorial on how to install root CA on many OS and devices

Create the root CA certificate
Follow these steps to create your own root certificate authority certificate. After generating the certificates, place the .key in a safe location such as LastPass The .key file is the private secret data that is needed when you generate new self signed certificates. The .crt file can be shared with others who need to access servers that have your self signed certificate. This is the file that will need to be installed to allow trust of the self signed certificate.


openssl genrsa -aes256 -out your_rootCA.key 4096


openssl req -x509 -new -nodes -key your_rootCA.key -sha256 -days 3650 -out your_rootCA.crt -subj '/CN=Your Root CA/C=YourCountry/ST=YourState/L=YourCity/O=Your Organization'

Create a Jenkins SSL certificate

Jenkins has no requirements on the self signed certificate file names. In this example we use jenkins.yourdomain.com. You can name the file anything you like.


openssl req -new -nodes -out jenkins.yourdomain.com.csr -newkey rsa:4096 -keyout jenkins.yourdomain.com.key -subj '/CN=Jenkins Server/C=YourCountry/ST=YourState/L=YourCity/O=Your Organization'

Next you will need to create a v3 ext file for SAN properties. This will allow you to apply multiple names such as the server name and domain name along with the static IP address of the server.


cat > jenkins.v3.ext << EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names
[alt_names]
DNS.1 = yourserver.local
DNS.2 = jenkins.yourdomain.com
IP.1 = 192.168.1.100
EOF

Next create the server certificate using the v3 ext file. In this example, we set the maximum of 825 days to expiration. If you set this to a higher number, you will run into issues on the Mac operating system due to security constraints.


openssl x509 -req -in jenkins.yourdomain.com.csr -CA your_rootCA.crt -CAkey your_rootCA.key -CAcreateserial -out jenkins.yourdomain.com.crt -days 825 -sha256 -extfile jenkins.v3.ext

Configure Jenkins

For this configuration we are using Apache in front of Jenkins where it acts as a proxy. This means that we don't actually configure Jenkins to use SSL, rather we are configuring Apache in a more common way.

Apache Install

Here is a quick example of how to install Apache web server on Fedora 35 or higher. You can easily find instructions for your operating system if you are using something non Red Hat based.


sudo dnf install httpd mod_ssl -y
sudo systemctl enable httpd.service
sudo systemctl start httpd.service

Once you have Apache installed, copy your Jenkins SSL certificates to the tls/certs folder.


sudo cp jenkins.yourdomain.com.crt jenkins.yourdomain.com.key /etc/pki/tls/certs

Finally, configure Apache to use your SSL certificates and to act as a proxy to Jenkins.

Create the config file

/etc/httpd/config.d/jenkins.conf


<VirtualHost *:80>
    ServerName jenkins.yourdomain.com
    Redirect permanent / https://jenkins.yourdomain.com/
</VirtualHost>

<VirtualHost *:443>
    SSLEngine on
    SSLCertificateFile /etc/pki/tls/certs/jenkins.yourdomain.com.crt
    SSLCertificateKeyFile /etc/pki/tls/certs/jenkins.yourdomain.com.key
    ServerAdmin  domain@yourdomain.com
    ProxyRequests     Off
    ProxyPreserveHost On
    AllowEncodedSlashes NoDecode
    <Proxy *>
        Order deny,allow
        Allow from all
    </Proxy>
    ProxyPass         /  http://localhost:8080/ nocanon
    ProxyPassReverse  /  http://localhost:8080/
    ProxyPassReverse  /  http://jenkins.yourdomain.com/
    RequestHeader set X-Forwarded-Proto "https"
    RequestHeader set X-Forwarded-Port "443"
</VirtualHost>

Now you can restart Apache and Jenkins to test out your https connection.

Troubleshooting

If you run into trouble, you can use this command to see the contents of the certificates along with possible error messages.


echo Q | openssl s_client -showcerts -verify 5 -connect jenkins.yourdomain:443

If you see this message:

Verify return code: 21 (unable to verify the first certificate)

It means that you need to install the root CA certificate on the device you ran this troubleshooting command on. Check the guide linked at the top of this article for how to do this on a number of platforms. If you happen to be on a linux server you can run these commands to install the root CA.


openssl x509 -in your_rootCA.crt -out your_rootCA.pem -outform PEM
sudo mv your_rootCA.pem /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

Leave a Reply Cancel reply