Edit

Using TLS certificates

Certificates overview

Before installation of Workfusion SPA it is required to place TLS certificates into the <PACKAGE_DIR>/certificates directory.
The table below describes all certificates required to install full Workfusion SPA:

Settings in secrets.yml	Default file names	Description
Nginx Certificates
apm_ssl_cert apm_ssl_key	apm.crt apm.key	Certificate and its private key files in pem format for APM server. Used by nginx on APM server. Certificate's CommonName or SAN must match apm_hostname. Certificate file must include end certificate plus intermediate cert(s) if exist(s).
app_ssl_cert app_ssl_key	app.crt app.key	Certificate and its private key files in pem format for APP server. Used by nginx on APP server. Certificate's CommonName or SANs must match app_hostname and s3_hostname. Certificate file must include end certificate plus intermediate cert(s) if exist(s).
db_ssl_cert db_ssl_key	db.crt db.key	Certificate and its private key files in pem format for DB server. Used by nginx on DB server. Certificate's CommonName or SANs must match db_hostname. Certificate file must include end certificate plus intermediate cert(s) if exist(s).
ocr_ssl_cert ocr_ssl_key	ocr.crt ocr.key	Certificate and its private key files in pem format for OCR server. Used by nginx on OCR server. Certificate's CommonName or SANs must match ocr_hostname. Certificate file must include end certificate plus intermediate cert(s) if exist(s).
bi_ssl_cert bi_ssl_key	bi.crt bi.key	Certificate and its private key files in pem format for BI server. Used by Tableau on BI server. Certificate's CommonName or SANs must match bi_hostname. Certificate file must include end certificate plus intermediate cert(s) if exist(s).
vds_master_ssl_cert vds_master_ssl_key	vds_master.crt vds_master.key	Certificate and its private key files in pem format for AutoML Master server. Used by nginx and mesos on AutoML Master server. Certificate's CommonName or SANs must match vds_master_hostname. Certificate file must include end certificate plus intermediate cert(s) if exist(s).
vds_slave_ssl_cert vds_slave_ssl_key	vds_slave.crt vds_slave.key	Certificate and its private key files in pem format for AutoML Agent server(s). Used by mesos on AutoML Agent server(s). Certificate's CommonName or SANs must match ALL existing and planned hostnames of AutoML Agent(s). Certificate file must include end certificate plus intermediate cert(s) if exist(s).
ca_ssl_cert	CA.cert	Root CA certificate in pem format. All above certificates in this table must be signed by this Root CA. It is imported into Java Truststore on all servers. Certificate file must include only Root cert, without any intermediate certs.
Vault Certificates
vault_admin_cert_file	vault_admin.p12	Certificate and its private key in single p12 file. Used by Workfusion applications for authentication and access control into Vault (Secure Storage).
vault_workfusion_cert_file	vault_workfusion.p12	Certificate and its private key in single p12 file. Used by Workfusion applications for authentication and access control into Vault (Secure Storage).
vault_sandbox_cert_file	vault_sandbox.p12	Certificate and its private key in single p12 file. Used by Workfusion applications for authentication and access control into Vault (Secure Storage).

You have two options to install Workfusion SPA:

• Using your Trusted Certificates
• Using Self-Signed Certificates

Installation with Trusted Certificates

Example: Wildcard Trusted certificates

Prerequisites:

1. Hostnames of all your servers are in single domain. For example, you have the following hostnames in config.yml:

   db_hostname: db.example.com
   app_hostname: app.example.com
   ocr_hostname: ocr.example.com
   apm_hostname: apm.example.com
   bi_hostname: bi.example.com
   vds_master_hostname: automlmaster.example.com
   vds_slave_hostname: automlagent.example.com
   s3_hostname: app-s3.example.com
   

2. You got the following certificates from your SSL provider:

   ca.cert          ## contains ROOT CA certificate in pem format (the file may have .crt, .cer, .pem, or .cert extension)
   intermediate.crt ## contains intermediate CA certificate in pem format signed by ROOT CA certificate (the file may have .crt, .cer, .pem, or .cert extension)
   domain.crt       ## contains wildcard server certificate in pem format signed by intermediate CA certificate issued for wildcard CommonName *.example.com (the file may have .crt, .cer, .pem, or .cert extension)
   domain.key       ## contains private key file for domain.cer certificate in pem format (the file may have .key, or .pem extension). This file should have been generated initially with CSR.
   

Required actions are as follows:

1. Append intermediate.crt to the domain.crt certificate:

   cat intermediate.crt >> domain.crt
   

   important

   The order does matter. domain.crt must be the first. If you have several intermediate CA certs, you need to bundle all of them. Each subsequent intermediate cert added to the file must be signed by previous one. If you don't have any intermediate CA certs, you don't need this step.

2. Put your trusted certificates to <PACKAGE_DIR>/certificates directory on DB server with filenames specified in secrets.yml, for example:

