Configuring the Connectors for TLS Authentication

You have to configure the Connector to authenticate using a certificate and to verify the server certificate. This section guides you through the process.

The connector framework includes support for communication with the AAI server using two-way certificate-based authentication over TLS 1.2. This authentication must be configured on the AAI server and any Connector wishing to communicate with it securely.

You only have to carry out the tasks to configure the AAI server once. However, you have to generate a certificate for each Connector that will connect to the AAI server and add the AAI server’s CA to its trust store.

This page includes the following:

Requirements

To secure a Connector, your system must meet the following requirements:

OpenSSL version 1.1.1 installed and on the system path
JDK version 8 or later, with tools keytool and jar installed and on the system path

In addition, you must have installed or upgraded your AAI server to at least version 6.3.0 (including the database schema), and you must have installed or upgraded a Connector that is based on the connector framework.

Overview

The authentication setup can be broken down into three steps:

Generate AAI server certificate and configure AAI to allow two-way certificate-based authentication over TLS 1.2.

AAI runs within a JBoss container which must be configured to allow two-way authentication via certificates for a Connector to communicate with it over TLS 1.2.
Generate client certificates for Connectors to authenticate over two-way TLS 1.2.

Once the AAI server has been configured to allow certificate-based authentication over TLS 1.2, you have to generate client certificates for each Connector that you want to authenticate using certificates.
Configure the Connectors.

Each Connector that must communicate with the AAI server over two-way TLS 1.2 must be configured using a unique client certificate generated and trusted by the AAI server. The Connector also must be configured to trust the AAI server certificate. A single Connector installation can only communicate with one AAI server instance, but one AAI server instance can communicate with multiple Connectors.

The generated client certificate is packaged in a .jar file along with any other resources needed by the Connector to successfully authenticate with the AAI server using client certificate authentication. If the Connector is running on a different machine than the AAI server instance, this single .jar file must be transferred to the machine running the Connector into a specific directory. Since the AAI server generates its own Certificate Authority (CA) to self-sign certificates, you may need to add the AAI server CA to the trust store of the connector machine for two-way TLS to commence, otherwise the client is not able to verify the server's certificate.

Configuring Two-Way Certificate-Based Authentication over TLS 1.2 on the AAI Server

Generating the AAI Server Key

You have to generate the AAI server key that is used to sign and verify the connector client certificates. This requires running a command line script found in the connectors directory of the AAI installation.

To generate the AAI server key, follow these steps:

Navigate to the connectors directory under the AAI server installation.

Example

Automic_Automation_Intelligence/connectors
In a terminal window, run the following command:

UNIX: ./generateAaiKey.sh

Windows: generateAaiKey.bat
You are prompted to enter the following parameters:
- The server certificate name, which is used in the generated keys and certificates to identify the server.
  
  Important! The server certificate name must be the DNS name of the server on which AAI is installed. The DNS name of the server is used in the generated client certificate as the CN.
- The keystore password, which must be the same password that was entered in the standalone.xml file for the keystore
  
  The password is not displayed on the terminal, so it is repeated to avoid issues with typos. The password can include special characters or spaces.
The output generated by the script indicates that the key is generated and copied directly to the AAI server configuration directory jboss/standalone/configuration.

Example of running generateAaiKey.sh
```
[root@lvnkdev001361 connectors]# ./generateAaiKey.sh
Server certificate name: lvnkdev001361.bpc.broadcom.net

Server keystore password:
Repeat keystore password:
Generating key ...
Certificate stored in file <certout.pem>
Certificate was added to keystore
Key generated in jboss/standalone/configuration/aaiconnectorkey.p12
```

Configuring JBoss to Allow Two-Way Certificate-Based Authentication over TLS 1.2

A dedicated port is configured on the AAI server that requires a verified client certificate. This port is used only by clients (such as the Connectors) that have a certificate issued and signed by that AAI server.

To enable Client Certificate Authentication on the AAI server, follow these steps:

Locate the standalone.xml AAI server configuration file within the JBoss installation, which is usually located in the jboss\standalone\configuration directory.

