To secure communications with the services, WorkFusion platform uses several x509 certificates. In the current version only few services are TLS enabled, but it is enough to secure most of the traffic.

Current concept

There are three types of the certificates used during setup. They can be grouped according to their functions:

The first group is the web server certificates (below Server-certs), which are used to encrypt communications with the frontend and the end user.
The second group is the TLS client certificates (below Client-certs), which are used during the two-way authentication.
The third group is the Vault related certificates.

The certificates should strictly match to DNS in common name or SAN (Subject Alternative Name).

Hostnames

Certificate common names match to DNS hostnames as defined in config.yml.

certificate/key name (secret.yml)	default file names	hostname variable (config.yml)	certificate format	note
apm_ssl_cert apm_ssl_key	apm.crt apm.key	apm_hostname:	crt(pem)	Include end certificate plus intermediate(s).
app_ssl_cert: app_ssl_key:	app.crt app.key	app_hostname:	crt(pem)	Include end certificate plus intermediate(s).
db_ssl_cert: db_ssl_key:	db.crt db.key	db_hostname:	crt(pem)	should include a wildcard to 3th level domain, for example, *.db_hostname domain
ocr_ssl_cert: ocr_ssl_key:	ocr.crt ocr.key	ocr_hostname:	crt(pem)	Include end certificate plus intermediate(s).
vds_master_ssl_cert: vds_master_ssl_key:	vds_master.crt vds_master.key	vds_master_hostname:	crt(pem)	Include end certificate plus intermediate(s).
vds_slave_ssl_cert: vds_slave_ssl_key:	vds_slave.crt vds_slave.key	vds_slave_hostname:	crt(pem)	Include end certificate plus intermediate(s). wildcard can be used.
vault_admin_cert_file:	vault_admin.p12		p12
vault_workfusion_cert_file:	vault_workfusion.p12		p12
vault_sandbox_cert_file:	vault_sandbox.p12		p12
vault_host_cert_file:	vault_host.p12		p12
ca_ssl_cert:	CA.cert		crt(pem)	intermediate/selfSign certificate. Include ONLY ROOT certificate

note

Double-check that your CA file is placed into the certificates/ directory and named according to configuration in secret.yml, (default ca_ssl_cert:CA.cert) before you start the installation, as it can produce errors with the java trust store later.

Solution 1: Trusted certificates

This approach is intended to use the Trusted Certificates signed by trusted intermediate CA or directly by ROOT CA. For self-signed certificates see Solution 2.

For versions 8.5+ prior to Installer Version 9.0.0.7 you should place the entire certificate chain in PEM format to the certificate/CA.cert file. Since Installer Version 9.0.0.8, TLS certificates preparing procedure changed:

CA.cert must contain only ROOT certificate.
Application certificates (db, app, apm, ocr, vds_master, vds_slave) must contain end certificate in first place and then all intermediate certificates if they are exist to complete chain with ROOT certificate.

EXAMPLE wilcard certificate with intermediate CA for Installer Version 9.0.0.8+

Let assume that you need to setup SSL for hostnames *.example.com, you already defined hostnames in config.yml:

apm_hostname: apm.example.com
db_hostname: db.example.com
app_hostname: app.example.com
ocr_hostname: ocr.example.com
vds_master_hostname: vds-master.example.com
vds_slave_hostname: vds-slave.example.com

You got next certificates from your SSL provider:

ca.cer contains ROOT CA certificate.
intermediate.cer contains intermediate certificate signed by ROOT CA certificate.
domain.cer is a wildcard certificate for *.example.com.
domain.key contains private key for domain.cer.

Required actions:

Concatenate intermediate.cer and domain.cer into the one file.
```
cat domain.cer intermediate.cer > fullchain.cer
```
caution

Order does matter. Content of the domain.cer file must be on top of resulting fullchain.cer.

Copy certificates to the installation folder:

cp ca.cer certificates/CA.cert

