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 Connectors. This means that these components communicate with the AAI Server through HTTPS using two-way certificate-based authentication over TLS 1.3.

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, aaikey, 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/aaikey -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 aaiserver -keyalg RSA -keystore <AAI_HOME>/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_HOME>\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.

Linux

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

Windows

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

Update the AAI Server Configuration for TLS

To enable HTTPS with TLS you have to make for modifications to the <AAI_HOME>/jboss/standalone/configuration/standalone.xml file. The places that you must make 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.

   1. Locate <security-realm name="ApplicationRealm"> section—not the "ClientCertRealm", which looks very similar.

   2. Uncomment the <server-identities> section.  

   3. In the <ssl> section, update the keystore path and keystore-password to align with your keystore definition.

      Note:

      The keystore path is relative to the jboss/standalone/configuration directory or folder. If the keystore file is placed in jboss/standalone/configuration, the keystore path would be just the name of the keystore file.

   4. Change the keystore-password from the default ("password") to secure passwords for both the truststore and the keystore. The passwords that you enter here must match the passwords entered when generating the certificates for AAI and the Connector. For information, see Configuring the AAI Server for TLS Authentication

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

      <security-realms>
          ....
          <security-realm name="ApplicationRealm">
   	   <server-identities>
   		<ssl>
   		    <keystore path="aai.keystore" relative-to="jboss.server.config.dir" keystore-password="my*secure*password" key-password="my*secure*password" generate-self-signed-certificate-host="localhost"/>
   		</ssl>
   	   </server-identities>
   	   ....
         </security-realm>
         ....					
      <security-realms/>		
   

2. Enable the socket-binding listener for HTTPS.

   By default, the server is set up to listen on the HTTP port. To enable the HTTPS port, do the following:

   1. Locate the <server name="default-server"> section.

   2. Uncomment the https-listener name="https".

   After your changes, the <server name="default-server"> element looks like this.

   
   	<server name="default-server">
   		<http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
   		<https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
   		<!-- SSL listener with client auth verification required. -->
   		<!-- To enable this, enable the socket binding and security realm as well -->
   		<!--<https-listener name="clientauth-https" socket-binding="clientauth-https" security-realm="ClientCertRealm" enable-http2="true" verify-client="REQUIRED"/>-->
   		<host name="default-host" alias="localhost">
   			<location name="/" handler="welcome-content"/>
   			<filter-ref name="telemetry"/>
   			<http-invoker security-realm="ApplicationRealm"/>
   		</host>
   	</server>					
   						

3. Restart the AAI server for the changes to take effect.

Summary of Changes to the standalone.xml for the AAI Server TLS 

The original standalone.xml file:

Before you make the changes to the standalone.xml file to configure TLS for the AAI Server, the following sections in the file look like the sample here. The elements that you update are in bold and the attributes and controls that you modify are underlined. Four dots indicate any number of additional elements that are not shown here.

<management>	
   ....
   <security-realms>
   .   ...
       <security-realm name="ApplicationRealm">
	   <server-identities>
		<ssl>
		    <keystore path="application.keystore" relative-to="jboss.server.config.dir" keystore-password="password" key-password="password" generate-self-signed-certificate-host="localhost"/>
		</ssl>
	   </server-identities>
	   ....
      </security-realm>
      ....					
   <security-realms/>
   ....				
<management/>					
<profile">
   ...				
   <subsystem xlms="urn:joboss:domain:undertow:12.0" ....>
	<buffer-cache name="default"/>
	<server name="default-server">
		<http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
		<!--<https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>-->
		<!-- SSL listener with client auth verification required. -->
		<!-- To enable this, enable the socket binding and security realm as well -->
		<!--<https-listener name="clientauth-https" socket-binding="clientauth-https" security-realm="ClientCertRealm" enable-http2="true" verify-client="REQUIRED"/>-->
		    <host name="default-host" alias="localhost">
			<location name="/" handler="welcome-content"/>
			<filter-ref name="telemetry"/>
			<http-invoker security-realm="ApplicationRealm"/>
		    </host>
	</server>
	....
   <subsystem/>
   ....
<profile/>

An updated standalone.xml file

When you update the standalone.xml file to configure TLS for your AAI Server, you make the following changes:

• In the <security-realm name="ApplicationRealm"> section:

  • Uncomment the <server-identities> section to enable TLS

  • Change the keystore path=“keystore” to keystore path="aai.keystore"

  • Change the keystore password from the default "password" value to "my*secure*password" (whatever your password is)

• Enable the listener for the HTTPS port and, with it, enable the socket binding for the port

After you make the changes to the standalone.xml file to configure TLS for the AAI Server, the following sections in the file look like the sample here. The elements that you update are in bold and the attributes and controls that you modify are underlined. Four dots indicate any number of additional elements that are not shown here.

<management>	
   ....
   <security-realms>
   ....
       <security-realm name="ApplicationRealm">
	   <server-identities>
		<ssl>
		    <keystore path="aai.keystore" relative-to="jboss.server.config.dir" keystore-password="my*secure*password" key-password="my*secure*password" generate-self-signed-certificate-host="localhost"/>
		</ssl>
	   </server-identities>
	   ....
      </security-realm>
      ....					
   <security-realms/>
   ....				
<management/>					
<profile">
   ...				
   <subsystem xlms="urn:joboss:domain:undertow:12.0" ....>
	<buffer-cache name="default"/>
	<server name="default-server">
		<http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
		<https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
		<!-- SSL listener with client auth verification required. -->
		<!-- To enable this, enable the socket binding and security realm as well -->
		<!--<https-listener name="clientauth-https" socket-binding="clientauth-https" security-realm="ClientCertRealm" enable-http2="true" verify-client="REQUIRED"/>-->
		    <host name="default-host" alias="localhost">
			<location name="/" handler="welcome-content"/>
			<filter-ref name="telemetry"/>
			<http-invoker security-realm="ApplicationRealm"/>
		    </host>
	</server>
	....
   <subsystem/>
   ....
<profile/>

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.

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/aai.keystore -alias aaiserver -file FileName.cer

Windows

%JAVA_HOME%\bin\keytool -export -keystore <AAI_HOME>\jboss\standalone\configuration\aai.keystore -alias aaiserver -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 aaiserver

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/aai.keystore -destkeystore $JAVA_HOME/jre/lib/security/cacerts

Windows

%JAVA_HOME%\bin\keytool -importkeystore -srckeystore <AAI_HOME>\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 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/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 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.

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 AAI: TLS and Kerberos

• Installing AAI

• Configuring the Connectors for TLS Authentication