Note:
A copy of standalone.xml file called standalone.xml.fresh is provided to customers as a backup of the original.
Add a new security-realm to allow two-way TLS using certificates. To do so, uncomment the <security-realm name="ClientCertRealm"> section of the standalone.xml file and modify it as shown in the example below. If your standalone.xml file does not have that section, the example of the updated standalone.xml section below can be used as a copy that you can add to the <security-realms> section. The passwords entered here must match the passwords entered when generating the certificates for AAI and the Connector (see Creating and Signing the Certificate).

Whether you uncomment or copy the section, you have to change the keystore-password to something more secure than the default value ("password") for both the trust store and the keystore. You also have to update the truststore and keystore paths as follows:
- Change path=“truststore.p12” to path=“connectortrust.p12”
- Change path=“keystore.p12” to path=“aaiconnectorkey.p12”
```
<security-realm name="ClientCertRealm">
    <authentication>
        <truststore path="connectortrust.p12" relative-to="jboss.server.config.dir" keystore-password="password"/>
    </authentication>
    <server-identities>
       <ssl protocol="TLS">
           <engine enabled-protocols="TLSv1.1 TLSv1.2" />
           <keystore path="aaiconnectorkey.p12" relative-to="jboss.server.config.dir" keystore-password="password"/>
       </ssl>
    </server-identities>
</security-realm>
```
Add a new https-listener to allow JBoss to listen for HTTPS connections. To do so, uncomment the <https-listener name="clientauth-https" section of the standalone.xml file. If your standalone.xml file does not have that section, the example of the updated standalone.xml section below can be used as a copy that you can add to the <server name="default-server"> section:
```
<https-listener name="clientauth-https" 
socket-binding="clientauth-https" security-realm="ClientCertRealm" 
verify-client="REQUIRED"/>
```
Add a new socket-binding to allow JBoss to listen for the HTTPS connections on port 4443. To do so, uncomment the <socket-binding name="clientauth-https" interface="public" port="4443"/> line of the standalone.xml file. If your standalone.xml file does not have that line, the example of the updated standalone.xml line below can be used as a copy that you can add to the <socket-binding-group name="standard-sockets" default-interface="public" port-offset="0"> section:

<socket-binding name="clientauth-https" interface="public" port="4443"/>

Restart the AAI server for the changes to take effect.

Example

Original standalone.xml file

<server>
   <security-realms>
      <!--
      <security-realm name="ClientCertRealm">
         <authentication>
            <truststore path="truststore.p12" relative-to="jboss.server.config.dir" keystore-password="password"/>
         </authentication>
         <server-identities>
            <ssl protocol="TLS">
               <engine enabled-protocols="TLSv1.1 TLSv1.2" />
               <keystore path="keystore.p12" relative-to="jboss.server.config.dir" keystore-password="password"/>
            </ssl>
         </server-identities>
      </security-realm>
      -->
   </security-realms>
   <profile>
      <subsystem xmlns="urn:jboss:domain:undertow:3.1">
         <server name="default-server">
            <!--<https-listener name="clientauth-https" socket-binding="clientauth-https" security-realm="ClientCertRealm" verify-client="REQUIRED"/>-->
         </server>
      </subsystem>
   </profile>
   <socket-binding-group name="standard-sockets" default-interface="public" port-offset="0">
      <!--<socket-binding name="clientauth-https" interface="public" port="4443"/>-->
   </socket-binding-group>
</server>

Updated standalone.xml file:

Uncommented text relevant for TLS/SSL
Changed path=“truststore.p12” to path=“connectortrust.p12”
Changed path=“keystore.p12” to path=“aaiconnectorkey.p12”
Change default "password" value