cp fullchain.cer certificates/db.crt
cp domain.key certificates/db.key

cp fullchain.cer certificates/app.crt
cp domain.key certificates/app.key

cp fullchain.cer certificates/apm.crt
cp domain.key certificates/apm.key

cp fullchain.cer certificates/ocr.crt
cp domain.key certificates/ocr.key

cp fullchain.cer certificates/vds-master.crt
cp domain.key certificates/vds-master.key

cp fullchain.cer certificates/vds-slave.crt
cp domain.key certificates/vds-slave.key

./generate-certificates.sh -n -d -p "my_ca_pass"

Generate VAULT certificates using the procedure described below.

EXAMPLE wilcard certificate without intermediate CA for Installer Version 9.0.0.8+

Let assume that you need to setup SSL for hostnames *.example.com, you already defined hostnames in config.yml:

apm_hostname: apm.example.com
db_hostname: db.example.com
app_hostname: app.example.com
ocr_hostname: ocr.example.com
vds_master_hostname: vds-master.example.com
vds_slave_hostname: vds-slave.example.com

You got next certificates from your SSL provider:

ca.cer contains ROOT CA certificate.
domain.cer is a wildcard certificate for *.example.com signed by ROOT CA certificate.
domain.key contains private key for domain.cer.

Required actions:

Copy certificates to the installation folder:

cp ca.cer certificates/CA.cert

cp domain.cer certificates/db.crt
cp domain.key certificates/db.key

cp domain.cer certificates/app.crt
cp domain.key certificates/app.key

cp domain.cer certificates/apm.crt
cp domain.key certificates/apm.key

cp domain.cer certificates/ocr.crt
cp domain.key certificates/ocr.key

cp domain.cer certificates/vds-master.crt
cp domain.key certificates/vds-master.key

cp domain.cer certificates/vds-slave.crt
cp domain.key certificates/vds-slave.key

Generate VAULT certificates:

./generate-certificates.sh -n -d -p "my_ca_pass"

Generate VAULT certificates using the procedure described below.

Solution 2: Self-signed certificates

The approach is intended to use self-signed certificates signed by an untrusted CA, for example, self-signed certificate authority.

Certificates can be generated automatically by generate-certificates.sh or manually.

EXAMPLE 1 Generate certificates automatically with generate-certificates.sh

Generate TLS and Vault Certificates for all servers:

./generate-certificates.sh -n -d -p "my_ca_pass"

After running this command, two folders are populated with certificates: ./certificates and ./certs_db.

For more information about generate-certificates.sh, use the onscreen help:

[root@]# ./generate-certificates.sh -h
Found previous settings, disable interactive mode

Generate self-signed CA and required hosts certificates
Usage: ./generate-certificates.sh [-h] [-d] [-n|g] [-v] (Certificate flags)

Required flags:
There are no required flags

Optional flags:
-d : don't modify, for example, use default subject values. Should be never used alone
-n : Do not start gui to ask values
-g : Do start gui and ask values
-v : Increase output verbosity level

-a : Specify desirable CA name
-r : Regenerate hosts certificates, implies don't modify
-p : Specify password for CA key. This allows to generate not existing certs and sign them

Certificate flags:
-a CAname : specify Certificate Authority name
-z Sign request : specify Omit creating a certificate sign request
-g CA Certificate validity : specify CA Certificate validity (days)
-j Certificate validity : specify Certificate validity (days)
-c Country : specify country (2 letter)
-s State/Province : specify state or province
-l Location_Name : specify location name
-o organization : specify organization name
-u organizationalUnit : specify Organizational Unit name
-e emailAddress : specify email Address
-w Wildcard vds : specify Make a wildcard subject for vds slave

EXAMPLE 2 Generate certificates manually

In this case, you create your own PKI solution and sign the certificates there.

Create openssl caconf.cnf, save it to the certs_db folder.

certs_db/caconf.cnf

