Skip to main content

Use custom Certificates Authorities

GitGuardian provides the option to use a custom Certification Authority (CA) for some of the integration. Configuring this will permit the GitGuardian application to verify certificates signed by the custom CA.

It is only supported with the following integrations:

  • GitHub Enterprise
  • GitLab Self-Managed
  • Azure DevOps
  • BitBucket
  • Splunk alerting
  • Custom webhook alerting

Prerequisites#

To use your CA certificates with the GitGuardian application, you have two options:

  • generate a pem file with the entire SSL certificate trust chain.
  • use a zip bundle containing the CA certificates.
danger

The zip was the old experimental feature to use custom CA with GitGuardian.
It will be deprecated on 2023.02.0, which will be delivered in 2023 February.

Please consider moving to the pem file as soon as possible!

Format your file with multiple pem certificates#

In case of multiple certificates, you should concatenate them into a single file, like the example below:

-----BEGIN CERTIFICATE-----xxx(your first certificate)xxx-----END CERTIFICATE----------BEGIN CERTIFICATE-----xxx(your second certificate)xxx-----END CERTIFICATE----------BEGIN CERTIFICATE-----xxx(your third certificate)xxx-----END CERTIFICATE-----

Generate a zip bundle with multiple certificates (deprecated)#

This version will be deprecated in 2023 February.
Please migrate to the pem file as soon as possible.

You need to generate a bundle using the following steps:

  1. Get your certificates to establish the chain of trust, and put them in a folder, one file per certificate. Here we use $HOME/gitguardian/trusted-certs.
$ tree $HOME/gitguardian/trusted-certs/home/centos/gitguardian/trusted-certs├── my-other-ca.pem└── my-private-ca.pem
0 directories, 2 files
  1. Install c_rehash from OpenSSL:
# On CentOS/RHELyum install openssl-perl
# On Debian/Ubuntuapt-get install openssl
  1. Prepare the directory for openssl to consume using c_rehash.
$ c_rehash $HOME/gitguardian/trusted-certsDoing /home/centos/gitguardian/trusted-certs
$ tree $HOME/gitguardian/trusted-certs/home/centos/gitguardian/trusted-certs├── 4dfd5795.0 -> my-private-ca.pem├── da4e607d.0 -> my-other-ca.pem├── my-other-ca.pem└── my-private-ca.pem
0 directories, 4 files
  1. Zip the folder. Make sure that all files are at the root of the archives, without any directory in between.
$ cd $HOME/gitguardian/trusted-certs$ zip -r ../trusted-certs-bundle.zip .
  1. Your bundle is created in $HOME/gitguardian/trusted-certs-bundle.zip

Upload and deploy#

Connect to the Admin Console and navigate to the Custom Certificate Authority section. Check the Use custom CA setting.
Depending on the type of file you generated, you'll have to check the corresponding option.

You can now upload your CA certificate file:

Configure your custom Certificate Authority

Once uploaded, do not forget to save the configuration at the bottom of the page.
You'll also have to redeploy the application for the change to be taken into account.

Certificates will be then installed and used by the application.