Customer Internal CA

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

Please note, that for 2026.0.0 the method of the custom Certificate Authority setup has been changed to pass the strict certificate chain verification required by default in python urllib3 package (starting with version 2.4.0).

Customer Internal CA

Prerequisites

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

Right now we will use 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!

Create the Certificate chain

To create custom Certificate Authority starts with a private key generation and then we have to generate a self-signed certificate. This self-signed certificate will be used for signing the CSR (certificate sign request)

Creating Certificate Authority's (CA) private key

The first step is creating the private key.

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

make-cadir ca-dir
cd ca-dir
openssl genrsa -out rootCA.key 4096

Customize and generate the root CA certificate

Create a rootCA.cnf file for setting attributes to rootCA like CN, keyUsage, etc.. These parameters must be set:

[ req ]
distinguished_name = dn
x509_extensions = v3_ca
prompt = no
[ dn ]
# This can be modified
CN = MyRootCA
[ v3_ca ]
basicConstraints = critical,CA:true,pathlen:1
keyUsage = critical, keyCertSign, cRLSign
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer

# Creating and signing rootCA certificate
openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 3650 -out rootCA.crt -config rootCA.cnf -extensions v3_ca

Create the server CSR (certificate sign request) and private key

Create server_csr.cnf file for setting attributes to CSR like CN, alt_names, keyUsage, etc.. These parameters must be set:

[ req ]
distinguished_name = dn
req_extensions = v3_req
prompt = no
[ dn ]
# This can be modified
CN = foobar.examplestartup.com
[ v3_req ]
basicConstraints = critical,CA:false
keyUsage = critical, digitalSignature, keyEncipherment
subjectAltName = @alt_names
[ alt_names ]
# These can be modified but relate with CN value
DNS.1 = *.examplestartup.com
DNS.2 = foobar.examplestartup.com

Execute the command for generating the private key and CSR

openssl genrsa -out foobar.examplestartup.com.key 2048
openssl req -new -key foobar.examplestartup.com.key -out foobar.examplestartup.com.csr -config server_csr.cnf

Create new Server certificate

Having proper certificate is required to sign the CSR with rootCA. Create server_cert.cnf file for setting attributes of "final" server certificate:

These parameters must be set:

[ v3_req ]
basicConstraints = critical,CA:false
keyUsage = critical, digitalSignature, keyEncipherment
subjectAltName = @alt_names
[ alt_names ]
DNS.1 = *.examplestartup.com
DNS.2 = foobar.examplestartup.com

Signing the certificate request

openssl x509 -req -in foobar.examplestartup.com.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out foobar.examplestartup.com.crt -days 825 -sha256 -extfile server_cert.cnf -extensions v3_req

Verify the certificate

openssl verify -verbose -x509_strict -CAfile rootCA.crt foobar.examplestartup.com.crt

WARNING If there is any error here the creation process wasn't correct. Make sure the above commands and .cnf files are correctly set.

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/foobar.examplestartup.com.key ssl/private.key
cp ca-dir/foobar.examplestartup.com.crt ssl/certificate.crt
cat ca-dir/rootCA.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=foobar.examplestartup.com

# Public URL of the deployment that will be used for external access (Public domain + protocol + port)
PUBLIC_URL=https://foobar.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://foobar.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