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).
Table of contents
- 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/