# This definition stops the following lines choking if HOME isn't
# defined.
HOME                    = .
RANDFILE                = $ENV::HOME/.rnd

# Extra OBJECT IDENTIFIER info:
#oid_file               = $ENV::HOME/.oid
oid_section             = new_oids

# To use this configuration file with the "-extfile" option of the
# "openssl x509" utility, name here the section containing the
# X.509v3 extensions to use:
# extensions            =
# (Alternatively, use a configuration file that has only
# X.509v3 extensions in its main [= default] section.)

[ new_oids ]

# We can add new OIDs in here for use by 'ca', 'req' and 'ts'.
# Add a simple OID like this:
# testoid1=1.2.3.4
# Or use config file substitution like this:
# testoid2=${testoid1}.5.6

# Policies used by the TSA examples.
tsa_policy1 = 1.2.3.4.1
tsa_policy2 = 1.2.3.4.5.6
tsa_policy3 = 1.2.3.4.5.7

####################################################################
[ ca ]
default_ca      = CA_wfs_ca

####################################################################
[ CA_wfs_ca ]

dir                             = /Data/WFP/Installer/develop/flat/installer/certs_db
certs                       = $dir/
crl_dir                     = $dir/crl
database                    = $dir/index.txt
new_certs_dir           = /Data/WFP/Installer/develop/flat/installer/certs_db
certificate                 = $dir/wfs_ca.crt
private_key                 = $dir/wfs_ca.key
RANDFILE                    = $dir/private/.rand
serial                      = $dir/serial
crlnumber                   = $dir/crlnumber
crl                             = $dir/crl.pem
x509_extensions         = usr_cert

# Comment out the following two lines for the "traditional"
# (and highly broken) format.
name_opt                    = ca_default                # Subject Name options
cert_opt                    = ca_default                # Certificate field options

# Extension copying option: use with caution.
# copy_extensions = copy

# Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs
# so this is commented out by default to leave a V1 CRL.
# crlnumber must also be commented out to leave a V1 CRL.
# crl_extensions        = crl_ext

default_days            = 3650                  # how long to certify for
default_crl_days        = 30                    # how long before next CRL
default_md                  = default           # use public key default MD
preserve                    = no                        # keep passed DN ordering

# A few difference way of specifying how similar the request should look
# For type CA, the listed attributes must be the same, and the optional
# and supplied fields are just that :-)
policy                      = policy_match
email_in_dn             = no                    # Don't add the email into cert DN

# For the CA policy
[ policy_match ]
countryName                     = match
stateOrProvinceName         = match
organizationName            = match
organizationalUnitName  = optional
commonName                      = supplied
emailAddress                = supplied

# For the 'anything' policy
# At this point in time, you must list all acceptable 'object'
# types.
[ policy_anything ]
countryName                     = optional
stateOrProvinceName         = optional
localityName                = optional
organizationName            = optional
organizationalUnitName  = optional
commonName                      = supplied
emailAddress                = optional

####################################################################
[ req ]
default_bits            = 4096
default_keyfile         = privkey.pem
default_md          = sha512
distinguished_name      = req_distinguished_name
attributes                  = req_attributes
x509_extensions     = req_ssign_ca      # The extensions to add to the self signed cert
req_extensions      = req_ca
# This sets a mask for permitted string types. There are several options.
# default: PrintableString, T61String, BMPString.
# pkix   : PrintableString, BMPString (PKIX recommendation before 2004)
# utf8only: only UTF8Strings (PKIX recommendation after 2004).
# nombstr : PrintableString, T61String (no BMPStrings or UTF8Strings).
# MASK:XXXX a literal mask value.
# WARNING: ancient versions of Netscape crash on BMPStrings or UTF8Strings.
string_mask         = MASK:0x2002

####################################################################
[ req_distinguished_name ]
countryName                             = Country Name (2 letter code)
countryName_default                 = US
countryName_min                     = 2
countryName_max                     = 2

