How to secure the bwagent REST API

Emmanuel Marchiset
4 min readNov 5, 2023

While installing a BusinessWorks 6.X configuration an important task not to forget is to secure the bwagent REST API.

This new article explains how to implement this configuration best practice.

#1 Update the bwagent.tra file

. Go to the <TIBCO_HOME>/bw/6.X/bin directory

. Edit the bwagent.tra file

. Uncomment the following line

#java.property.java.security.auth.login.config=%BW_HOME%/config/jaas.login.conf

Extract of the bwagent.tra file

The file pointed by the property is the default JAAS configuration file, it contains a reference to the default bwagent realm properties file.
By default this file is <TIBCO_HOME>/bw/6.X/config/realm.properties

#2 Update the default admin user password in the bwagent realm properties file

. By default the file contains an admin user with a default password (‘admin’)

The default realm.properties file

The format of the file is the following:

<username>: <PASSWORD FORMAT>:<PASSWORD>, <ROLE>

The two default users admin and bwappnode have an ‘admin’ role and can use all methods of the bwagent REST API.

Roles are pre-defined in the bwagent (and independent from the roles managed in the TEA), the available roles are the following: admin, operator & user.

Roles definitions are the following:

  • Users with ‘admin’ role can performs all Operations (Create Domains, Appspaces, Appnodes, Upload/Deploy EAR, Start and Stop and Delete)
  • Users with ‘operator’ role can only read and do lifecycle operations (start/stop components)
  • Users with ‘user’ role only have read access

. Choose a new password (for example ‘Tibco123’)

. Go to the <TIBCO_HOME>/bw/6.X/system/lib/tea folder

. Use Java with the -cp option to call the Jetty password utility

This can be done with the following:

java -cp jetty-util-<version>.jar org.eclipse.jetty.util.security.Password <username> <password>

For example (in BW 6.8.1 with TEA 2.4.1) :

java -cp jetty-util-9.4.44.v20210927.jar org.eclipse.jetty.util.security.Password admin Tibco123

Using Jetty Java method to encrypt / obfuscate a password

. Update the bwagent realm properties file with the new password (using the CRYPT format)

For example:

An updated realm.properties file

. Save the file and restart the bwagent (if you want to test the change)

#3 Update the default bwappnode password in the bwagent realm properties file

. By default the file contains a bwappnode user with a default password

The default realm.properties file

. Choose a new password (for example ‘AppNode123’)

. Encrypt the new password as explained above for the admin user

. Update the bwagent realm properties file with the new password (using the format of your choice but the CRYPT format is the most secure)

For example:

An updated realm.properties file

There is nothing more to do while this is the bwagent sharing the password to use with the appnode.

. Save the file and restart the bwagent (if you want to test the change)

#4 Create additional users (if needed)

In case the bwagent REST API would be used for other purposes, like monitoring the configuration or doing basic administration tasks, additional users can be created and set to a role supporting the minimum needed access rights.

To create a user with read only access to the bwagent REST API you can do the following:

. Choose a name and a password (for example monitor and ‘Mon123’)

. Encrypt the new password as explained above for the admin user

. Add a line for the new user in the bwagent realm properties file

For example:

monitor: CRYPT: mo12/2gQkJ3v.,user

An updated realm.properties file

. Save the file and restart the bwagent

#5 Testing the configuration

Example of the admin user calling the agent/refresh method:

Calling the agent/refresh method using the admin user

Example of the monitor user calling the browse/appspaces method:

Calling the browse/appspaces method using the monitor user

Additional elements

The BusinessWorks MAVEN plugin must use a user with the ‘admin’ role.

Additional configuration options are available to:

. Use a Digest authentication instead of a Basic authentication

. Connect the bwagent to an Enterprise Directory using LDAP or LDAPS

. Configure the bwagent to expose its REST API over HTTPS

All these options are detailled in the BusinessWorks documentation.

Reference elements

Reference elements about securing the bwagent REST API are available in the BusinessWorks administration guide in the ‘Securing the bwagent REST API’ section:

https://docs.tibco.com/pub/activematrix_businessworks/6.10.0/doc/html/Default.htm#administration/securing-the-bwagent.htm

--

--

Emmanuel Marchiset

I work as an Architect at TIBCO Software on Integration products. Opinions here are my own.