Prerequisites

Before starting, ensure you have:

  • Clockspring installed and running (single-user mode is fine)

  • Root or sudo access to the server

  • The fully qualified domain name (FQDN) of your Clockspring server

  • The IP address of your Clockspring server

  • Access to a Certificate Authority (CA) to sign your certificate

If Clockspring already has a multi-user configuration, back up your conf/ directory before making changes.

Step 1: Create the Keystore

Become the clockspring user:

sudo su - clockspring

Change to the certificates directory (contains a default self-signed certificate):

cd /opt/clockspring/certificates

Generate a new Java keystore and private key. Replace <FQDN> with your server’s hostname and <IP_ADDRESS> with its IP:

keytool -genkey -keystore keystore.jks -storetype jks -alias clockspring-tls -keyalg RSA -sigalg SHA256withRSA -validity 365 -keysize 2048 -ext san=dns:<FQDN>,ip:<IP_ADDRESS>

Complete the prompts as shown below:

Enter keystore password:
Re-enter new password:
What is your first and last name?
  [Unknown]:  clockspring.example.com
What is the name of your organizational unit?
  [Unknown]:  IT
What is the name of your organization?
  [Unknown]:  Example Corp
What is the name of your City or Locality?
  [Unknown]:  New York
What is the name of your State or Province?
  [Unknown]:  NY
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=clockspring.example.com, OU=IT, O=Example Corp, L=New York, ST=NY, C=US correct?
  [no]:  yes
The "first and last name" field must be the exact FQDN of your Clockspring server.

Step 2: Generate Certificate Signing Request (CSR)

Generate a CSR to send to your Certificate Authority:

keytool -certreq -alias clockspring-tls -keystore keystore.jks -storetype jks -file clockspring.csr -ext san=dns:<FQDN>,ip:<IP_ADDRESS>

Submit clockspring.csr to your Certificate Authority and wait for the signed certificate to be returned.

Step 3: Install the Certificate

Once you receive the signed certificate from your CA, save it as clockspring.crt in /opt/clockspring/certificates/.

First, import the CA certificate chain. You’ll typically have a Root CA and Intermediate CA certificate:

cd /opt/clockspring/certificates
keytool -import -trustcacerts -alias rootCA -file rootCA.crt -keystore keystore.jks
keytool -import -trustcacerts -alias intermediateCA -file intermediateCA.crt -keystore keystore.jks

Verify the certificate chain is valid:

openssl verify -verbose -CAfile <(cat intermediateCA.crt rootCA.crt) clockspring.crt

Expected output:

clockspring.crt: OK

Import your signed certificate:

keytool -import -trustcacerts -alias clockspring-tls -file clockspring.crt -keystore keystore.jks

Step 4: Configure Clockspring

Edit /opt/clockspring/conf/clockspring.properties:

vi /opt/clockspring/conf/clockspring.properties

Update the security section with your keystore information:

nifi.security.keystore=./certificates/keystore.jks
nifi.security.keystoreType=JKS
nifi.security.keystorePasswd=YOUR_KEYSTORE_PASSWORD
nifi.security.keyPasswd=YOUR_KEY_PASSWORD

Step 5: Add CA Certificates to Operating System (Optional)

If your operating system doesn’t already trust your CA chain, add the certificates:

sudo dnf install ca-certificates
sudo update-ca-trust force-enable
sudo cp /opt/clockspring/certificates/rootCA.crt /opt/clockspring/certificates/intermediateCA.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust extract

Step 6: Apply Changes

Restart Clockspring to apply the SSL configuration:

sudo systemctl restart clockspring

Step 7: Verify SSL Configuration

Navigate to https://<clockspring_hostname>:8443/canvas in your browser. You should see a valid certificate from your CA.

The service may take a few minutes to start. If unreachable after 5 minutes, check the logs in /opt/clockspring/logs/.

Troubleshooting

"Certificate chain not valid" error during verification

  • Ensure you imported the CA certificates in the correct order (root first, then intermediate)

  • Verify the certificate files are not corrupted

  • Check that the signed certificate matches the CSR you submitted

Browser shows certificate warning

  • Verify the FQDN in the certificate matches the URL you’re accessing

  • Ensure the CA certificates are installed in your browser’s trust store or the operating system’s trust store

  • Check that the certificate hasn’t expired

Clockspring fails to start after SSL configuration

Check the logs for specific errors:

tail -100 logs/application.log

Common issues:

  • Wrong keystore password: Verify the password in clockspring.properties matches what you set during keystore creation

  • Missing certificate: Ensure all certificates were imported to the keystore

  • Key alias mismatch: The alias used during import must match clockspring-tls

"Keystore was tampered with, or password was incorrect"

This usually means the keystore password is wrong. Re-create the keystore if you’ve forgotten the password.

Certificate works but shows as "not trusted"

The CA chain is incomplete. Import any missing intermediate certificates:

keytool -list -keystore keystore.jks -v

Review the certificate chain and ensure all intermediate CAs are present.

SSL Property Reference

Property Description

nifi.security.keystore

Path to the Java keystore containing the server certificate

nifi.security.keystoreType

Keystore format: JKS or PKCS12

nifi.security.keystorePasswd

Password for the keystore

nifi.security.keyPasswd

Password for the private key (often same as keystore password)

nifi.security.truststore

Path to truststore for client certificate validation (optional)

nifi.security.truststoreType

Truststore format: JKS or PKCS12

nifi.security.truststorePasswd

Password for the truststore