stateOrProvinceName                 = State or Province Name (full name)
stateOrProvinceName_default     = NY

localityName                        = Locality Name (eg, city)
localityName_default        = NY

0.organizationName                  = Organization Name (eg, company)
0.organizationName_default      = workfusion

organizationalUnitName          = Organizational Unit Name (eg, section)
organizationalUnitName_default  = ops

commonName                              = Common Name (e.g. server FQDN or YOUR name)
commonName_max                      = 64

emailAddress                        = Email Address
emailAddress_max                    = 64
emailAddress_default        = ops@workfusion.com

[ req_attributes ]
challengePassword                   = A challenge password
challengePassword_min           = 4
challengePassword_max           = 20

unstructuredName                    = An optional company name

[ req_ca ]
# Extensions for a typical CA
# PKIX recommendation.
basicConstraints       = critical,CA:true,pathlen:0
subjectKeyIdentifier   = hash
# authorityKeyIdentifier = keyid:always,issuer:always
# authorityKeyIdentifier = keyid,issuer
keyUsage               = cRLSign, keyCertSign
nsCertType             = sslCA

[ req_ssign_ca ]
# Extensions for a typical CA
# PKIX recommendation.
basicConstraints       = critical,CA:true,pathlen:0
subjectKeyIdentifier   = hash
# authorityKeyIdentifier = keyid:always,issuer:always
# authorityKeyIdentifier = keyid,issuer
keyUsage               = cRLSign, keyCertSign
nsCertType             = sslCA

[ req_server ]
# Extensions to add to a certificate request
basicConstraints     = critical,CA:false
keyUsage             = nonRepudiation, digitalSignature, keyEncipherment
subjectKeyIdentifier = hash
subjectAltName       = $ENV::ALTNAME
nsCertType           = server

[ req_client ]
# Extensions to add to a certificate request
basicConstraints     = critical,CA:false
keyUsage             = dataEncipherment, digitalSignature, keyEncipherment
subjectKeyIdentifier = hash
subjectAltName       = $ENV::ALTNAME
nsCertType           = client, email

[ crl_ext ]
# CRL extensions.
# Only issuerAltName and authorityKeyIdentifier make any sense in a CRL.
# issuerAltName=issuer:copy
authorityKeyIdentifier=keyid:always

Define and provide CA key password via the PASSPHRASE environment variable.
Export PASSPHRASE=changeMePass.
Create and sign the CA certificate.

Generate the self-signed CA certificate. Make sure that permissions are set to reasonable defaults.

openssl req -new -x509 -days 3650 -extensions req_ssign_ca -reqexts req_ssign_ca\
    -out wfs_ca.crt -key wfs_ca.key \
    -subj "/C=Country_Name/ST=State_Name/O=Org_Name/localityName=Locality_Name/commonName=CAcert/organizationalUnitName=OrgUnitName" \ 
    -passin env:PASSPHRASE -config certs_db/caconf.cnf

chmod 0644 wfs_ca.crt
chmod 0400 wfs_ca.key

Generate and sign the server-certificate requests.

Repeat the procedure for each hostname defined.

Example for db-server with hostname db.mydomain.com:

openssl req -new -days 365 -out db.crt.csr -keyout db.key -nodes -config ./caconf.cnf\
    -subj "/C=Country_Name/ST=State_Name/O=Org_Name/localityName=Locality_Name/commonName=*.db.mydomain.com/organizationalUnitName=OrgUnitName/emailAddress=ops@mydomain.com"\
    -reqexts req_server
openssl x509 -req -in db.crt.csr -out db.crt -days 365 -CA ./wfs_ca.crt -CAkey ./wfs_ca.key\
    -CAcreateserial -passin env:PASSPHRASE -extensions req_server -extfile ./caconf.cnf
chmod 0644 db.crt
chmod 0644 db.key

Example for app-server with hostname app.mydomain.com:

