Securing the BWAgent REST API

The BWAgent REST API can be secured via authentication and roles. The BWAgent REST API server can be secured with SSL access.

Enabling Authentication for the BWAgent REST API Using the JAAS Property File

Authentication for the BWAgent REST API is implemented using the JAAS property file login module. Different login module implementations can be used. For more information, see the Jetty documentation at eclipse.org.

Before you begin

Stop the BWAgent if it is running.

Procedure

To enable authentication for the BWAgent REST API,

Navigate to BW_HOME\bin.
Open the bwagent.tra file in an editor and uncomment the following property:
```
java.property.java.security.auth.login.config=%BW_HOME%/config/jaas.login.conf
```
This property points to the location of the JAAS configuration file, which enables the authentication mechanism and, in turn, points to the property file. The property file identifies users, and stores encrypted/obfuscated passwords.
Save the file.

To change the name or location of the default property file, edit the BW_HOME\config\jaas.login.conf file. The default property file for the login module implementation is BW_HOME\config\realm.properties.
```
bwloginmodule {            org.eclipse.jetty.jaas.spi.PropertyFileLoginModule required
    file="../config/realm.properties";
};
```
To change default users or passwords, edit the BW_HOME\config\realm.properties file. Two users are provided by default: admin and bwappnode. The admin user is the default user for access to the BWAgent REST API. The bwappnode user is the default user for the bwappnode process.

Open BW_HOME\config\realm.properties in a text editor. The default contents of the file are outlined below.

Note: The format of this file is: <username>: <password>[,<rolename> ...]
```
admin: CRYPT:adpexzg3FUZAk,adminbwappnode: OBF:1sho1wgi1u9d1x1d1xfj1x191ua51wfg1shu,admin
```
Note: Roles specified in the realm.properties file are different than the TIBCO ActiveMatrix BusinessWorks™ user roles in TIBCO Enterprise Administrator™. For more information about TIBCO Enterprise Administrator user roles for ActiveMatrix BusinessWorks™, see Roles and Permissions.

To create an encrypted or obfuscated password, navigate to the BW_HOME\system\lib\tea folder and use Java with the -cp option to call the Jetty Password utility, passing the password. In this example, the password admin is used. The utility returns the password in a variety of formats.

BW_HOME\system\lib\tea> java -cp jetty-util-<version>.jar org.eclipse.jetty.util.security.Password admin password

2019-10-10 14:19:57.505:INFO::main: Logging initialized @281ms to org.eclipse.jetty.util.log.StdErrLog

password

OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1v

MD5:5f4dcc3b5aa765d61d8327deb882cf99

CRYPT:advwtv/9yU5yQ

Copy the OBF, MD5, or CRYPT password from the output and paste it into the realm.properties file for the username.
Save the file.

To configure the bwappnode user using the BWAgent file,

Open the BW_HOME\config\bwagent.ini file in a text editor and navigate to the Configuration for AppNode to agent communication section.

This provides an alternate configuration mechanism.
Uncomment the bw.agent.appnode.user property and change the default bwappnode username. If you specify a different user for the bw.agent.appnode.user property, you can add the entry to the realm.properties file (with an obfuscated password and role). If you do not add this entry to the properties file, set the password for the user, outlined in the next step.
Uncomment the property bw.agent.appnode.password and change the default password. The password must be able to de-obfuscate. If encrypted, the bwappnode process is unable to decrypt the password. As a result, the AppNode is unable to communicate with the BWAgent REST API and report its status. The status for the AppNode and any applications on that AppNode is displayed as Stopped even though they are running. To create an encrypted or obfuscated password, follow the instructions.

Note: If you specify this password, it is used and the password set in the realm.properties file for the user (if that user exists in the file) is ignored.
Save the file.

The default authentication mechanism is set to Basic. To change the authentication to Digest,

Open the BW_HOME\config\bwagent.ini file in a text editor.
Navigate to the Web server HTTP and HTTPS configuration section of the file and uncomment the bw.agent.bw.auth property. Change the value from BASIC to DIGEST (all caps).
Add a new property called bw.agent.bw.api.auth. Set the value of this property to DIGEST (all caps).
Save the file.

Set the bw.agent.http.authorization property to true in the bwagent.ini file for authentication and authorization.
Restart the BWAgent.

Enabling LDAP Authentication for the BWAgent REST API

