Configuring the AAI Server for TLS Authentication

As a system administrator, you have the option of setting up the AAI to use HTTPS with TLS, thus protecting the data flow between the AAI Server and its communication partners, such as the Reporting Server or the Connectors. This means that these components communicate with the AAI Server through HTTPS using two-way certificate-based authentication over TLS 1.2.

Using an Existing Keystore File or CA Signed Certificate

If you already have a keystore file, for example, .jks, make sure that the file is included in your JBoss configuration directory:

<AAI Install directory>\jboss\standalone\configuration

If you are using a CA signed certificate file, make sure to import it into a keystore file, for example, jawskey, which you can create in the directory mentioned above.

You can use keytool to import the certificate file into the keystore file you created by running the following command:

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

Generate a Self-Signed Certificate Keystore File

The AAI application requires access to a keystore file containing the certificate and key to be used. This section provides an example on how to use a self-signed certificate.

Generate a Key and Keystore

To create a keystore file, log into the AAI Server using the user that is used to start and stop the AAI application.

Linux Example

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

Windows Example

%JAVA_HOME%\bin\keytool -genkey -alias jawsserver -keyalg RSA -keystore <AAI_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):

Verify the Keystore File

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

Linux

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

Windows

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

Update the AAI Server Configuration

To enable HTTPS with TLS you have to make for modifications to the <AAI_HOME>/jboss/standalone/configuration/standalone.xml file. The exact changes are underlined to highlight them.

Follow these steps to make the necessary modifications:

1. Enable the TLS protocol.

   The TLS protocol is disabled by default. To enable the TLS protocol, you must uncomment the TLS protocol section. To do so, locate it 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. Modify the keystore path and password.

   These section must reflect the keystore definition.

   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. Enable the HTTPS connector.

   The HTTP connector is enabled by default. To disable it and enable the HTTPS connector, you must comment out the HTTP connector and uncomment the HTPPS connector.

   To do so, 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. Enable 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.

   To do so, 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>

Launch the AAI Client from a Web Browser

You should be able to launch the AAI client using HTTPS with TLS using the URL:

https://<ServerName>:8443/aai/

For more information, see Logging In to AAI.

Add the Public Key Certificate to the AAI Client (Self-Signed Certificates Only)

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

To remediate this issue, you can add a Public Key Certificate to the list of Trusted Certificates on the client machine to allow access and remove the warning.

Exporting the Public Key Certificate on the AAI Server

Linux

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

Windows

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

Importing the Certificate as a Trusted Certificate on the Client

You also might be required to carry out the following update on each client machine that requires access to the AAI Server.

Linux

/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

To import the certificates, do the following:

1. Run mmc.exe from the Start menu on the client.

2. Click File and then click Add/Remove Snap-in.

3. Choose Certificates from the list then click Add.

4. In the Certificates snap-in pop-up window, select Computer Account then click Next.

5. In the Select Computer pop-up window, select Local Computer then click Finish.

6. Click OK to confirm Certificates (Local Computer) snap-in.

7. Expand Certificates, expand Trusted Root Certification Authorities.

8. Right-click Certificates, click All Tasks, and then click Import.

9. On the Certificate Import Wizard Welcome page, click Next.

10. Browse to the location of the saved certificate file, select the file and then click Open.

11. Select Next.

12. In the Certificate Store, select Place all certificates in the following store and choose Trusted Root Certification Authorities.

13. Select Next and then Finish.

Make sure you restart all browsers.

Secure Access from the CLI

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

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

Updating the Path to the Keystore File

To update the path to the keystore file, do the following:

1. Make a copy of <AAI_HOME>/batch/lib/jaws_ssl.py as a backup.

2. Edit <AAI_HOME>/batch/lib/jaws_ssl.py.

3. 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.

4. Uncomment and update the password. Make sure there are no blank spaces at the beginning of the line.

Required Command Line Options

All CLI scripts should use the login_with_params() function found in batch/lib/params.py rather than login(). For more information, see Getting Started Commands.

The following command line options are required for HTTPS with TLS access:

• -port 8443

• -protocol https

Example

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

Using TLS with Subscription Services (5.7+)

The Subscription Services process within AAI may fail to deploy when the AAI Server is configured for TLS only using an untrusted certificate. This issue can be detected by an error similar to the one below which can be 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

Linux

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

Windows

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

The keytool command will prompt you for the destination and source passwords. The destination should be changeit unless modified by the system administrator. The source password is the same as defined while generating the self-signed certificate keystore file, see Generate a Self-Signed Certificate Keystore File.

Troubleshooting

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:

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: [suplja02.termalabs.com, 192.168.1.1];

In this case, you might need to generate a self-signed certificate keystore file again making sure you use the correct SAN (Subject Alternative Name), see Generate a Self-Signed Certificate Keystore File.

You also need to carry out all subsequent steps to export/import the certificate to other cert files.

AAI Export/Import

There are no additional configuration changes required to use TLS with the AAI Export/Import tools. For more information, see About Importing and Exporting.

The only changes required are additional parameters on the command line.

From a command prompt on the AAI Server, change to the respective directory and run the following command:

Linux

<AAI_HOME>/import_export/bin directory

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

Windows

<AAI_HOME>\import_export\bin folder

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

TLS Connection to SMTP Server

To enable TLS connection to the SMTP server, make sure that you select the Use STARTTLS checkbox on the Other tab of the Configuration Tool UI. For more information, see Configuration Tool - Other Tab.

You can also do so using the commands specific to SMTP from the Configuration Tool CLI. For more information, see SMTP Configuration Commands.

See also:

• Securing Automic Automation Intelligence

• Installing Automic Automation Intelligence

• Configuring the Connectors for TLS Authentication

• Configuring the AAI Server for TLS Authentication