openssl req -new -days 365 -out app.crt.csr -keyout app.key -nodes -config ./caconf.cnf\
    -subj "/C=Country_Name/ST=State_Name/O=Org_Name/localityName=Locality_Name/commonName=*.app.mydomain.com/organizationalUnitName=OrgUnitName/emailAddress=ops@mydomain.com"\
    -reqexts req_server
openssl x509 -req -in app.crt.csr -out app.crt -days 365 -CA ./wfs_ca.crt -CAkey ./wfs_ca.key\
    -CAcreateserial -passin env:PASSPHRASE -extensions req_server -extfile ./caconf.cnf
chmod 0644 app.crt
chmod 0644 app.key


cp ./app.crt  ../certificates/
cp ./app.crt.csr  ../certificates/
cp ./app.key  ../certificates/

Copy the CA certificate:

cp ./wfs_ca.crt ../certificates/CA.cert

Distribute the CA certificate.

Ensure that you import the intermediate certificate to each component and workplace that interacts with the WorkFusion platform. Refer to an example for a Microsoft Windows workplace in Import Root or Intermediate CA to Store.

Generate Vault certificates manually

To start Vault it is necessary to provide four certificate/key pairs in P12 format.

Certificates can be generated automatically with generate-certificates.sh.

Copy x509 Server-certs and x509 Client-certs files in P12 format to the certificates directory and edit the secrets.yml file to match the filenames before starting the installation. The examples below assume that the pass is specified in the command line. Execute them in the certs_db directory.

vault_host:

openssl req -new -x509 -days 3650 -out vault_host.cert -keyout vault_host.key -passout pass:vault_cert_host_passwd -subj /C=US/ST=NY/O=workfusion/localityName=NU/commonName=host/organizationalUnitName=ops/
openssl pkcs12 -export -in vault_host.cert -inkey vault_host.key -out vault_host.p12 -passin pass:vault_cert_host_passwd -password pass:vault_cert_host_passwd

vault_admin:

openssl req -new -x509 -days 3650 -out vault_admin.cert -keyout vault_admin.key -passout pass:vault_adm_cert_vault_passwd -subj /C=US/ST=NY/O=workfusion/localityName=NU/commonName=admin/organizationalUnitName=ops/
openssl pkcs12 -export -in vault_admin.cert -inkey vault_admin.key -out vault_admin.p12 -passin pass:vault_adm_cert_vault_passwd -password pass:vault_adm_cert_vault_passwd

vault_workfusion:

openssl req -new -x509 -days 3650 -out vault_workfusion.cert -keyout vault_workfusion.key -passout pass:vault_cert_wfvault_passwd -subj /C=US/ST=NY/O=workfusion/localityName=NU/commonName=workfusion/organizationalUnitName=ops/
openssl pkcs12 -export -in vault_workfusion.cert -inkey vault_workfusion.key -out vault_workfusion.p12 -passin pass:vault_cert_wfvault_passwd -password pass:vault_cert_wfvault_passwd

vault_sandbox:

openssl req -new -x509 -days 3650 -out vault_sandbox.cert -keyout vault_sandbox.key -passout pass:vault_cert_wfsndboxvault_passwd -subj /C=US/ST=NY/O=workfusion/localityName=NU/commonName=sandbox/organizationalUnitName=ops/
openssl pkcs12 -export -in vault_sandbox.cert -inkey vault_sandbox.key -out vault_sandbox.p12 -passin pass:vault_cert_wfsndboxvault_passwd -password pass:vault_cert_wfsndboxvault_passwd

copy certificates:

cp ./vault_*.p12 ../certificates/

WorkFusion Documentation

9.1

Preinstall steps

Installation steps

Post-installation steps

Appendix

General information

APP

DB

OCR

VDS

Single sign-on

Platform Monitor overview

Platform Monitor configuration

Platform Monitor for RPA

Using TLS Certificates