Configuring the AAI Server for TLS Authentication

As a system administrator, you can set up AAI to use secure communication with an HTTPS protocol with TLS, thus protecting the data flow between the AAI Server and its communication partners, such as the Connectors. This means that these components communicate with the AAI Server through HTTPS using two-way certificate-based authentication over TLS 1.3.

Important!

If the AAI Server is configured to use HTTPS with TLS, the Connectors must be configured with HTTPS, too.

This page includes the following:

Using Trusted CA-Signed Certificates

When preparing an AAI instance for a production environment, to properly set up TLS secured communication with the AAI Server, use the following steps

Tip:

For expedience when setting up a non-production environment (for example, for testers or developers), you can use a self-signed certificate for your TLS configuration. For information, see Using a Self-Signed Certificate Keystore File.

  1. Get three CA-signed certificates (Certificate Authority certificates), one for each of the following parts of the certificate chain (also known as the "chain of trust"):

    • The certificate from the Certificate Authority (CA) itself

    • An intermediate certificate  

    • A root certificate

  2. Add a keystore file to your JBoss configuration directory:

    <AAI Install directory>\jboss\standalone\configuration

    • If you already have a keystore file that you want to use, for example, .jks, make sure that the file is included in the directory.

    • If you don't have a keystore file that you want to use, create a keystore file, for example, aaikeys, in the directory.

  3. Import each of the three certificates into the keystore file.

    If the keystore file a keystore file with all three certificates, then you can skip this step.

    There are a number of standard methods that you can use. One way is to use the keytool utility by running the following command:

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

  4. Update the standalone.xml file to configure the AAI Server for TLS with the prepared certificates, as explained in Update the AAI Server Configuration for TLS.

Using 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. Typically, if you use a self-signed certificate, you use it in non-production environments. Using a self-signed certificate avoids having to purchase a certificate, however, it is less secure and you will get warning messages to that effect when starting up AAI. This is not recommended for production environments. For production environments, see Using Trusted CA-Signed Certificates.

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.

Notes:

  • The JAVA_HOME environment variable must be set to the root of a Java JDK install, for example /usr/java/jdk-17.

  • Replace <AAI_HOME> in each of the commands with the root path of the AAI installation.

  • The location of the srckeystore must be the same as specified while generating the self-signed certificate keystore file, see Using a Self-Signed Certificate Keystore File.

  • 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 (for example, /usr/java/jdk-17/jre/lib/security).

  • The default password for cacerts is usually changeit.

  • You might need to run the following commands at the root directory to import a keystore file into <AAI_Installation_Directory>/jboss/standalone/configuration. When you do this, you must log into the AAI Server using the user that you use to start and stop the AAI application.

Linux Example

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

Windows Example