Follow these steps to enable LDAP authentication for the BWAgent REST API.

Before you begin

Stop the BWAgent.
Ensure that users are assigned the admin, operator, and user roles in the LDAP server. For more information, see Authorizing Access to the REST API by Role.

Procedure

Navigate to BW_HOME\bin.

Open the bwagent.tra file in an editor and uncomment the following property:

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

Replace the following lines to the %BW_HOME%/config/jaas.login.conf file.

bwloginmodule {
  org.eclipse.jetty.jaas.spi.LdapLoginModule required
  debug="true"
  useLdaps="false"
  contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
  hostname="10.97.106.72"
  port="10389"
  authenticationMethod="simple"
  forceBindingLogin="true"
  userBaseDn="o=tibco"
  userObjectClass="inetOrgPerson"
  userRdnAttribute="uid"
  userIdAttribute="uid"
  userPasswordAttribute="userPassword"
  roleBaseDn="ou=roles,o=tibco"
  roleNameAttribute="cn"
  roleMemberAttribute="uniqueMember"
  customRoleForLDAP=test
  roleObjectClass="groupOfUniqueNames";
};

In the bwagent.ini file, set the property bw.agent.http.authorization to true for LDAP authentication and authorization, and set the property to false to enable authorization for the Custom Group.
Restart the BWAgent.
Open a web browser and go to the URL of the API server. For example, enter the following URL:

http://localhost:8079/bw/v1/agents/info
Enter the correct LDAP username and password credentials in the dialog that displays.

Enabling LDAP Over SSL Authentication for the BWAgent REST API

Follow these steps to enable LDAP over SSL authentication for the BWAgent REST API.

Before you begin

Stop the BWAgent.
Ensure that users are assigned the admin, operator, and user roles in the LDAP server. For more information, see Authorizing Access to the REST API by Role.

Procedure

Navigate to BW_HOME\bin.

Open the bwagent.tra file in an editor and uncomment the following property:

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

Replace the following lines to the %BW_HOME%/config/jaas.login.conf file.

bwloginmodule {
  org.eclipse.jetty.jaas.spi.LdapLoginModule required
  debug="true"
  useLdaps="true"
  contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
  hostname="localhost"
  port="10636"
  bindDn="cn=John Keats,ou=users,o=mojo"
  bindPassword="pass"
  authenticationMethod="simple"
  forceBindingLogin="true"
  userBaseDn="o=mojo"
  userObjectClass="inetOrgPerson"
  userRdnAttribute="uid"
  userIdAttribute="uid"
  userPasswordAttribute="userPassword"
  roleBaseDn="ou=bwgroups,o=mojo"
  roleNameAttribute="cn"
  roleMemberAttribute="uniqueMember"
  roleObjectClass="groupOfUniqueNames";
};

Note: Ensure that the value of the attribute useLdaps is set to true.

For more information about how to import the LDAP SSL certificate into the cacerts keystore file that is shipped with tibcojre, see Importing the LDAP SSL Certificate in the Cacerts Keystore File.
Restart the BWAgent.
Open a web browser and go to the URL of the API server. For example, enter the following URL:

http://localhost:8079/bw/v1/agents/info
Enter the LDAP username and password credentials.

Authorizing Access to the REST API by Role

The REST API supports the following roles: admin, operator, and user. Roles are assigned in the realm.properties file. Multiple roles can be assigned to a single user.

Before you begin

Stop the BWAgent if it is running.

Role	Description	Access to Operations
admin	Full rights: Create, Read, Update, Delete, Lifecycle (default)	All
operator	Read and Lifecycle operations	Start/Stop, GET
user	Read only	GET

Procedure

Navigate to BW_HOME\config and open the realm.properties file. For more information, see Enabling Authentication for the BWAgent REST API.
For each defined user, change the default role as needed.
Save the file and restart the BWAgent.

Securing the REST API Server

The BWAgent REST API server can be secured with an SSL connection.

The SSL connection is configured in the BWAgent configuration file.

Before you begin

Stop the BWAgent if it is running.

Procedure

Open the BW_HOME\config\bwagent.ini file in a text editor and navigate to Web server HTTP and HTTPS configuration.
Comment out the bw.agent.http.port property.
Uncomment the bw.agent.https.port property.

Note: If the bw.agent.http.port property is also set, requests to the HTTP port are automatically rerouted to the HTTPS port.

Uncomment the following properties and add values:

Property	Value	Description
bw.agent.https.truststorepath	String	Path to the trust store file.
bw.agent.https.truststorepassword	String	The password for the trust store.
bw.agent.https.keystorepath	String	Path to the keystore file.
bw.agent.https.keystorepassword	String	Password of the keystore.

Note: If you are using a self-signing certificate, specify CN to be localhost.

Add additional SSL properties to the Web server HTTP and HTTPS configuration section of the bwagent.ini file as needed.

Property	Value	Description
bw.agent.https.allowrenegotiate	true\|false	Set if SSL renegotiation is allowed.
bw.agent.https.certalias	String	Alias of SSL certificate for the connector.
bw.agent.https.keymanagerpassword	Obfuscated password	The password (if any) for the specific key in the keystore.
bw.agent.https.keystoretype	String	The type of the keystore (default "JKS").
bw.agent.https.needclientauth	true\|false	Set to true if SSL needs client authentication.
bw.agent.https.protocol	String	The SSL protocol (default "TLS") passed as the protocol parameter to the `SSLContext.getInstance(String, String)` method.
bw.agent.https.provider	String	The SSL provider name, which, if set, is passed as the provider parameter to the `SSLContext.getInstance(String, String)` method.
bw.agent.https.trustall	true\|false	Set to true if all certificates should be trusted (for example, if there is no Keystore or TrustStore).
bw.agent.https.trustmanagerfactoryalgorithm	String	The algorithm name (default "SunX509") passed to `TrustManagerFactory`. Use the string "TrustAll" to install a trust manager that trusts all.
bw.agent.https.truststoreprovider	String	The provider of the trust store.
bw.agent.https.truststoretype	String	The type of the trust store (default "JKS").
bw.agent.https.ocspresponderurl	String	Location of the OCSP Responder.
bw.agent.https.enablecrldp	true\|false	Set to true to enable CRL Distribution Points support.
bw.agent.https.enableocsp	true\|false	Set to true to enable On-Line Certificate Status Protocol support.
bw.agent.https.crlpath	String	The path to the file that contains the Certificate Revocation List.
bw.agent.https.validatecerts	true\|false	Set to true if SSL certificates have to be validated.
bw.agent.https.validatepeercerts	true\|false	Set to true if the SSL certificates of the peer have to be validated.
bw.agent.https.wantclientauth	true\|false	Set to true if SSL wants client authentication.
bw.agent.https.maxcertpathlength	int	The maximum number of intermediate certificates in the certification path (-1 for unlimited).
bw.agent.https.excludeciphersuites	Comma-separated list of Strings	The list of cipher suite names to exclude from.
bw.agent.https.includeciphersuites	Comma-separated list of Strings	The list of cipher suite names to include.
bw.agent.https.securerandomalgorithm	String	The algorithm name. If set, is passed as the algorithm parameter to `SecureRandom.getInstance(String)` method to obtain the SecureRandom instance, which is then passed to the SSLContext constructor.
bw.agent.https.excludeprotocols	String	Add this property to disable SSL protocols. Disabled SSL protocols are represented in a comma-delimited list.
bw.agent.https.includeprotocols	String	Add this property to enable SSL protocols. Enabled SSL protocols are represented in a comma-delimited list.

Save the file and restart the BWAgent.
Open a web browser and go to the URL of the API server. For example, enter the following URL:

https://localhost:8886/bw/v1/agents/info

Importing the LDAP SSL Certificate in the Cacerts Keystore File

To connect the BWAgent to the LDAP Over SSL server, ensure that the server certificate is imported into the cacerts keystore file.

Before you begin

Ensure that the SSL Certificate has been exported from the LDAP server.

Procedure

Navigate to BW_Home\tibcojre64\1.8.0\lib\security.

# To List Existing Certificates use command :

BW_Home\tibcojre64\1.8.0\lib\security>keytool -list -keystore cacerts

Enter keystore password: changeit

Keystore type: JKS

Keystore provider: SUN

Your keystore contains 5 entries

verisignclass2g2ca [jdk], Aug 25, 2016, trustedCertEntry,

Certificate fingerprint (SHA1): B3:EA:C4:47:76:C9:C8:1C:EA:F2:9D:95:B6:CC:A0:08:1B:67:EC:9D

digicertassuredidg3 [jdk], Aug 25, 2016, trustedCertEntry,

Certificate fingerprint (SHA1): F5:17:A2:4F:9A:48:C6:C9:F8:A2:00:26:9F:DC:0F:48:2C:AB:30:89

verisignuniversalrootca [jdk], Aug 25, 2016, trustedCertEntry,

Certificate fingerprint (SHA1): 36:79:CA:35:66:87:72:30:4D:30:A5:FB:87:3B:0F:A7:7B:B7:0D:54

digicerttrustedrootg4 [jdk], Aug 25, 2016, trustedCertEntry,

Certificate fingerprint (SHA1): DD:FB:16:CD:49:31:C9:73:A2:03:7D:3F:C8:3A:4D:7D:77:5D:05:E4

verisignclass1g3ca [jdk], Aug 25, 2016, trustedCertEntry,

Certificate fingerprint (SHA1): 20:42:85:DC:F7:EB:76:41:95:57:8E:13:6B:D4:B7:D1:E9:8E:46:A5

identrustpublicca [jdk], Aug 25, 2016, trustedCertEntry,

E:\BW\6.4.0\V11\tibcojre64\1.8.0\lib\security>

#### Import LDAP SSL Certificates to cacerts:

BW_Home\tibcojre64\1.8.0\lib\security>keytool -import -keystore cacerts -file <certName>.der

Enter keystore password: changeit

Owner: CN=bwin2k8r264b_52, OU=Directory, O=ASF, C=US

Issuer: CN=ApacheDS, OU=Directory, O=ASF, C=US

Serial number: 15ac649f77e

Valid from: Sun Mar 12 23:10:20 PDT 2017 until: Mon Mar 12 23:10:20 PDT 2018

Certificate fingerprints:

MD5: A4:25:84:6C:63:51:C5:A2:EB:D5:69:2A:74:EE:D3:31

SHA1: F0:9D:0A:26:E3:86:61:CB:62:3F:1F:40:5A:31:F3:BC:0C:C9:C0:B0

SHA256: 82:43:35:95:55:A6:CC:36:BB:C8:9A:6E:9D:55:FF:69:C1:7C:30:B3:EC:79:DA:3E:98:A9:F2:B6:5C:48:B8:28

Signature algorithm name: SHA1withRSA

Version: 1

Trust this certificate? [no]: yes

Certificate was added to keystore

#### Check if the certificate was imported. The number of keystore entries should increase by 1.

BW_Home\tibcojre64\1.8.0\lib\security>keytool -list -keystore cacerts

Enter keystore password:

Keystore type: JKS

Keystore provider: SUN

Your keystore contains 6 entries

verisignclass2g2ca [jdk], Aug 25, 2016, trustedCertEntry,

Certificate fingerprint (SHA1): B3:EA:C4:47:76:C9:C8:1C:EA:F2:9D:95:B6:CC:A0:08:1B:67:EC:9D

digicertassuredidg3 [jdk], Aug 25, 2016, trustedCertEntry,

Certificate fingerprint (SHA1): F5:17:A2:4F:9A:48:C6:C9:F8:A2:00:26:9F:DC:0F:48:2C:AB:30:89

verisignuniversalrootca [jdk], Aug 25, 2016, trustedCertEntry,

Certificate fingerprint (SHA1): 36:79:CA:35:66:87:72:30:4D:30:A5:FB:87:3B:0F:A7:7B:B7:0D:54

digicerttrustedrootg4 [jdk], Aug 25, 2016, trustedCertEntry,

Certificate fingerprint (SHA1): DD:FB:16:CD:49:31:C9:73:A2:03:7D:3F:C8:3A:4D:7D:77:5D:05:E4

verisignclass1g3ca [jdk], Aug 25, 2016, trustedCertEntry,

Certificate fingerprint (SHA1): 20:42:85:DC:F7:EB:76:41:95:57:8E:13:6B:D4:B7:D1:E9:8E:46:A5

identrustpublicca [jdk], Aug 25, 2016, trustedCertEntry,

Certificate fingerprint (SHA1): BA:29:41:60:77:98:3F:F4:F3:EF:F2:31:05:3B:2E:EA:6D:4D:45:FD

utnuserfirstobjectca [jdk], Aug 25, 2016, trustedCertEntry,

BW_Home\tibcojre64\1.8.0\lib\security>

Did you find this helpful?

Yes No