configureBPMTransportSecurity command

Edit online

Use the configureBPMTransportSecurity command to list and toggle HTTPS protocol enforcement for a set of Business Automation Workflow URLs.

If secure connections are used, IBM® BPM marks the cookies as secure. However, if you re-enable non-secure http:// access to IBM BPM, you might need to disable the Secure flag for IBM BPM cookies by setting the deployment-level custom property ProcessServer.MarkCookiesSecureOnSecureConnections to false. To set the property to false, you can use the following command (which assumes that your deployment environment is named De1): 
AdminTask.setBPMProperty(['-de', 'De1', '-name', 'ProcessServer.MarkCookiesSecureOnSecureConnections', '-value', 'false'])"
Tip: If you switched URLs to the non-secure HTTP protocol, then the profile upgrade that occurs during the first server startup after applying an Business Automation Workflow cumulative fix will switch the URLs back to secure HTTPS. You will need to re-run the configureBPMTransportSecurity command to continue to use non-secure HTTP.

The configureBPMTransportSecurity command is run using the AdminTask object of the wsadmin scripting client.

Prerequisites

This command reconfigures web deployment descriptors and then redeploys affected applications. As a result, the following conditions must be met:

  1. In a network deployment environment, run the command on the deployment manager node. In a single-server environment, run the command on the stand-alone server.
  2. Stop all servers in your deployment environment. In an ND topology, this includes the deployment manager and the node agents.
  3. Run the command in disconnected mode by using the wsadmin -conntype none option.
  4. Restart all servers in your deployment environment to pick up the configuration changes.

Location

Start the wsadmin scripting client from the profile_root/bin directory. The configureBPMTransportSecurity command does not write to a log file, but the wsadmin scripting client always writes a profile_root/logs/wsadmin.traceout log file where you will find exception stack traces and other information.

Note: When you run this command, the wsadmin.traceout file will display several warning messages that are similar to the following message, but you can safely ignore them:
[3/15/17 13:07:50:879 CST] 00000041 annotations 
W com.ibm.ws.amm.scan.context.ScannerContextImpl getInputDataForClass 
Failed to open resource [ org/apache/struts/taglib/bean/StrutsTag.class ]
from module [ webviewer.war ]

Syntax

configureBPMTransportSecurity
[-de deployment_environment_name]
-apps configuration_scope
-transportSecurity configuration_mode

Parameters

-de deployment_environment_name
An optional parameter that specifies the name of the current deployment environment. If there is only one deployment environment in the WebSphere® cell, you can omit this parameter.
-apps configuration_scope
A required parameter that specifies the scope of the configuration. The valid values are:
  • productREST: REST APIs provided by Business Automation Workflow.
  • productSOAP: SOAP APIs provided by Business Automation Workflow.
  • customSOAP: SOAP web services in custom (.twx) applications.
  • bspace: Web applications related to Business Space and Heritage Process Portal.
    Restriction: Heritage Process Portal is deprecated.
  • 201612: All other changes that are relative to cumulative fix 2016.12.
  • 18001: IBM Content Navigator and case management features introduced in 25.x.
-transportSecurity configuration_mode
A required parameter that specifies the mode of the configuration. The valid values are:
  • list: Display the current configuration.
  • httpsonly: Switch the transport-guarantee setting to CONFIDENTIAL to enforce a redirect to HTTPS.
  • allowhttp: Switch the transport-guarantee setting to NONE to allow non-secure HTTP traffic. If you enable non-secure HTTP and access any of the browser-targeted web user interfaces using an HTTP URL, you need to ensure that URLs pointing to Business Automation Workflow are calculated using an HTTP prefix to avoid mixed content in the browsers. The useHTTPSURLPrefixes flag determines the protocol of self-referential URLs in case no other strategy is configured, as described in the topic Configuring Secure Sockets Layer (SSL) communication in a network deployment environment.

Examples

Note: The examples are for illustrative purposes only. They include variable values and are not meant to be reused as snippets of code.
The following Jython example uses the configureBPMTransportSecurity command to ensure non-secure HTTP access for IBM BPM REST APIs in the deployment environment De1:
print AdminTask.configureBPMTransportSecurity( [ '-de', 'De1', '-apps', 'productREST', '-transportSecurity', 'allowhttp'] )
The following Jython example uses the configureBPMTransportSecurity command to enforce HTTPS for SOAP clients that are calling IBM BPM product APIs in the deployment environment De1:
print AdminTask.configureBPMTransportSecurity( [ '-de', 'De1', '-apps', 'productSOAP', '-transportSecurity', 'httpsonly'] )
The following Jython example uses the configureBPMTransportSecurity command to enforce HTTPS for SOAP clients that are calling custom web services in the deployment environment De1:
print AdminTask.configureBPMTransportSecurity( [ '-de', 'De1', '-apps', 'customSOAP', '-transportSecurity', 'httpsonly'] )
The following Jython example uses the configureBPMTransportSecurity command to view the current configuration for all other modified web modules that are not covered by the productREST scope, productSOAP scope, or customSOAP scope:
print AdminTask.configureBPMTransportSecurity( [ '-de', 'De1', '-apps', '201612', '-transportSecurity', 'list'] )
When switching back to non-secure HTTP access for browser user interfaces, you must ensure that cookies can be sent over non-secure connections and that IBM BPM calculates HTTP URLs. The following Jython example uses the configureBPMTransportSecurity command and other commands to perform the required configuration:
wsadmin> print AdminTask.configureBPMTransportSecurity( [ '-de', 'De1', '-apps', 'productREST', '-transportSecurity', 'allowhttp'] )
wsadmin> AdminTask.configureSingleSignon('-requiresSSL false')
wsadmin> for server in AdminUtilities.convertToList(AdminTask.listServers( '-serverType APPLICATION_SERVER' )):
wsadmin>     for cookie in AdminUtilities.convertToList(AdminConfig.list('Cookie', server)):
wsadmin>         AdminConfig.modify(cookie, [['secure','false']])
wsadmin>
wsadmin> AdminConfig.save()

In this example, the fourth line must be indented one level and the fifth line must be indented two levels. You should use at least one blank for each level. The sixth line is a required empty line to end the loop and you can just press the Enter key.