Settings in secrets.yml	File names for Nginx certificates in "certificates/" directory
ca_ssl_cert: CA.cert apm_ssl_cert: apm.crt apm_ssl_key: apm.key app_ssl_cert: app.crt app_ssl_key: app.key db_ssl_cert: db.crt db_ssl_key: db.key ocr_ssl_cert: ocr.crt ocr_ssl_key: ocr.key bi_ssl_cert: bi.crt bi_ssl_key: bi.key vds_master_ssl_cert: vds_master.crt vds_master_ssl_key: vds_master.key vds_slave_ssl_cert: vds_slave.crt vds_slave_ssl_key: vds_slave.key	CA.cert apm.crt apm.key app.crt app.key db.crt db.key ocr.crt ocr.key bi.crt bi.key vds_master.crt vds_master.key vds_slave.crt vds_slave.key
ca_ssl_cert: CA.cert apm_ssl_cert: domain.crt apm_ssl_key: domain.key app_ssl_cert: domain.crt app_ssl_key: domain.key db_ssl_cert: domain.crt db_ssl_key: domain.key ocr_ssl_cert: domain.crt ocr_ssl_key: domain.key bi_ssl_cert: domain.crt bi_ssl_key: domain.key vds_master_ssl_cert: domain.crt vds_master_ssl_key: domain.key vds_slave_ssl_cert: domain.crt vds_slave_ssl_key: domain.key	CA.cert domain.crt domain.key

3. Generate VAULT certificates. Vault certificates must be generated using the generates-certificates.sh script:

   ./generate-certificates.sh cert-vault
   

   The command produces three additional certificates in the certificates directory:

Settings in secrets.yml	File names for Vault certificates in "certificates/" directory
vault_admin_cert_file: vault_admin.p12 vault_workfusion_cert_file: vault_workfusion.p12 vault_sandbox_cert_file: vault_sandbox.p12	vault_admin.p12 vault_sandbox.p12 vault_workfusion.p12

As a result you should have the following files in the <PACKAGE_DIR>/certificates directory:

## ls -la ./certificates/
total 88
-rw-r----- 1 root root 1793 Dec 10 05:59 apm.crt
-rw------- 1 root root 3272 Dec 10 05:59 apm.key
-rw-r----- 1 root root 1793 Dec 10 05:59 app.crt
-rw------- 1 root root 3272 Dec 10 05:59 app.key
-rw-r----- 1 root root 1793 Dec 10 05:59 bi.crt
-rw------- 1 root root 3272 Dec 10 05:59 bi.key
-rw-r----- 1 root root 1411 Dec 10 05:59 CA.cert
-rw-r----- 1 root root 1793 Dec 10 05:59 db.crt
-rw------- 1 root root 3272 Dec 10 05:59 db.key
-rw-r----- 1 root root 1793 Dec 10 05:59 ocr.crt
-rw------- 1 root root 3272 Dec 10 05:59 ocr.key
-rw-r----- 1 root root 2517 Dec 10 05:59 vault_admin.p12
-rw-r----- 1 root root 2517 Dec 10 05:59 vault_sandbox.p12
-rw-r----- 1 root root 2517 Dec 10 05:59 vault_workfusion.p12
-rw-r----- 1 root root 1793 Dec 10 05:59 vds_master.crt
-rw------- 1 root root 3272 Dec 10 05:59 vds_master.key
-rw-r----- 1 root root 1793 Dec 10 05:59 vds_slave.crt
-rw------- 1 root root 3272 Dec 10 05:59 vds_slave.key

What if you cannot provide wildcard certificate that matches all hostnames?

Such situation might happen if, for example, you have your own Certificate Authority in your organization which doesn't allow signing of wildcard certificates. In this case, you can:

• Generate a single certificate issued to one of the servers' hostnames, for example, CommonName=app_hostname. Put all other hostnames into certificate's Subject Alternative Names (SAN).
• Or generate separate certificates for each server.

note

If you are using non-wildcard separate certificates for each server, make sure that APP server's certificate is valid for both app_hostname and s3_hostname. For example, app.crt can be issued to app_hostname but it must have s3_hostname in its SAN.

Install with Self-Signed certificates

1. Set hostnames for all servers in config.yml.

2. Run the command:

   ./generate-certificates.sh cert-all
   

   This script will generate all certificates required for installation of Workfusion SPA: Nginx certificates and Vault certificates. Check that files exist in the <PACKAGE_DIR>/certificates directory.
   The script also generates CA.key, CA.srl, and openssl.cnf files. Do not delete these files. They might be required later if you want to generate and sign additional Nginx certificates.

Use generate-certificates.sh script

Three options are available:

./generate-certificates.sh cert-nginx     ## generates only Nginx certificates
./generate-certificates.sh cert-vault     ## generates only Vault certificates
./generate-certificates.sh cert-nginx     ## generates both - Nginx certificates and Vault certificates

The script will not generate a particular Nginx Certificate if a respective hostname is not set in config.yml. The script will not override the existing certificate if a file with the same name exists in the certificates directory.

If you need to generate an additional Nginx certificate for some server, for example, for BI server:

1. Specify bi_hostname in config.yml.
2. Ensure that ca_ssl_cert and ca_ssl_key files exist in the certificates directory, and ca_key_pass is valid.
3. Execute the ./generate-certificates.sh cert-nginx command.

If you want to generate vault certificates with new passwords:

1. Set the required value for Vault passwords in secrets.yml.
2. Remove Vault certificates from the certificates directory.
3. Run ./generate-certificates.sh cert-vault.

Attachments

app.key.url