<server>
   <security-realms>
      <security-realm name="ClientCertRealm">
         <authentication>
            <truststore path="connectortrust.p12" relative-to="jboss.server.config.dir" keystore-password="password"/>
         </authentication>
         <server-identities>
            <ssl protocol="TLS">
               <engine enabled-protocols="TLSv1.1 TLSv1.2" />
               <keystore path="aaiconnectorkey.p12" relative-to="jboss.server.config.dir" keystore-password="password"/>
            </ssl>
         </server-identities>
      </security-realm>
   </security-realms>
   <profile>
      <subsystem xmlns="urn:jboss:domain:undertow:3.1">
         <server name="default-server">
            <https-listener name="clientauth-https" socket-binding="clientauth-https" security-realm="ClientCertRealm" verify-client="REQUIRED"/>
         </server>
      </subsystem>
   </profile>
   <socket-binding-group name="standard-sockets" default-interface="public" port-offset="0">
      <socket-binding name="clientauth-https" interface="public" port="4443"/>
   </socket-binding-group>
</server>

Generating the Client Certificate for a Connector

The AAI server key that is stored in aaiconnectorkey.p12 is used to sign and verify the Connector certificate. This is why the Connector certificate must be generated on the AAI server.

When you generate the Connector certificate, a .jar file is created. It contains the credentials required for the Connector to communicate with the AAI server over TLS/SSL. It is recommended to generate and sign the Connector certificate before installing and configuring the Connector.

If the Connector has been installed and configured using unsecured HTTP, you can convert it to HTTPS. For more information, see Converting the Connector from HTTP to HTTPS.

Creating and Signing the Certificate

To create and sign the certificate, follow these steps:

Navigate to the connectors directory under the AAI server installation directory.
In a terminal window, run the following command:

UNIX: ./generateConnectorCert.sh

Windows: generateConnectorCert.bat
You are prompted to enter the following parameters:
- The Connector name, which is used in the generated certificate to identify the Connector.
  
  It must be a readable and unique name for the Connector that you are installing. This name is used for the .jar file that is generated as the output of this script. The name is also used on the Connector server to allow the Connector to communicate with the AAI server over TLS/SSL.
- A new password for the Connector keystore.
  
  Keep this password at hand; you will need it to install the Connector credentials. The password is not displayed on the terminal, so it is repeated to avoid issues with typos. The password can include special characters or spaces.
  
  The script displays confirmation that the certificate signing request was successfully generated.
- Enter the AAI server keystore password.
  
  This is the password entered when generating the AAI server key (see Generating the AAI Server Key). It must match the password used for the aaiconnectorkey.p12 entry in the standalone.xml file while configuring the JBoss (see Configuring JBoss to Allow Two-Way Certificate-Based Authentication over TLS 1.2 )
  
  The output generated by the script includes the details of the certificate and the name of the generated .jar file.

Copy the generated .jar file so that it is available during the Connector installation.

Example of runninggenerateConnectorCert.sh

[root@lvnkdev001361 connectors]# ./generateConnectorCert.sh
Enter the connector name: Automic-connector

Enter a password for the new connector keystore:
Repeat the connector keystore password:
Generating connector certificate signing request ...

Signing Automic-connector.csr ...
Enter the password for the server keystore:
MAC verified OK
MAC verified OK
Using configuration from serversign.cnf
Check that the request matches the signature
Signature ok
Certificate Details:
        Serial Number:
            ac:d4:ff:de:9f:46:47:91
        Validity
            Not Before: May 25 21:50:29 2021 GMT
            Not After : May 26 21:50:29 2121 GMT
        Subject:
            countryName               = US
            organizationName          = broadcom
            commonName                = Automic-connector
        X509v3 extensions:
            X509v3 Key Usage:
                Digital Signature, Non Repudiation, Key Encipherment
            X509v3 Subject Key Identifier:
                14:A0:F7:3B:BC:72:ED:7D:3E:3B:7F:54:FA:F2:1B:80:E8:6B:6A:D3
Certificate is to be certified until May 26 21:50:29 2121 GMT (36525 days)

Write out database with 1 new entries
Data Base Updated
Certificate was added to keystore
Certificate reply was installed in keystore
Importing keystore ../jboss/standalone/configuration/connectortrust.p12 to aaiservertrust.p12...
Entry for alias lvnkdev001361.bpc.broadcom.net successfully imported.
Import command completed:  1 entries successfully imported, 0 entries failed or cancelled

Connector certificate package generated to Automic-connector.jar

