Managing certificates with Vault

Internal certificates

For the internal certification between the HCL Commerce Docker containers, you must ensure that the Common Name (CN) in your certificate and "SubjectAlternativeName" can match the host name that the Docker containers will use. Also, when other source containers connect to a target container, the source container must use the target container's host name. There is strict verification logic in place to check whether the host name that is used in a request is the same as the SubjectAlternativeName in the certificate on the target container. If the host names do not match, then the connection fails.

Here are the SubjectAlternativeNames in the default internal certification that is included in the HCL Commerce Docker containers:

SubjectAlternativeName [
  DNSName: *
  DNSName: app
  DNSName: web
  DNSName: search
  DNSName: store
  DNSName: tooling-web
  DNSName: store-web
  DNSName: query
  DNSName: data-query
  DNSName: ingest
  DNSName: nifi
  DNSName: registry
  DNSName: elasticsearch
  DNSName: zookeeper
  DNSName: localhost
  DNSName: search_master
  DNSName: search_repeater
  DNSName: search_slave
]

If you do not use the default host names then you need to reconfigure the connections between containers. To learn how to create your own certificates, see Managing certificates manually. Otherwise you can use Vault as the certificate authority (CA).

Configuring Vault to act as the certificate authority (CA)

You can configure Vault as a CA with a PKI backend. If you want use this method, you need to hard code the PKI backend name as 'selfserve_production_pki' and PKI role as 'generate-cert'. Assuming that you have Vault installed, unsealed, and an environment that has a Vault client that can connect to the Vault server with the correct address and token, you can complete the following steps to set up Vault as a CA.

Create a PKI type backend.

vault secrets enable -path=selfserve_production_pki -description="SelfServe Root CA" -max-lease-ttl=87600h pki

Enable Vault PKI feature to act as the Certificate Authority (CA) organization to issue certificates.
1. Run the command to create a Root CA Certificate.
```
vault write selfserve_production_pki/root/generate/internal  common_name="selfserve_production_pki Root CA"  ttl=87600h  key_bits=4096  exclude_cn_from_sans=true
```
2. Run the following command to create a role that will be used to issue certification for each Docker container.
```
vault write selfserve_production_pki/roles/generate-cert key_bits=2048 max_ttl=8760h allow_any_name=true enforce_hostnames=false
```
  The command completes with a Success! Data written to: selfserve_production_pki/roles/generate-cert message.

Verify whether you can get certification from PKI.

curl -sS -X POST -H "X-Vault-Token:<Vault_token>" -d "{\"common_name\":\"<common_name>\", \"ttl\":\"1344h\"}" http://<Vault_IP>:8200/v1/selfserve_production_pki/issue/generate-cert

You should receive a response similar to the following output.

Key Value
--- -----
lease_id cuddletech_ops/issue/web_server/e03318f2-d005-8196-4ed5-a42f9cd55238
lease_duration 2591999
lease_renewable false
certificate -----BEGIN CERTIFICATE-----
MIIE7jCCAtagAwIBAgIUN+vXFuIf42v1SW+mDROUVAm+lUMwDQYJKoZIhvcNAQEL
BQAwKTEnMCUGA1UEAxMeQ3VkZGxldGVjaCBPcHMgSW50ZXJtZWRpYXRlIENBMB4X
DTE2MDcwOTA5MzE1N1oXDTE2MDgwODA5MzIyN1owIjEgMB4GA1UEAwwXc3NsX3Rl
...
issuing_ca -----BEGIN CERTIFICATE-----
MIIF5DCCA8ygAwIBAgIUdhJTQb4YmCyhUUr48L20o0R+dFkwDQYJKoZIhvcNAQEL
...
private_key -----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEApBabDpPZIloRQUpro3tQEls0FEFvsvfraQzQJLD2dicSPZ2s
CqYyT8OXMclrapG7KKTYp79AaTW8LgNg3WvCzoMGDfhLL9m0QomzrMDzoW8Q7iQO
1MV4f6JXjGMbOMMXatKQlO32fLZln8m+/yJ3pOW0S6uatFzZ/N3+ed+gDuUc7eAO
...
private_key_type rsa
serial_number 37:eb:d7:16:e2:1f:e3:6b:f5:49:6f:a6:0d:13:94:54:09:be:95:43
'''

Starting a container with VAULT_CA=`true`

After you configured Vault as the CA, you can start the container with the VAULT_CA=true parameter. Use this method in a Docker orchestration platform such as Kubernetes. When VAULT_CA=true, the scripts follow the

TENANTENVIRONMENTENVTYPEcontainer_name.DOMAIN_NAME

pattern to apply certifications. With this mode, the host name is fixed. If you do not provide a DOMAIN_NAME, the default is default.svc.cluster.local.

Starting a container with VAULT_CA=`true` and CONTAINER_HOSTNAME=`customHostName`

Beginning with HCL Commerce 9.0.0.2, you can start the container with VAULT_CA=true and CONTAINER_HOSTNAME=customHostName. Use this method on your own custom environment where you do not have TENANTENVIRONMENTENVTYPE. When CONTAINER_HOSTNAME is passed, the start up logic /SETUP/bin/updateCerts.sh applies the internal certification based on the host name that you provide. For example, to start the Store server Docker container with host name mycustomstore

docker run -d -e LICENSE=accept  \
    -e SPIUSER_NAME=spiuser \
    -e SPIUSER_PWD=<Your spiuser password that you encrypted with wcs_encrypt.sh>
    -e VAULT_TOKEN=<vault_token > \
    -e VAULT_URL=<vault_url. For example, http://IP:Port/v1> \
    -e VAULT_CA=true \  
    -e CONTAINER_HOSTNAME=mycustomstore    
    <Store_Docker_Image>

External Certificates

For secure SSL communication between HCL Commerce and an external system, ensure that you are importing the proper certificates into your key store and trust store. Also ensure that your customization code references the correct certificate name for that communication. You can put your third party certificates in Vault to enable the updateCerts.sh configuration script to import any certificates into your key store automatically.

To include external certificates:

Create a certificate bundle (certBundle) for your external certificate.

Note: If the purpose of a certificate bundle that you are creating is to trust a certificate assigned for an external system, then only the issusing_ca must be specified. In this case the certificate and private_key values can be empty, or left out of the certBundle definition entirely.

A certBundle is a JSON object containing a certificate, its private key, and the certificate authority (CA) certificate or certificate chain. An example of a certBundle is as follows.

{ 
 "certificate": "certificate", 
 "private_key": "private_key", 
 "issuing_ca": "ca_certificates" 
}

The contents of the certificate bundle are as follows.

The certificate value holds the certificate, in base64 PEM format, that should be assigned to the specified HCL Commerce application server:

The value of this certificate should be wrapped within -----BEGIN CERTIFICATE-----\n and -----END CERTIFICATE----- lines of text.
The value of the certificate should only be one line of text, and be concluded by an \n, to denote the end of line.

An example of the certificate value is as follows.

The private_key value holds the private key matching the certificate, and it is required to install the certificate for the HCL Commerce application server:

The value of this certificate should be wrapped within -----BEGIN RSA PRIVATE KEY-----\n and -----END RSA PRIVATE KEY----- lines of text.
The value of the certificate should only be one line of text, and be concluded by an \n, to denote the end of line.

An example of the certificate value is as follows.

The issuing_ca value holds the certificate authority (CA) certificate, or certificate authority certificate chain, that are used to validate the certificate. For example, if the certificate is signed by an intermediate CA certificate, both the intermediate CA certificate and its root CA certificate should be included within the issuing_ca value.

The value of this certificate should be wrapped within -----BEGIN CERTIFICATE-----\n and -----END CERTIFICATE----- lines of text.
The value of the certificate should only be one line of text, and be concluded by an \n, to denote the end of line.

An example of the issuing_ca value is as follows.

Write the certBundle data to Vault.
Important: Each certBundle must have a unique name. For example, cert1 and cert2.
For example, the following curl command writes the contents of the certBundle, cert_bundle_json, to the cert1 definition under a specified tenant and environment.
```
curl -sS -X POST -H "X-Vault-Token:<Vault_token>" -d "{\"value\":<cert_bundle_json>}" http://<Vault_IP>:8200/v1/<tenant>/<environment>/certs/cert1 
```
Specify which certBundle certificates should be deployed to each HCL Commerce application server.
This is done by updating the certsBundle definition on your specified tenant and environment, {tenant}/{environment}/certsBundle, with the following JSON object format.
```
{ 
    "value":
        {
        "tsapp": "cert1,cert2", 
        "crsapp": "cert1,cert2", 
        "searchapp": "cert1,cert2", 
        "xcapp": "cert1,cert2", 
        "storeapp": "cert1,cert2" 
        }
}
```
In this example, both certsBundle cert1 and cert2 are deployed to, and applied within, five HCL Commerce application servers.
Deploy your HCL Commerce applications to apply the external certificates.
Certificates will not be applied by the updateCerts.sh utility script without a deployment to trigger it.