How do I setup AAI/JAWS to use HTTPS?
search cancel

How do I setup AAI/JAWS to use HTTPS?

book

Article ID: 191576

calendar_today

Updated On:

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 protocol="TLS">

        <engine enabled-protocols="TLSv1.1 TLSv1.2" />

        <keystore path="keystore" relative-to="jboss.server.config.dir" keystore-password="password" provider="JKS"/>

    </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 protocol="TLS">

        <engine enabled-protocols="TLSv1.1 TLSv1.2" />

        <keystore path="keystore" relative-to="jboss.server.config.dir" keystore-password="changeit" provider="JKS"/>

    </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 protocol="TLS">

        <engine enabled-protocols="TLSv1.1 TLSv1.2" />

        <keystore path="jaws.keystore" relative-to="jboss.server.config.dir" keystore-password="changeit" provider="JKS"/>

    </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:

<subsystem xmlns="urn:jboss:domain:remoting:3.0">

    <endpoint/>

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

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

</subsystem>

 

Replace with:

<subsystem xmlns="urn:jboss:domain:remoting:3.0">

    <endpoint/>

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

    <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:

<server name="default-server">

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

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

    <host name="default-host" alias="localhost">

                                    <location name="/" handler="root-redirect"/>

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

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

                                    <!--<filter-ref name="disable-byte-range"/>-->

                                    <!--<access-log prefix="my_access" />-->

    </host>

</server>

 

Replace with:

<server name="default-server">

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

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

    <host name="default-host" alias="localhost">

                                    <location name="/" handler="root-redirect"/>

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

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

                                    <!--<filter-ref name="disable-byte-range"/>-->

                                    <!--<access-log prefix="my_access" />-->

    </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?