Custom root certificate recipes.

There are some cases when a company establishes its own root certification authority (CA) by creating a self-signed root certificate then issuing some certificates for intermediate CAs signed by the root certificate and finally the intermediate (issuing) CAs are issuing certificates for the company’s internal sites.

In this article I’m not going to go into the details of all the issues related to the home-grown root certificates but I’ll give some recipes.

How to add a custom root certificate to a Windows git client

First of all you need to export the root certificate. Try to use Microsoft Internet Explorer or Google Chrome.  Firefox uses it’s own approach for working with PKI certificates and doesn’t show custom root or intermediate certificates sometimes.

The following instruction is for Internet Explorer 11 but other versions of IE or Chrome should be similar.

1. Open the link to your git repository https://my.site.com/git/ When you access it the first time you might need to export the root certificate into the Windows root CA storage.
2. Click on the small lock icon at the end of the address bar and select “View certificates”.
3. Select “Certification Path” tab – you should see a certificates hierarchy e.g. “Awesome Root CA”, “Awesome Issuing CA” and “my.site.com”.
4. Select “Awesome Root CA” certificate and click “View Certificate”.
5. Go to the “Details” tab and click “Copy to File…” button.
   Note: In some cases, in order to enable this button, you need to start IE using “Run as administrator” option.
6. Click “Next” and select “Base-64 encoded X.509 (.CER) and then “Next”.
7. Click “Browse” navigate to the folder where you are going to keep your certificates (e.g C:\my_certificates).
8. Select a file name (e.g my.site.com), click “Next” and then “Finish.

Now you have to configure Git to trust the root certificate, e.g.:

>git config --global http.https://my.site.com.sslCAInfo C:\my_certificates\my.site.com.cer

You can also check to make sure Git was configured properly:

>git config --global --get http.https://my.site.com.sslCAInfo

How to set up VSTS Agent to run on Ubuntu using a custom root certificate.

In this workflow I’ll demonstrate step by step how to add a custom root certificate so that VSTS Cross Platform Agent (.NET Core) on Ubuntu 14.04.4 LTS (Trusty Tahr) can access your TFS server.

Firs of all create an Ubuntu VM on your Windows machine and connect using Putty. I am using Vagrant and for provisioning VM on VirtualBox.

1. Crate a folder for your VM (e.g. BuildAgent)

   > mkdir BuildAgent
   > cd BuildAgent

2. Using the procedure described above you need to obtain the root certificate for your TFS server (e.g. my.site.com) and save it to BuildAgent folder.
3. Create Vagrant file for Ubuntu

   \BuildAgent> vagrant init ubuntu/trusty64

4. Create VM using Vagrant

   \BuildAgent> vagrant up

5. Connect to the VM using putty

   \BuildAgent> vagrant putty

Assuming that your you’ve got your root certificate as \BuildAgent\my.site.com.cer copy the certificate to your certificates folder and rename to my.site.com.crt (the renaming part is quite important otherwise the certificate won’t be found by update-ca-certificates).

~/$ sudo cp /vagrant/my.site.com.cer /usr/local/share/ca-certificates/my.site.com.crt

Merge the certificate with the rest of the root certificates.

~/$ update-ca-certificates

The command response should contain something like:

Updating certificates in /etc/ssl/certs... 1 added, 0 removed; done.

You can also check if the certificate was successfully merged by opening /etc/ssl/certs/ca-certificates.crt and scrolling to the end.

Now you might want to install the TFS agent and start it. In this example I’m using Kerberos authentication providing “–auth negotiate” alongside with the user name and password.

~/$ sudo apt-get install -y libunwind8 libcurl3 libicu52

~/$ mkdir Downloads && cd Downloads

~/Downloads$ curl -kSLO https://github.com/Microsoft/vsts-agent/releases/download/v2.99.0/vsts-agent-linux-2.99.0-0428.tar.gz

~/Downloads$ cd ..

~/$ mkdir myagent && cd myagent

~/myagent$ tar zxvf ~/Downloads/vsts-agent-linux-2.99.0-0428.tar.gz

~/myagent$ ./run.sh --url https://my.site.com/tfs --agent myagent --pool default --auth negotiate --username DOMAIN\\user --password ********