How to configure your Jenkins server with SSL certificate

This guide elaborates step by step on how to add a SSL certificate to your Jenkins server, for Windows and Linux deployments ;-)
Please consider some variations in your deployment, OS version, paths, etc.

Some prerequisites:

• My endpoint has a Windows OS attached to a domain with a Microsoft CA issuing server in it’s network.
• Basic knowledge of PKI, especially on how to issue a certificate from your local CA (Certificate Authority).
• OpenSSL
• WinSCP

Let’s start with Linux, my deployment ran on Ubuntu 18.04, I based the following on the steps I had to overcome…

1. Create a PFX — Assuming you have the right permissions to issue a certificate from your CA, create a certificate with all the necessary fields. Keep in mind that latest browsers mandate the use of SAN (Subject Alternate Name), be sure a input on the server DNS name and/or it’s IP.
2. Split the PFX file to .key + .crt — Using OpenSSL, split the PFX certificate into .key+.crt, once for the .key and once for the .crt:

openssl pkcs12 -in path_certificate.pfx -nocerts -out path_key.key
openssl pkcs12 -in path_certificate.pfx -clcerts -nokeys -out path_cert.crt

3. Convert the .key + .crt to .p12 file — Again. using OpenSSL, combine the .key+.crt into a .p12 file:

openssl pkcs12 -export -out server.p12 -inkey path_key.key -in path_cert.crt

4. Install Root certificate —
- Extract the Root certificate from your PC (or either from your issuing CA, your Root CA or any other server in your local network).
- Convert the .cer or .crt file to .pem using OpenSSL command:

openssl x509 -inform der -in certificate.cer -out certificate.pem

- SCP to the Linux machine using WinSCP and copy the .pem converted root certificate to /usr/local/share/ca-certificates.
- Update the CA certificates in the Linux machine with this command: update-ca-certificate

5. Copy the .p12 file to the server — same is in the previous step, copy with WinSCP the .p12 file to a location in the server, I used /tmp

6. Convert .p12 file to .jks — As Jenkins uses Java, we have to use JKS file. A JKS file is an encrypted security file used to store a set of cryptographic keys or certificates in the binary Java KeyStore (JKS) format.
Run the following on the server, modify per your naming convention:

keytool -importkeystore -srckeystore jenkins.p12 \ 
-srcstorepass ‘chosen_pass’ -srcstoretype PKCS12 \
-srcalias jekins.contoso.com -deststoretype JKS \
-destkeystore jenkins.jks -deststorepass ‘chosen_pass’ \
-destalias jenkins.contoso.com

7. Once converted, copy the .jks certificate from it’s location (if you left it at /tmp) to it’s final destination.

8. Modify the Jenkins configuration file — the configuration file resides in /etc/default/Jenkins, scroll to the last line and change it from:

JENKINS_ARGS=” — webroot=/var/cache/$NAME/war — httpPort=$HTTP_PORT”

to

JENKINS_ARGS=” — httpPort=-1 — httpsPort=8443 — httpsKeyStore=/path/to/jenkins.jks — httpsKeyStorePassword=chosen_pass — httpsListenAddress=0.0.0.0"

If you want to allow both HTTP and HTTPS you can leave the object httpPort as it was and just add the rest of the configuration line.
Reference A, B

9. Restart the Jenkins service — with sudo jenkins restart.

10. If your local network is segmented properly, don’t forget to update the firewall rules to the Jenkins server to support the new port.

Moving on to Windows deployments:

1. Create a PFX — Assuming you have the right permissions to issue a certificate from your CA, create a certificate with all the necessary fields. Keep in mind that latest browsers mandate the use of SAN (Subject Alternate Name), be sure a input of the server DNS name or it’s IP.
2. Split the PFX file to .key + .crt — Using OpenSSL, split the PFX certificate into .key+.crt, once for the .key and once for the .crt

openssl pkcs12 -in path_certificate.pfx -nocerts -out path_key.key
openssl pkcs12 -in path_certificate.pfx -clcerts -nokeys -out path_cert.crt

3. Convert the .pfx file to .jks — Copy the .pfx file to your Jenkins Windows based server and run for following from c:\jenkins\jre\bin (modify the path per your deployment):

keytool -importkeystore -srckeystore jenkins.pfx -srcstoretype pkcs12 -destkeystore jenkins.jks -deststoretype JKS

4. Copy the .jks file to C:\Jenkins\secrets

5. Update the configuration file — In C:\Jenkins\jenkins.xml change the line (bottom of the .xml) that includes the following:

-Xrs -Xmx10240m -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -jar “%BASE%\jenkins.war” — httpPort

to

Xrs -Xmx10240m -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -jar “%BASE%\jenkins.war” — httpPort=-1 — httpsPort=443 — httpsKeyStore=”%BASE%\Cert\Jenkins.jks” — httpsKeyStorePassword=[Cert password from step 1]

6. Again, same as with the Linux disto, if your local network is segmented properly, don’t forget to update the firewall rules to the Jenkins server to support the new port.