Products

Automation Analytics & Intelligence

Issue/Introduction

How do I setup AAI to use HTTPS?

Environment

Release : 6.0

Component : AUTOMIC AUTOMATION INTELLIGENCE ENGINE

Resolution

If you have an existing keystore file or certificate see below, otherwise skip to "Generating a Self-Signed Certificate Keystore File on the JAWS server"

If you already have a keystore copy your keystore file (ie. .jks file) to the <JAWS_HOME>\jboss\standalone\configuration directory and skip to the "Update AAI/JAWS configuration" section of the document.

If you have a signed a CA Signed certificate file, you would need to import it into a keystore file like jawskey, which you can create in <JAWS_HOME>\jboss\standalone\configuration directory and then you can skip to the "Update AAI/JAWS configuration" section of this document.
- You can use keytool to import your certificate file into the keystore file you created by running:

keytool -import -v -file filename.cer -keystore /opt/aai/jboss/standalone/configuration/jawskey -storepass changeit -noprompt

Generating a Self-Signed Certificate Keystore File on the JAWS server

The JAWS application requires access to a keystore file containing the certificate and key to be used. This example will provide details on using a self-signed certificate.

Generating a key and keystore

To create the keystore file, log into the AAI/JAWS server as the same user that is used to start and stop the JAWS application.

NOTES:

The JAVA_HOME environment variable should be set to the root of a Java JDK install (e.g. /usr/java/jdk1.8.0_141).
When prompted for first and last name, enter the hostname of the AAI/JAWS server. This should be the same hostname used for launching the JAWS client via a web browser (e.g. https://<hostname>8080/jaws or https://<hostname.domain.com>/jaws where <hostname> or <hostname.domain.com> is the hostname or FQDN of the server.
Replace <JAWS_HOME> in each of the commands with the root path of the AAI/JAWS installation.
SAN is the "Subject Alternative Name" and is now required by Chrome and other browsers. This allows for additional host names (sites, IP addresses, common names, etc.) to be used in a certificate. In the example below, we are using the hostname, Fully Qualified Domain Name, and IP address. The host name should match the exact host name for the JAWS application server.

Linux Command

$JAVA_HOME/bin/keytool -genkey -alias jawsserver -keyalg RSA -keystore <JAWS_HOME>/jboss/standalone/configuration/jaws.keystore -ext SAN=dns:<hostname>,dns:<hostname.domain.com>,ip:<ip address> -validity 3650

Windows Command

%JAVA_HOME%\bin\keytool -genkey -alias jawsserver -keyalg RSA -keystore <JAWS_HOME>\jboss\standalone\configuration\jaws.keystore -ext SAN=dns:<hostname>,dns:<hostname.domain.com>,ip:<ip address> -validity 3650

Sample Input

Enter keystore password: changeit

Re-enter new password: changeit

What is your first and last name?

[Unknown]: <hostname>

What is the name of your organizational unit?

[Unknown]: Broadcom

What is the name of your organization?

[Unknown]: Broadcom

What is the name of your City or Locality?

[Unknown]: Boulder

What is the name of your State or Province?

[Unknown]: CO

What is the two-letter country code for this unit?

[Unknown]: US

Is CN= <hostname>, OU=Broadcom, O=Broadcom, L=Boulder, ST=CO, C=US correct?

[no]: yes

Enter key password for <jawsserver>

(RETURN if same as keystore password):

Verifying the keystore file

You will be prompted for a password when running the verification commands below. Enter the key password. If the keystore file is valid, you will be presented with a certificate and key.

NOTE: Replace <JAWS_HOME> in each of the commands with the root path of the JAWS installation.

Linux Command

$JAVA_HOME/bin/keytool -list -v -keystore <JAWS_HOME>/jboss/standalone/configuration/jaws.keystore -alias jawsserver

Windows Command

%JAVA_HOME%\bin\keytool -list -v -keystore <JAWS_HOME>\jboss\standalone\configuration\jaws.keystore -alias jawsserver

Update AAI/JAWS configuration

The following steps are the same for both UNIX and Windows environments. The ‘/’ will be used for Linux and ‘\’ for Windows in all paths.

Modifying the <JAWS_HOME>/jboss/standalone/configuration/standalone.xml file

Four changes will be required in this file to enable https with TLS. The exact changes in each are highlighted in red bold.

NOTE: It is recommended that you save a copy of the original file as a backup before beginning modifications.

COPY standalone.fresh to standalone.xml

1. Enabling TLS protocol

The TLS protocol is disabled by default. To enable the TLS protocol, you must uncomment the TLS protocol section.

Locate the following section within the security-realm name="ApplicationRealm" and not the "ClientCertRealm"

<security-realm name="ApplicationRealm">
<plug-ins>
<plug-in module="com.termalabs.server.authentication"/>
</plug-ins>
<authentication>
<plug-in name="JawsAuthPlugIn"/>
</authentication>

<!--<server-identities>

</ssl>

</server-identities>-->

Replace with:

<security-realm name="ApplicationRealm">
<plug-ins>
<plug-in module="com.termalabs.server.authentication"/>
</plug-ins>
<authentication>
<plug-in name="JawsAuthPlugIn"/>
</authentication>

<server-identities>

</ssl>

</server-identities>

2. Modifying the keystore path and password

These should be the values from the Keystore section of this document:

NOTE: The keystore path is relative to the jboss/standalone/configuration directory or folder. If the keystore file was placed in jboss/standalone/configuration, it will be the simple name of the keystore file.

<security-realm name="ApplicationRealm">
<plug-ins>
<plug-in module="com.termalabs.server.authentication"/>
</plug-ins>
<authentication>
<plug-in name="JawsAuthPlugIn"/>
</authentication>

<server-identities>

</ssl>

</server-identities>

3. Enabling the https connector

The http connector is enabled by default. To disable the http connector and enable the https connector, you must comment out the http connector and uncomment the https connector.

Locate the following section:

<http-connector name="http-remoting-connector" connector-ref="http" security-realm="ApplicationRealm"/>

</subsystem>

Replace with:

<http-connector name="http-remoting-connector" connector-ref="https" security-realm="ApplicationRealm"/>

</subsystem>

4. Enabling the socket-binding listener for https

The server is set up to listen on the http port by default. To change to the https port, the listener for the http port must be commented out and the comments removed for the https port.

Locate the following section:

<http-listener name="http" socket-binding="http" redirect-socket="https"/>

<filter-ref name="server-header"/>

<filter-ref name="x-powered-by-header"/>

</host>

</server>

Replace with:

<https-listener name="https" socket-binding="https" security-realm="ApplicationRealm"/>

<filter-ref name="server-header"/>

<filter-ref name="x-powered-by-header"/>

</host>

</server>

Restart the AAI/JAWS application

Changes will not take effect until the JAWS application has been restarted.

Launch the AAI/JAWS client from a web browser

Users should now be able to launch the JAWS client using https with TLS by entering one of the following URLs into the address bar of a web browser.

NOTE: Replace <JAWS_SERVER> in the following URLs with the correct hostname for your environment.

https://<JAWS_SERVER>:8443/terma

https://<JAWS_SERVER>:8443/jaws This URL will be going away in the near future and replaced with the above.

Add the Public Key Certificate to the JAWS client

When using a self-signed certificate, Java Web Start may display a security warning like shown below and block access to the JAWS client because it does not recognize the owner of the certificate.

A Public Key Certificate can be added to the list of Trusted Certificates on the client machine to allow access and remove the warning.

Exporting the Public Key Certificate on the JAWS server

NOTES:

Replace <JAWS_HOME> in each of the commands with the root path of the JAWS installation.
Choose a filename to save the exported certificate in (e.g. FileName.cer). The extension needs to be ".cer"
When prompted, enter the password used to generate the keystore file.

Linux Command

$JAVA_HOME/bin/keytool -export -keystore <JAWS_HOME>/jboss/standalone/configuration/jaws.keystore -alias jawsserver -file FileName.cer

Windows Command

%JAVA_HOME%\bin\keytool -export -keystore <JAWS_HOME>\jboss\standalone\configuration\jaws.keystore -alias jawsserver -file FileName.cer

Importing the Certificate as a Trusted Certificate on the Client

The following update may be required on each client machine that will require access to the JAWS server.

Linux Command

/usr/java/jre1.8.0_141/bin/keytool -importcert -file FileName.cer -keystore /usr/java/jre1.8.0_141/lib/security/cacerts -alias jawsserver

Windows Command

Run mmc.exe from the Start menu on the client
Click File then click Add/Remove Snap-in
Choose Certificates from the list then click Add
In the Certificates snap-in pop-up window, select Computer Account then click Next
In the Select Computer pop-up window, select Local Computer then click Finish
Click OK to confirm Certificates (Local Computer) snap-in
Expand Certificates, expand Trusted Root Certification Authorities
Right-click Certificates, click All Tasks, and then click Import
On the Certificate Import Wizard Welcome page, click Next
Browse to the location of the saved certificate file, select the file and then click Open
Select Next
In the Certificate Store, select Place all certificates in the following store and choose Trusted Root Certification Authorities
Select Next then Finish
Restart all browsers

Secure access from the CLI

Using https with TLS for the CLI requires some awareness of trusted certificates. The following changes will allow https with TLS access through the CLI.

All scripts should use the login_with_params() function found in batch/lib/params.py.

Updating the path to the keystore file

NOTE: Replace <JAWS_HOME> in each of the entries below with the root path of the JAWS installation.

Make a copy of <JAWS_HOME>/batch/lib/jaws_ssl.py as a backup
Edit <JAWS_HOME>/batch/lib/jaws_ssl.py
Uncomment and update the trustStoreLocation with the full path to the keystore. Make sure there are no blank spaces at the beginning of the line.
Uncomment and update the password. Make sure there are no blank spaces at the beginning of the line.

Command line options to use

All CLI scripts should use the login_with_params() function found in batch/lib/params.py rather than login().

The following command line options will be required for https with TLS access.

-port 8443
-protocol https

Example command line

./run.pl examples/system_check.py -server <serverName> -port 8443 -user admin -password password -protocol https

Using TLS with Subscription Services (5.7+)

The Subscription Services process within JAWS may fail to deploy when the JAWS server is configured for TLS only using an untrusted certificate. This issue can be detected by an error similar to the following found in the server.log file during initialization.

2018-12-27 11:12:02,021 INFO [org.jboss.as.server.deployment.scanner.FileSystemDeploymentService] WFLYDS0015: Re-attempting failed deployment subscriptionService.war

2018-12-27 11:12:04,851 INFO [org.jboss.as.server.operations.HttpManagementAddHandler] WFLYSRV0039: Creating http management service using socket-binding (management-http)

The issue can be resolved by inserting the enterprise-signed certificate authority into the Java keystore.

Importing the Certificate as a Trusted Certificate into the Java keystore

NOTES:

The JAVA_HOME environment variable should be set to the root of a Java JDK install (e.g. /usr/java/jdk1.8.0_141).
Replace <JAWS_HOME> in the following commands with the root path of the JAWS installation.
The location of the srckeystore is the same as specified in the Generate a Self-Signed Certificate Keystore File on the JAWS server section of the document.

The -destkeystore location and file must be the one that JAVA is using for the JVM. This is generally the cacerts file found in the lib/security folder of the Java install directory (e.g. /usr/java/jdk1.8.0_141/jre/lib/security).
The default password for cacerts is usually changeit.
The following command may need to be run as root or Administrator.

Linux Command

$JAVA_HOME/bin/keytool -importkeystore -srckeystore <JAWS_HOME>/jboss/standalone/configuration/jaws.keystore -destkeystore $JAVA_HOME/jre/lib/security/cacerts

Windows Command

%JAVA_HOME%\bin\keytool -importkeystore -srckeystore <JAWS_HOME>\jboss\standalone\configuration\jaws.keystore –destkeystore %JAVA_HOME%\jre\lib\security\cacerts

There will be prompts by the keytool command for the destination and source passwords. The destination should be changeit unless modified by the System Adminstrator. The source password will be the same as was set up in Generate a Self-Signed Certificate Keystore File on the JAWS server.

Restart the AAI/JAWS application

Changes will not take effect until the JAWS application has been restarted.

Potential Errors and Warnings

If an error similar to the following appears in the server.log file during a startup, it indicates that an incorrect DNS name was specified when the self-signed certificate was created. The Generate a Self-Signed Certificate Keystore File on the JAWS server steps will need to be run again with the correct “Subject Alternative Name”. All subsequent steps to export/import the certificate to other cert files will need to be re-applied.

I/O error on GET request for "https://servername.domain.com:8443/jaws/api/properties/serverParam/subscription.httpReadTimeout":

Certificate for <sservername.domain.com> doesn't match any of the subject alternative names: [serverName.termalabs.com, 192.168.1.1];

JAWS Export/Import

No additional configuration changes are required to use SSL/TLS with the JAWS Export/Import tools. The only changes required are additional parameters on the command line.

From a command prompt on the JAWS server, change to the <JAWS_HOME>/import_export/bin directory (Linux) or <JAWS_HOME>\import_export\bin folder (Windows).

Linux Command

./jawsExport.sh -e filename_export.xml -user admin -password password -server serverName:8443 –https

Windows Command

jawsExport.bat -e filename_export.xml -user admin -password password -server serverName:8443 –https

TLS Connection to SMTP server

Additional Information

When accessing the Terma website you should be using the hostname, FQDN, or IP address specified when creating the self signed certificates, or the hostname in the Subject or Subject Alternative Name fields in the certificate.

For setting up Insight with HTTPS please see this article: How do I setup HTTPS for Insight so that it can be used within AAI?

How do I setup AAI/JAWS to use HTTPS?

Article ID: 191576

Updated On:

Products

Issue/Introduction

Environment

Resolution

If you have an existing keystore file or certificate see below, otherwise skip to "Generating a Self-Signed Certificate Keystore File on the JAWS server"

Generating a Self-Signed Certificate Keystore File on the JAWS server

Generating a key and keystore

Linux Command

Windows Command

Verifying the keystore file

Linux Command

Windows Command

Update AAI/JAWS configuration

Modifying the <JAWS_HOME>/jboss/standalone/configuration/standalone.xml file

1. Enabling TLS protocol

Replace with:

2. Modifying the keystore path and password

3. Enabling the https connector

Locate the following section:

Replace with:

4. Enabling the socket-binding listener for https

Locate the following section:

Replace with:

Restart the AAI/JAWS application

Launch the AAI/JAWS client from a web browser

Add the Public Key Certificate to the JAWS client

Exporting the Public Key Certificate on the JAWS server

Linux Command

Windows Command

Importing the Certificate as a Trusted Certificate on the Client

Linux Command

Windows Command

Secure access from the CLI

Updating the path to the keystore file

Command line options to use

Example command line

Using TLS with Subscription Services (5.7+)

Importing the Certificate as a Trusted Certificate into the Java keystore

Linux Command

Windows Command

Restart the AAI/JAWS application

Potential Errors and Warnings

JAWS Export/Import

Linux Command

Windows Command

TLS Connection to SMTP server

Additional Information

Feedback