BW6.X - Security - How to secure the bwagent REST API

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

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 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

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

For example:

. 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

. 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:

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

. Save the file and restart the bwagent

#5 Testing the configuration

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

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

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