Versions Compared

Old Version 47

changes.mady.by.user John McKeever

Saved on

compared with

New Version Current

changes.mady.by.user John McKeever

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

Creating a Java KeyStore and SSL certificate

MettleCI Workbench can be configured to expose ports over HTTP, HTTPS, or both simultaneously at separate ports. Before configuring Workbench to use HTTPS, a Java KeyStore containing the HTTPS certificate must be created first. Java KeyStores can be created and managed using the keytool command included with all installations of Java.

First ensure that you use the keytool command shipped with the Java v1.8 package you downloaded to support MettleCI. You can check which version of keytool is your command line’s line's default keytool by using the operating system-specific commands where keytool

Status
colourBlue
titleWindows
or which keytool
Status
colourYellow
titleUnix
. Verify that the response indicates that you will be using the keytool in the correct bin directory (e.g. in your OpenJDK installation).

Next, you’ll use a the keytool command with the following template (with a format like that show below) to create a keystore containing a basic KeyStore that contains a single, basic, self-signed certificate:

Code Block
languagebash
keytool -genkey -keyalg RSA -alias workbench -keystore <path-to-keystore> 
        -storepass <store-password> -storetype PKCS12 -keysize 2048 
        -sigalg SHA256withRSA -dname "CN=<host url>"
        -ext san=dns:engine.yourdomain.com<host url>
        -validity <days-valid>

Please Use the following table to replace the <placeholder-values> in this command based on the following descriptions:example command with values that are specific to your environment and policies.

Placeholder

Description

Example Value

path-to-keystore

Full qualified path of the key store to be created

/opt/dm/mci/workbench.p12 (Unix)

C:\dm\mci\workbench.p12 (Windows)

store-password

Password required when reading or writing to the newly created key store

Choose a random password string.

Note that the key stores supplied with Java have a default password of changeit.

host-url

The domain name of the URL that will be used to access Workbench in your browser. This does not include the protocol or port numbers. For example, dev-engine.datamigrators.com

your-engine.yourdomain.com

(no port number)

days-valid

The number of days for which the key should remain valid

Note that the key stores supplied with Java have a default validity of 180 days.

...

This example generates a key with a 36510-day year validity.

Code Block
languagebash
$> keytool -genkey -keyalg RSA -alias workbench -keystore workbench.p12 \
-storepass changeit -storetype PKCS12 -keysize 2048 \
-sigalg SHA256withRSA -dname "CN=my-engine.datamigrators.com" \
-ext san=dns:my-engine.datamigrators.com \
-validity 3650
Note

Note that in the example above you must ensure that both instances of engine.datamigrators.com is are replaced with the domain name of your DataStage engine, which you can get from . It is suggested that you use the Workbench URL to derive this (e.g. mydsengine.acmesandwichmakers.com).

...

Note that with the exception of keytool -list the keytool command will not normally return a value to the console .to indicate it has executed successfully

Regenerating keys

If you want to regenerate your keystore certificate for any reason (i.e. it has expired) you can use the following command:

Code Block
# Delete it
$> keytool -delete -noprompt -alias workbench  -keystore workbench.p12  -storepass changeit

# Verify it has been deleted 
$>  keytool -list -v -keystore  /opt/dm/mci/workbench.p12  -storetype PKCS12  -storepass changeit
Keystore type: PKCS12
Keystore provider: SunJSSE

Your keystore contains 0 entries
$>

...

Enabling HTTPS support in the MettleCI Workbench config.yml

Once a keystore containing the Workbench HTTPS certificate has been created, update your MettleCI config.yml file to add the following section:

...

Expand
titleUnix
Code Block
languageyaml
server:
  applicationConnectors:
    - type: https
      port: 8443
      keyStoreType: PKCS12
      keyStorePath: /opt/dm/mci/workbench.p12
      keyStorePassword: changeit
      trustStoreType: PKCS12
      trustStorePath: /opt/dm/mci/workbench.p12
      trustStorePassword: changeit

If you wish to allow Workbench to communicate over both HTTP and HTTPS protocols then you configure your config.yml like this:

Code Block
languageyaml
server:
  applicationConnectors:
    - type: http
      port: 8080
    - type: https
      port: 8443
      keyStoreType: PKCS12
      keyStorePath: /opt/dm/mci/workbench.p12
      keyStorePassword: changeit
      trustStoreType: PKCS12
      trustStorePath: /opt/dm/mci/workbench.p12
      trustStorePassword: changeit
Note

Ensure you use fully qualified references for your KeyStorePath and TrustStorePath as relative references will not work.

For example, instead of ./workbench.p12 use /opt/dm/mci/workbench.p12.

The ports given above are only examples, and you’re free to use custom port numbers as desired.

...

Verify Workbench is up and running under HTTP and/or HTTPS by navigating to https://<host url>:8443 and/or http://<host url>:8080 (as appropriate) in your browser.

Trusting your certificate

You will need your local browser to trust the certificate on your DataStage engine tier. There will be slightly different processes for this depending upon your chosen browser and whether or not you have self-signed the certificate or used a CA.

Inspecting your certificate

Typically, when you first connect to Workbench using HTTPS you will see a certificate error in your browser. This may look like this…

...

Once you’re happy that the thumbprint matches you can proceed to installing your certificate.

Installing your certificate

If Install Certificate is enabled then click it to install the certificate into the Trust Root Certification Authorities store

...

If Install Certificate is not enabled then select the Details tab in the Certificate dialog then click Copy to File.

...

  1. Start the Certificate Export Wizard by clicking Next, accept the default settings, enter a meaningful certificate name to export it to your local system, and click Finish. Now the certificate has been successfully exported to a file.

  2. In the Certificate Export Wizard success message, click Finish.

  3. In the Certificate dialog, click OK.

You can now follow your operating system’s process for importing the certificate file into the Trust Root Certification Authorities store.

...