Installing the Connector with Two-Way Certificate-Based Authentication over TLS 1.2

During the Connector installation process, you have to copy the generated .jar file to the installation directory in a specific location.

To install the Connector with HTTPS support, follow these steps:

Navigate to the root directory of the Connector installation.

Example

UNIX: /opt/automic-connector.

Windows: C:\Program Files\automic-connector.
Create a new /secure directory.

UNIX Example

/opt/automic-connector/secure
Copy the .jar file generated in Automic_Automation_Intelligence/connectors directory to the secure directory.
Check that the Connector configuration script given by the rpm installer refers to an existing Connector.

Example

UNIX: /opt/automic-connector/configure-connector.sh

Windows: \<Install Dir>\automic-connector\setup.bat

The last line of the script begins as java -cp ./automic-connector.jar. Make sure that the automic-connector.jar file is located in the current directory.

Run the Connector configuration script:

UNIX: ./configure-connector.sh

Windows: setup.bat

The following reminder is displayed. If you have already created the secure directory and copied the .jar file into it, press Enter. Otherwise, press ctrl-c to quit the script.

  [root@lvnkdev001361 automic-connector]# ./configure-automic-connector.sh
If you are planning to make a TLS based connection to AAI then before proceeding
please obtain the connector certificate package from the AAI server
and copy it to ./secure/
Press ENTER to continue...

When prompted, enter the following parameters:
1. An HTTPS URL for the AAI server.
  
  Port: 4443
  
  Example
  
  https://{hostname}:4443
  
  Important! The host must be the DNS name of the server configured above. Also, the host name must match the host.
2. The Connector name.
  
  Important! The Connector name must be unique in AAI. The name must match the Connector name used when generating the client certificate. The application uses this to identify the name of the client certificate .jar file in the /secure directory.
3. The Connector host name. Optionally, you can use the DNS name configured above.
  
  The hostname is also part of the Connector information recorded in the AAI database as a hint to where the Connector is installed.
4. The Connector keystore password that was used to generate the .jar file.
5. When using TLS/SSL, you can leave the AAI user, password, and domain empty.
  
  The configuration script indicates if the HTTPS connection to AAI was successful. The Connector configuration is automatically updated if the connection succeeds. A new application.yml file is generated.

Make sure that http:client:ssl:enabled is set to true in the application.yml file:

http:
  client:
    ssl:
      enabled: true

Example of running configure-connector.sh

[root@lvnkdev001361 automic-connector]# ./configure-automic-connector.sh
If you are planning to make a TLS based connection to AAI then before proceeding
please obtain the connector certificate package from the AAI server
and copy it to ./secure/
Press ENTER to continue...

*** CONFIGURING CONNECTOR ***

Backing up configuration file to: application.yml.bak...
...Configuration file backed up to: application.yml.bak.

Please enter the following configuration parameters.

Enter AAI server URI (e.g., "https://localhost:4443"): https://TestAAIServer.broadcom.com:4443
Enter connector name: Automic-connector
Enter host name: lvnkdev001361.bpc.broadcom.net
Enter connector key password (will not echo, required for HTTPS):
Enter AAI server username (required for HTTP): admin
Enter AAI server password (will not echo, required for HTTP):
Enter connector domain: lvnkdev001361.bpc.broadcom.net

Verifying AAI server connectivity (please stand by)...
...AAI server connectivity verified.

Saving connector configuration to: application.yml...
...connector configuration saved to: application.yml.

*** CONNECTOR CONFIGURED ***

Converting the Connector from HTTP to HTTPS

If you have configured a Connector for HTTP connection, you can convert it to HTTPS as follows:

Copy the generated .jar file from the AAI connectors directory to the secure directory created in the root level of the Connector installation.

Example

/opt/esp-aai-connector/secure
Re-run the configure-connector (UNIX) or setup.bat (Windows) script respectively.

Troubleshooting

Problem: When running the connector configuration script or the connector itself, errors are observed indicating an issue with certificates.

Solution: Recheck or redo the generation of the key/trust stores and the modifications to the standalone.xml file. Pay particular attention to the items shown in bold in the instructions above.