%JAVA_HOME%\bin\keytool -genkey -alias aaiserver -keyalg RSA -keystore <AAI_Installation_Directory>\jboss\standalone\configuration\aai.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 <aaiserver>
        (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.

Note:

Replace <AAI_Installation_Directory> in each of the commands with the root path of the AAI installation.

Linux

$JAVA_HOME/bin/keytool -list -v -keystore <AAI_Installation_Directory>/jboss/standalone/configuration/aai.keystore -alias aaiserver

Windows

%JAVA_HOME%\bin\keytool -list -v -keystore <AAI_Installation_Directory>\jboss\standalone\configuration\aai.keystore -alias aaiserver

Importing the Certificate as a Trusted Certificate into the Java keystore

AAI processing is handled by both the server processes and a number of micro-services that handle processing of a specific functional area or collecting audit history data. These micro-services operate in a Java environment. To ensure that these micro-services are also accessing and passing data through TLS-secured communications protocols, you need to import your CA-signed certificate into the Java keystore.

  • The JAVA_HOME environment variable must be set to the root of a Java JDK install, for example /usr/java/jdk-17.

  • Replace <AAI_HOME> in each of the commands with the root path of the AAI installation.

  • The location of the srckeystore must be the same as specified while generating the self-signed certificate keystore file, see Using a Self-Signed Certificate Keystore File.

  • 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 (for example, /usr/java/jdk-17/jre/lib/security).

  • The default password for cacerts is usually changeit.

  • You might need to run the following commands at the root directory to import a keystore file into <AAI_Installation_Directory>/jboss/standalone/configuration. When you do this, you must log into the AAI Server using the user that you use to start and stop the AAI application.

Linux

When the AAI Server runs in a Linux operating system, use the following command:

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

Windows

When the AAI Server runs in a Windows operating system, use the following command:

%JAVA_HOME%\bin\keytool -importkeystore -srckeystore <AAI_Installation_Directory>\jboss\standalone\configuration\aai.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 Using a Self-Signed Certificate Keystore File.

Important!

Make sure you restart the AAI application because the changes do not take effect until the application has been restarted.

Update the AAI Server Configuration for TLS

To configure your AAI Server for TLS communication over an HTTPS protocol, you have to make modifications to the following configuration file:

<AAI_Installation_Directory>/jboss/standalone/configuration/standalone.xml file.

The steps in this section take you through the steps to prepare and configure this file. The configuration basically consists of the following:

  • Providing keystore file locations and passwords and then

  • Enabling HTTPS for the TLS communication

Modifying the standalone.xml for a TLS configuration for the AAI Server

Notes:
  • The following steps are the same for both UNIX and Windows environments.

  • In the file paths in the steps and examples use the ‘/’ (forward slash) to delineate the folder structure. This is the Linux syntax. For Windows environments, replace those with ‘\’ (backslash).

  • In these steps, the places that you must make changes are underlined to highlight them.

  1. If you have not yet done so (for example, to configure TLS for the AAI Connector), copy the provided default configuration file to create a file that you will modify, while you keep the original, unmodified file as a backup.

    1. Go the <AAI_Installation_Directory>/jboss/standalone/configuration directory.

    2. Copy —do not rename! — standalone.xml.fresh to standalone.xml into the same directory.

      Keep the standalone.xml.fresh as a backup of the original if you need to refer to it or revert to the original and start again.

  2. In the <AAI_Installation_Directory>/jboss/standalone/configuration directory, open the standalone.xmlfile in edit mode in an XML or text editing tool.

  3. Specify the keystore filename and password for the AAI Server keystore with your certificates.

    1. Find the <key-store name="applicationKS"> element.

    2. In the <credential-reference clear-text="password"> element, replace password with the password for your AAI Server keystore.

    3. Two lines below that, in the element starting with <file path="application.keystore", replace application.keystore with the name of the keystore file for your AAI Server.

      Note:

      Note that you put the keystore file in the same directory as the standalone.xml, that is, in <AAI_Installation_Directory>/jboss/standalone/configuration directory, when you did one of the following in preparation for configuring the AAI Server:

    After your changes, the changed <key-store name="applicationKS"> element looks like this, but with your own keystore path and password. The elements in question are in bold and the changed parts are underlined.

    	<key-store name="applicationKS">
    		<credential-reference clear-text="jaws88"/>
    		<implementation type="JKS"/>
    		<file path="aaiserver.keystore" relative-to="jboss.server.config.dir"/>
    	</key-store>	
    

  4. Specify the password for the key manager of the AAI Server keystore with your certificates.

    1. Find the element that starts with <key-manager name="applicationKM".

    2. In the <credential-reference clear-text="password"> element, replace password with the password for your AAI Server keystore.

    After your changes, the changed <key-manager name="applicationKM"> element looks like this, but with your own keystore path and password. The elements in question are in bold and the changed parts are underlined.

    	<key-manager name="applicationKM" key-store="applicationKS" generate-self-signed-certificate-host="localhost">
    		<credential-reference clear-text="jaws88"/>
    	</key-manager>
    

  5. Enable TLS communication for the AAI Server by enabling the HTTPS protocol, which is disabled by default.

    1. Find the <server name=”default-derver”> element.
    2. Two lines below it, uncomment the element that begins with <https-listener name="https" by removing the <!-- at the beginning and --> at the end.

      Note:

      There are three https-listener elements. Make sure to uncomment the one with name="https":

      • <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>

        This refers to the default HTTP that is always available, even when HTTPS is enabled.

      • <https-listener name="https" socket-binding="https" ssl-context="applicationSSC" enable-http2="true"/>

        This enables and configures HTTPS for the AAI Server.

      • <https-listener name="clientauth-https" socket-binding="clientauth-https" ssl-context="connectorSSC" enable-http2="true"/>

        This enables and configures HTTPS for the AAI connector.

    After you enable HTTPS for the AAI Server, the changed <server> element looks like this. In this example, HTTPS is enabled for the AAI Server, but not the AAI Connector. The elements in question are in bold.

    	<server name="default-server">
    		<http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
    		<https-listener name="https" socket-binding="https" ssl-context="applicationSSC" enable-http2="true"/>
    		<!--<https-listener name="clientauth-https" socket-binding="clientauth-https" ssl-context="connectorSSC" enable-http2="true"/>-->
    

  6. Restart the AAI Server for the changes to take effect.

Next steps: If the AAI Server is configured to use HTTPS with TLS, the AAI Connector must be configured with HTTPS, too.

Launch the TLS-Secured AAI

Test your TLS-secured configuration by launching the AAI application in your web browser using this HTTPS URL:

https://<hostname>:8443/aai/

For more information, see Logging In/ Out.

Secure Access from the CLI

If your AAI instance runs on a secure HTTPS protocol with TLS encryption, you can also access the AAI database with AAI command-line interface (CLI) commands. Depending on the type of security certificate you have, you might have to take additional configuration steps:

  • If you are using a CA-signed certificate to secure your HTTPS AAI instance, you can use CLI commands to access its database without further steps.

    Reason: The AAI CLI uses the Python "certi" package to manage trusted certificates for HTTPS URLs. This package installs the common CA trusted certificates. If you have a CA-signed certificate for AAI, then you can use the CLI without any other steps.

  • If you are using a self-signed certificate to secure your HTTPS AAI instance, and you want to use CLI commands to access its database, you must take the additional setup steps that follow.

Important!

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

Preparing AAI with a Self-Signed Certificate for CLI

If you have a self-signed certificate, then you will need to take the following additional steps:

  1. Export the AAI Server certificate in a pem file format. From a Java keystore, you can use the following keytool command:

    $ keytool -exportcert -rfc -alias aaiserver -file aai-server.pem -keystore application.keystore -storepass changeit -storetype JKS

    For other formats of keystores or certificates, you can convert them to a pem file format using openssl tools according to their documentation.

  2. From a Python command line, execute the following:

    >>> import certifi

    >>> print(certifi.where())

    The output will display the full path where the trusted certificates are stored, for example,

    /home/user/.venv/lib/python3.12/site-packages/certifi/cacert.pem

  3. Backup that file for safety.

  4. Append your AAI Server pem file to the cacerts, using one of the following commands:

    On Linux:

    $ cat aai-server.pem >> /home/user/.venv/lib/python3.12/site-packages/certifi/cacert.pem

    On Windows:

    $ type aai-server.pem >> C:\Python3.12\site-packages\certifi\cacert.pem

Important!

If the certifi package is updated or re-installed, you will need to repeat these steps.

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.

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

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

To import a keystore file, log into the AAI Server using the user that you use to start and stop the AAI application.

  • The JAVA_HOME environment variable must be set to the root of a Java JDK install, for example /usr/java/jdk-17.

  • Replace <AAI_HOME> in each of the commands with the root path of the AAI installation.

  • The location of the srckeystore must be the same as specified while generating the self-signed certificate keystore file, see Using a Self-Signed Certificate Keystore File.

  • 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 (for example, /usr/java/jdk-17/jre/lib/security).

  • The default password for cacerts is usually changeit.

  • You might need to run the following commands at the root directory to import a keystore file into <AAI_Installation_Directory>/jboss/standalone/configuration. When you do this, you must log into the AAI Server using the user that you use to start and stop the AAI application.

Linux

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

Windows

%JAVA_HOME%\bin\keytool -importkeystore -srckeystore <AAI_Installation_Directory>\jboss\standalone\configuration\aai.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 Using a Self-Signed Certificate Keystore File.

Important!

Make sure you restart the AAI application because the changes do not take effect until the application has been restarted.

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/aai/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.2];

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 Using a Self-Signed Certificate Keystore File.

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

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: