Customer Internal CA

This directory contains the internal certificate authority (CA) related scripts help to create own (test) CA and certificates.

Customer Internal CA

Prerequisites

We should download the docker-compose template: [Download]

Right now we will use easyrsa3 helper tool. This tool uses openssl, so it needs to be installed, if you do not use some Linux vendor packaged edition. The helper script called prepare-cust-ca.sh needs an additional tool called yq to change parts of docker-compose.yml YAML file. Please make sure the downloaded version is as fresh as available!

Install on Debian/Ubuntu

sudo add-apt-repository ppa:rmescandon/yq
sudo apt-get update
sudo apt-get install easy-rsa yq

Install on Fedora/Centos/RedHat

sudo curl -L -o /usr/local/bin/yq https://github.com/mikefarah/yq/releases/download/3.4.1/yq_linux_amd64
sudo chmod a+x /usr/local/bin/yq
sudo yum install epel-release
sudo yum makecache
sudo yum install easy-rsa

Install on OpenSuse/SLES

sudo curl -L -o /usr/local/bin/yq https://github.com/mikefarah/yq/releases/download/3.4.1/yq_linux_amd64
sudo chmod a+x /usr/local/bin/yq
sudo zypper refresh
sudo zypper install easy-rsa

Install on Alpine

MIRROR_URL=$(grep "main$" /etc/apk/repositories|sed -e 's#\(.*\/alpine\)/.*$#\1#')
echo "$MIRROR_URL/edge/community" >> /etc/apk/repositories
apk update
apk install easy-rsa yq

Create the PKI infrastructure

To create custom Public Key Infrastructure (PKI), we should create a new CA, and create server certificates, and sign with the created CA

Creating directory to start the process

The first step is creating the PKI infrastructure.

Warning! All steps needs to start inside of freshly created directory.

make-cadir ca-dir
cd ca-dir
./easyrsa init-pki

Customize the vars file

We should change these parameters:

...
set_var EASYRSA_DN    "org"
...
set_var EASYRSA_REQ_COUNTRY   "US"
set_var EASYRSA_REQ_PROVINCE  "California"
set_var EASYRSA_REQ_CITY      "Los Angeles"
set_var EASYRSA_REQ_ORG       "Example Startup Company"
set_var EASYRSA_REQ_EMAIL     "[email protected]"
set_var EASYRSA_REQ_OU        "IT Sec group"
...
set_var EASYRSA_CA_EXPIRE     3650
...
set_var EASYRSA_CERT_EXPIRE   1080
...
set_var EASYRSA_NS_SUPPORT    "yes"
...
set_var EASYRSA_NS_COMMENT    ""
...

Create new CA

If the vars file changed well, the only important question is about Common Name (CN) of the CA.

./easyrsa build-ca nopass

Create new Server certificate

Here the script also asks about CN, please be careful with this. Using wildcard (for ex.: *.examplestartup.com) here is also allowed.

./easyrsa gen-req server nopass

Sign server certificate with CA

./easyrsa sign-req server server

Copy the created certificates

We should create a directory called ssl next to docker-compose.yaml, copy the files like this example, and set the needed permissions:

mkdir -p ssl
cp ca-dir/pki/private/server.key ssl/private.key
cp ca-dir/pki/issued/server.crt ssl/certificate.crt
cat ca-dir/pki/ca.crt >> ssl/certificate.crt
chmod -R a+r ssl/
chmod a+w ssl/

Preparing the .env and docker-compose.yml

If we want to use the certificates in SSL, we need some change in .env and in docker-compose.yml as well.

Changes in docker-compose.yml

We can use the prepare-cust-ca.sh shell script, which can extend the docker-compose.yml file with the needed options. It will change some part of the .env file as well.

Changes in .env file

We should edit the file, and change lines like this, if it needs:

...
# Public domain of the deployment
PUBLIC_DOMAIN=platform.examplestartup.com

# Public URL of the deployment that will be used for external access (Public domain + protocol + port)
PUBLIC_URL=https://platform.examplestartup.com

# Public URL of the SSO endpoint that will be used for external access. In most cases it should be the same as the PUBLIC_URL
SSO_PUBLIC_URL=https://platform.examplestartup.com
...
CUSTOM_CA_CERTS_FILE=<custom certificate file's name located under ssl folder>
...
JHUB_CUSTOM_CA_CERTS=/full/path/to/platform/ssl/deb_cacerts/

Warning! JHUB_CUSTOM_CA_CERTS must contains the full path of your platform directory, plus ssl/deb_cacerts/ subdirectory.

Starting the platform

The starting process is the same as documented in the official documentation.

Steps after deployment or deployment errors

Delete previously created subdirs

If we want to restart the certificate transformation part of the Initialization service, we should remove the created subdirs:

sudo rm -fr ssl/deb_cacerts/
sudo rm -fr ssl/java_cacerts/
sudo rm -fr ssl/rh_cacerts/

Categories

Versions