BW 6.X - BWCE - Security - How to use Basic Authentication in BusinessWorks and BusinessWorks Container Edition

Authentication is one of the key security principles (with Confidentiality, Integrity, Access control and Availability) and a simple way to implement it in a REST or SOAP context is to use the HTTP Basic Authentication.

This article aims to explain how to limit the access to a REST API or a SOAP Service exposed by a BusinessWorks server application to only authenticated users and add role based Authorizations if needed. It also explains how to include user credentials when invoking a REST API or a SOAP Service in a BusinessWorks client application.

Limiting the access to a REST API or a SOAP Service exposed by a BusinessWorks server application

The general approach is the following:
. Create a Basic Authentication Policy
. Configure the Policy to check the provided user credentials either using a local file in XML format or using an LDAP Directory server
. Assign the Policy to the REST or SOAP Binding

The detailed approach is the following:

. Right click on the ‘Policies’ folder and select ‘Policy’ to create a new Policy

. The following dialog appears:

Select the following options:

- ‘HTTP Security -> Basic Authentication’

- Policy Defaults, it can be one of the following:

(In the remaining part of the article we will use an XML file in the file system)

- Optionally change the Policy Name from the default and check the ‘Create module properties for common fields’ option to have properties automatically created

. Check the created Policy (no change should be needed)4

. Open the created ‘XML authentication’ resource and set the path to the XML file

In this example we use a file located in the local file system selected using the ‘Browse File System’ option, in a production environment the file path should be managed using a property.

. Create the xml file using the following syntax

When the XML file is managed in the local file system the passwords will be obfuscated at the first authentication attempt.

If using an XML file managed in the workspace, which might be convenient in a Container environment, or if required because of security requirements, the XML file can be encrypted using one of the two following approaches:

- Temporarily configure the XML Authentication resource to point to the target xml file using the full file path (that can be entered using the ‘Browse File’ option), run the application in Studio and invoke the REST API at least once

- Use a ‘hashpassword’ utility available from TIBCO support (you will need to open a Service Request to ask for it)

After obfuscation of the passwords the file will look like this :

For more details about the XML file format you can refer to the following documentation:
https://docs.tibco.com/pub/api-exchange-gateway/2.2.0/doc/html/GUID-595E392F-7FF9-43C4-BAD3-CCE3077D980D.html

. Finally you have to assign the Policy to the Binding, open the Binding and click ‘Add Policy’

This can be done for both REST Bindings or SOAP Bindings.

Then select the Policy previously created and click ‘OK’ :

The Binding should now look like this:

The Policy we assigned applies to all operations (all resources) of the target REST API or SOAP Service.

. The policy can be tested using the Authorization tab in Postman (with Type ‘Basic Authentication’)

Important:

#1 In the runtime environment for the Policies to be applied the target appspace or its appnodes should be configured with the following property (enabled by default in the debugger environment):
bw.governance.enabled=true

#2 This is important to keep in mind that what we implemented above is an authentication policy, in other words all APIs or SOAP Services using the same basic authentication policy, or the same XML file, or the same LDAP Directory, will be accessible to an authenticated user.

It is possible to add role based authorizations in the Policy by creating groups of users in the XML file (see the documentation mentioned above) or in the LDAP directory and configuring the ‘Authorization’ tab using those groups (for example you can create a group ‘SalesFrontEnd’ and only authorize this group to access the ‘AddOrder’ REST API).

Invoking a REST API or a SOAP Service with Basic Authentication credentials in a BusinessWorks client application

Two approaches can be used:

. Use of an Identity provider

. Creation of the Basic Authentication Authorization header at runtime in a mapping

The first approach is implemented by creating an Identity Provider resource and configuring the HTTP Client resource to use this Identity.

. Create an Identity Provider resource and enter the credentials (username and password) you want to use, the use of properties is recommended

. Enable the ‘Authentication’ option and assign the Identity provider to the HTTP Client resource

This approach can be used with a REST Reference Binding, an ‘Invoke REST API’ activity or a SOAP Reference Binding.

The other approach is to create the Basic Authentication Authorization Header in a mapping.

For the ‘Invoke REST API’ activity this can be done using the following mapping:

The xpath expression to use is the following (note that the password should be in clear — in the case it is managed in a property it should be of type String):
concat(“Basic “, tib:string-to-base64(concat($Username,”:”, “password”)))

Using this approach it is possible to dynamically set the user and password.

It is also possible to use this approach while using a REST Reference Binding or a SOAP Reference Binding by using a Context and using the approach explained in this article:
https://medium.com/@emarchiset/how-to-access-http-headers-while-exposing-or-invoking-web-services-in-businessworks-6-x-1be1d7fd14a5

Summary

It is possible in BusinessWorks to limit the access to a REST API or a SOAP Service exposed by a BusinessWorks server application to only authenticated users and to include user credentials when invoking a REST API or a SOAP Service in a BusinessWorks client application.

The Basic Authentication Policy can be extended to manage role based authorizations.

Additional elements

Example of an XML file with only users:

<?xml version="1.0" encoding="UTF-8"?>
<realm xmlns="http://xsd.tns.tibco.com/trinity/realm/2013" hashAlgorithm="PBKDF2WithHmacSHA256" repetitionCount="128">
<users>
  <user>
     <name>user1</name>
     <!--specify the password as follows using the <plaintext> element.
     The code will replace <plaintext/> with <password salt=…>hash</password>
     in the file on the first authentication attempt> -->
     <plaintext>password</plaintext>
  </user>
  <user>
     <name>user2</name>
     <plaintext>Hello</plaintext>
  </user>
</users>
</realm>

Example of an XML file with users and a group:

<?xml version="1.0" encoding="UTF-8"?>
<realm xmlns="http://xsd.tns.tibco.com/trinity/realm/2013" hashAlgorithm="PBKDF2WithHmacSHA256" repetitionCount="128">
<users>
  <user>
     <name>user1</name>
     <!--specify the password as follows using the <plaintext> element.
     The code will replace <plaintext/> with <password salt=…>hash</password>
     in the file on the first authentication attempt> -->
     <plaintext>password</plaintext>
  </user>
  <user>
     <name>user2</name>
     <plaintext>Hello</plaintext>
  </user>
</users>
<group-mapping>
      <group-name>SalesFrontEnd</group-name>
      <user-name>user1</user-name>
   </group-mapping>
</realm>

An article explaining how to use Basic Authentication in BusinessWorks 5.X is available here:
https://community.tibco.com/articles/tibco-activematrix-businessworks/bw5x-security-how-to-use-http-basic-authentication-in-businessworks-5x-r3351/

Additional elements

You can refer to the attached project.

BasicAuthenticationDemo.zip