Securing the bwagent REST API

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.

1. To enable authentication for the bwagent REST API,
   1. Navigate to BW_HOME\bin.
   2. 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.

   3. Save the file.
2. 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";
   };

3. 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.
   1. 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,admin
      bwappnode: 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.
   2. 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

   3. Copy the OBF, MD5 or CRYPT password from the output and paste it into the realm.properties file for the user name.
   4. Save the file.
4. To configure the bwappnode user using the bwagent file,
   1. Open the BW_HOME\config\bwagent.ini file in a text editor and navigate to the section called "Configuration for AppNode to agent communication."
      This provides an alternate configuration mechanism.
   2. Uncomment the bw.agent.appnode.user property and change the default bwappnode user name. 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.
   3. Uncomment the property bw.agent.appnode.password and change the default password. The password must be able to be de-obfuscated. If encrypted, the bwappnode process will not be able to decrypt the password. As a result, the AppNode will not be able to communicate with the bwagent REST API and will be unable to report its status. The status for the AppNode and any applications on that AppNode will display as Stopped even though they may be running. To creating an encrypted or obfuscated password, follow the instructions.
      Note: If you specify this password, it will be used and the password set in the realm.properties file for the user (if that user exists in the file) will be ignored.
   4. Save the file.
5. The default authentication mechanism is set to Basic. To change the authentication to Digest,
   1. Open the BW_HOME\config\bwagent.ini file in a text editor.
   2. 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).
   3. Add a new property called bw.agent.bw.api.auth. Set the value of this property to DIGEST (all caps).
   4. Save the file.
6. Set the bw.agent.http.authorization property to true in the bwagent.ini file for authentication and authorization.
7. Restart the bwagent.

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

1. Navigate to BW_HOME\bin.
2. 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

3. 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";
   };
   };

4. 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 Custom Group.
5. Restart the bwagent.
6. 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
7. Enter the correct LDAP user name and password credentials in the dialogue box that displays.

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

1. Navigate to BW_HOME\bin.
2. 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

3. 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"
4. For more information about how to import the LDAP SSL certificate into the cacerts keystore file that is shipped with tibcojre, see the section Importing LDAP SSL Certificate in the cacerts keystore file.
5. Restart the bwagent.
6. 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
7. Enter the LDAP user name and password credentials.

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.

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

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

1. Open the BW_HOME\config\bwagent.ini file in a text editor and navigate to the section called "Web server HTTP and HTTPS configuration."
2. Comment out the bw.agent.http.port property.
3. 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.
4. 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.
5. 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 re-negotiation 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 (e.g. 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 enables CRL Distribution Points support.
   bw.agent.https.enableocsp	true|false	Set to true to enables On-Line Certificate Status Protocol support.
   bw.agent.https.crlpath	String	The path to the file that contains 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 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.

6. Save the file and restart the bwagent.
7. 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

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

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