Configuring the Connectors for TLS Authentication

For schedulers that connect to the AAI Server over the Universal Connector framework, if you want the Connector to authenticate using a certificate and to verify the server certificate, you have to configure AAI for TLS authentication. This section guides you through the process. The schedulers that use connectors based on the Universal Connector Framework are Airflow, Automic Automation, Control-M, and ESP Workload Automation.

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

You have to carry out the tasks to configure the AAI Server only once. However, after that, you must generate a certificate for each connector that you want to connect to the AAI Server and add the AAI Server’s certificate authority (CA) to the connector's truststore.

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 17 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 main steps:

Generate AAI Server certificate and configure AAI to allow two-way certificate-based authentication over TLS 1.3.

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.3.
Generate client certificates for Connectors to authenticate over two-way TLS 1.3.

Once the AAI Server has been configured to allow certificate-based authentication over TLS 1.3, 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.3 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 truststore 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.3 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.

<AAI_Installation_Directory>/connectors
In a terminal window for your operating system, run the following command:

UNIX: ./generateAaiKey.sh

Windows: generateAaiKey.bat
Enter the following parameters as you are prompted for them:
- 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 can include special characters and spaces.
  
  Because the password is not displayed on the terminal, you have to enter the password twice to ensure that you entered it correctly
The output generated by the script indicates that the key is generated and copied directly to the AAI Server configuration directory <AAI_Installation_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 AAI for TLS Communication with Its Connector

To configure the AAI universal Connector 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:

Enabling the elements where you can providing keystore and truststore passwords
Enabling HTTPS for the TLS communication

Modifying the standalone.xml for a TLS configuration for the AAI universal Connector

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.

If you have not yet done so (for example, when configuring TLS for the AAI Server), 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.
In the <AAI_Installation_Directory>/jboss/standalone/configuration directory, open the standalone.xmlfile in edit mode in an XML or text editing tool.
Enable and specify the keystore filename and password for the Connector keystore with your certificates.
1. Find the <key-store name="connectorKS"> element.
2. Uncomment the entire element by removing the  at the end.
3. In the <credential-reference clear-text="password"> element, replace password with the password for your Connector keystore.
After your changes, the changed <key-store name="connectorKS"> element looks like this, but with your keystore password. The elements in question are in bold and the changed parts are underlined.
```
	<key-store name="connectorKS">
		<credential-reference clear-text="jaws88"/>
		<implementation type="PKCS12"/>
		<file path="aaiconnectorkey.p12" relative-to="jboss.server.config.dir"/>
	</key-store>	
```
Enable and specify the truststore filename and password for the Connector truststore with your certificates.
1. Find the <key-store name="connectorTS"> element.
2. Uncomment the entire element by removing the  at the end.
3. In the <credential-reference clear-text="password"> element, replace password with the password for your Connector truststore.
After your changes, the changed <key-store name="connectorTS"> element looks like this, but with your keystore password. The elements in question are in bold and the changed parts are underlined.
```
	<key-store name="connectorTS">
		<credential-reference clear-text="jaws88"/>
		<implementation type="PKCS12"/>
		<file path="aaiconnectorkey.p12" relative-to="jboss.server.config.dir"/>
	</key-store>	
```
Specify the password for the key manager of the Connector keystore with your certificates.
1. Find the element that starts with <key-manager name="connectorKM".
2. Uncomment the entire element by removing the  at the end.
3. In the <credential-reference clear-text="password"> element, replace password with the password for your Connector keystore.
After your changes, the changed <key-manager name="connectorKM"> element looks like this, but with your key manager password. The elements in question are in bold and the changed parts are underlined.
```
	<key-manager name="connectorKM" key-store="connectorKS">
		<credential-reference clear-text="jaws88"/>
	</key-manager>
```
Enable TLS communication for the Connector by enabling the HTTPS protocol, which is disabled by default.
1. Find the <server name=”default-derver”> element.
2. Three lines below it, uncomment the element that begins with <https-listener name="clientauth-https" by removing the  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 Connector, the changed <server> element looks like this. In this example, HTTPS is enabled for both the AAI Server and the 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"/>
```
Restart the AAI Server for the changes to take effect.

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
  
  This 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 typos. The password can include special characters or spaces.
  
  The script displays confirmation that the certificate signing request was successfully generated.
- 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 TLS communication for the Connector in the AAI Server. For information, see Configuring AAI for TLS Communication with Its Connector.
  
  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 running generateConnectorCert.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.3

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 Automation_Analytics_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 keystore/truststores and the modifications to the standalone.xml file. Pay particular attention to the items shown in bold in the instructions above.