FlexDeploy HTTPS Agent - Installation Guide

The FlexDeploy HTTP Agent distribution contains the following components:

• A Tomcat 9 server with required libraries, and base configurations

• The Https Agent WAR

Step 1. Ensure Java 8 is installed on the server.

Setting JAVA_HOME in the configuration will be done later. This Java will be used to run the Tomcat server. A different Java version can be specified on the endpoint configuration in FlexDeploy and those will be used to actually execute plugins.

Step 2. Prepare software

Download and unzip the HTTPS Agent software using wget, curl, or manually from the Flexagon website.

# select folder location where the agent will be downloaded
export SOFTWARE_HOME=/u01/software
mkdir -p $SOFTWARE_HOME
cd $SOFTWARE_HOME
wget -O HttpsAgentTomcatComplete.zip https://flexagon.com/downloads/httpsagent

As an alternative to wget you can use curl to download the agent software from the Flexagon website.

curl -L --max-redirs 5 https://flexagon.com/downloads/httpsagent --output HttpsAgentTomcatComplete.zip

Extract the zip file in the desired location (referred to as "HTTPS_AGENT_HOME" in this document).

unzip /u01/software/HttpsAgentTomcatComplete.zip .

Step 3. Configure authentication

Basic Auth

To configure basic auth, use the username and password being stored in tomcat-users.xml.

For basic configuration only, the password needs to be configured in the given HTTPS_AGENT_HOME/apache-tomcat-flexdeploy-https-agent/conf/tomcat-users.xml file. Here’s what that will look like:

<role rolename="FlexDeployHTTPSAgent" />
<user
username="tomcat" 
password="PASSWORD" 
roles="FlexDeployHTTPSAgent" />

Active Directory/LDAP

For LDAP use we will need to change the HTTPS_AGENT_HOME/apache-tomcat-flexdeploy-https-agent/conf/server.xml file. By default it is configured to use a UserDatabase realm instead of the JNDI realm we are looking for.

Start by commenting out the existing UserDatbase realm. Then let’s uncomment the included JNDI realm, that should look like the following:

<!-- Use the LockOutRealm to prevent attempts to guess user passwords
via a brute-force attack -->
<Realm className="org.apache.catalina.realm.LockOutRealm">
  <!-- This Realm uses the UserDatabase configured in the global JNDI
  resources under the key "UserDatabase".  Any edits
  that are performed against this UserDatabase are immediately
  available for use by the Realm.  -->
  <!--<Realm
  className="org.apache.catalina.realm.UserDatabaseRealm"
        resourceName="UserDatabase" />-->
  <!-- user MUST be a part of FlexDeployHTTPSAgent group in order for authentication
  to work -->
  <Realm className="org.apache.catalina.realm.JNDIRealm"
        connectionName="CN=administrator,CN=Users,DC=flexagondev,DC=local"
        connectionPassword="password"
        connectionURL="ldap://yourldapurl.example:389"
        userBase="CN=Users,DC=flexagondev,DC=local"
        userSearch="(&amp;(objectClass=*)(sAMAccountName={0}))"
        userRoleName="member"
        roleBase="CN=Users,DC=flexagondev,DC=local"
        roleName="cn"
        roleSearch="(objectClass=group)"
  />
</Realm>

Next, add the organization specific LDAP/Azure Directory configuration.

Make sure the user you are trying to connect with has the FlexDeployHTTPSAgent role or they will not be able to connect.

For more information about using LDAP/Active Directory see the tomcat documentation how to for realms, and also the configuration reference.

Step 4. Configure SSL

The use of SSL is required. These steps will be for generating and using a self signed certificate. You can of course use any other certificate compatible with Tomcat. See the Tomcat Documentation for more details.

Let’s generate the self signed certificate in the HTTPS_AGENT_HOME/config directory. Run the following command.

keytool -genkey -keyalg RSA -alias tomcat -keystore tomcat.jks -validity 365 -keysize 2048

When prompted enter a password for the keystore.

Then when prompted for your name input the hostname for the server. The rest of the information is not needed (although you can input it).

After that you will be prompted for the password for the tomcat key, press enter to use the same password as the keystore.

Next let’s export the certificate in order to add it to the FlexDeploy server’s trust store.

keytool -export -keystore tomcat.jks -storepass <password> -alias tomcat -file httpsagent.cer

The last thing we need to do on the endpoint is configure the keystore password (and the location of the file if not generated in the config directory). Open up the HTTPS_AGENT_HOME/apache-tomcat-flexdeploy-https-agent/conf/server.xml file. Find the SSL connector (by default set for port 8444) and add the keystore password like this:

<Connector port="8444" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="150" scheme="https" secure="true"
           clientAuth="false" sslProtocol="TLS" SSLEnabled="true"
           keystoreFile="../config/tomcat.jks" keystorePass="KEYSTORE PASSWORD HERE">
</Connector>

Now import the certificate into the java trust store on the FlexDeploy server.

First copy over the certificate that was generated (with the .cer extension).

Next determine the Java install used by the FlexDeploy server.

If JAVA_HOME is set in your setenvoverride.sh file, use that directory.

If it is not set, but it is already set in your system use that value. Run echo "$JAVA_HOME" to find that out.

If it’s not set in setenvoverride.sh or the environment run this command to find the path used dirname $(dirname $(readlink -f $(which javac)))

Then run the following command on the server.

keytool -import -noprompt -trustcacerts -alias tomcat -file httpsagent.cer -keystore "JAVA_INSTALL_PATH/jre/lib/security/cacerts" -storepass <password>

The default password for the java keystore is changeit.

Now the server will be able to connect to the endpoint.

Step 5. Start the server.

Run the StartFlexDeployHttpsAgent.sh (or StartFlexDeployHttpsAgent.bat) script to start the agent.

Next Steps

To manage FlexDeploy properties locally on the endpoint without the need to send them through HTTPS requests to the agent checkout this page.

Create the endpoint on your FlexDeploy server.