Providing credentials for outbound requests by using IWA

Set up IBM® Integration Bus to consume a remote service that is secured with Integrated Windows Authentication (IWA). Only IBM Integration Bus running on Windows can consume an IWA-secured service.

Before you begin

Your IBM Integration Bus must be running on the Windows operating system. If it is running on a different operating system, an IWA-secured remote service cannot be consumed.

Your message flow must include one or more of the following nodes:
  • HTTPRequest
  • SOAPRequest
  • RESTRequest
You cannot use the HTTPAsyncRequest, SOAPAsyncRequest, or RESTAsyncRequest nodes to consume a remote service that is secured with Integrated Windows Authentication (IWA). If your message flow includes an HTTPRequest node, you must set the HTTP version property to 1.1 and select Enable HTTP/1.1 keep-alive on the HTTP Settings tab in the Properties view of the node.

A security identity is required for outbound authentication. By default, the identity credentials of the integration node user ID (the serviceUserId parameter that is specified by the mqsicreatebroker command) is sent to the remote service to use for authentication. If you require a specific security identity to be propagated, you must set the appropriate identity credentials in the Properties tree. For more information, see Providing credentials in HTTP requests.

About this task

Use the following commands to set up and manage outbound support for the NTLM, Kerberos, SPNEGO, and SPNEGO-2 protocols, which together are referred to as Integrated Windows Authentication (IWA). By default IWA is enabled.

To consume a remote service that is secured with IWA, run the following command:

mqsichangeproperties integrationNodeName -e integrationServerName -o ComIbmSocketConnectionManager
 -n allowedAuthTypes -v "PropertyValue"
Where:
  • integrationNodeName is the name of the integration node you want to modify.
  • integrationServerName is the name of the integration server on that integration node.
  • PropertyValue is one of the following values:
    IWA
    Allow the integration node to authenticate by using any IWA protocol.
    NTLM
    Allow the integration node to authenticate by using the NTLM protocol.
    Negotiate
    Allow the integration node to authenticate by using the SPNEGO process to negotiate the use of the NTLM or Kerberos protocols.
    Nego2
    Allow the integration node to authenticate by using the SPNEGO-2 process to negotiate the use of the NTLM or Kerberos protocols.
    Basic
    Allow authentication with Basic Authentication.
    All
    Allow authentication with any supported protocol from this list.
    None
    Do not authenticate.
    Multiple values can be given, separated by a semicolon or a space, and these values are not case-sensitive. IBM Integration Bus selects one value from the list of supported IWA protocols by the server, in the following order: Nego2, Negotiate, NTLM.
When security is enabled, the HTTPRequest and SOAPRequest nodes wait for a 401 response from the server that indicates which authentication mechanisms the server supports. The nodes then use the highest supported protocol for the connection, which is selected in the order that is listed previously. When connected, this protocol is used to authenticate pre-emptively until the flow is stopped or the allowedAuthTypes property is changed. To configure any of the protocols to be used pre-emptively, run the following command:
mqsichangeproperties integrationNodeName -e integrationServerName -o ComIbmSocketConnectionManager
 -n preemptiveAuthType -v "PropertyValue"
Where:
  • integrationNodeName is the name of the integration node you want to modify.
  • integrationServerName is the name of the integration server on that integration node.
  • PropertyValue is one of the following values:
    Basic
    Pre-emptively authenticate by using Basic Authentication.
    NTLM
    Pre-emptively authenticate by using the NTLM protocol.
    Negotiate
    Pre-emptively authenticate by using the SPNEGO process to negotiate the use of the NTLM or Kerberos protocols.
    Nego2
    Pre-emptively authenticate by using the SPNEGO-2 process to negotiate the use of the NTLM or Kerberos protocols.
For more advanced scenarios, the following optional configuration properties can also be used with the ComIbmSocketConnectionManager object:
allowNtlmNegotiation='TRUE'
Set to 'FALSE' to prevent NTLM from being negotiated with the SPNEGO and SPNEGO-2 protocols. The default value is 'TRUE'.
negotiateMutualAuth='FALSE'
Set to 'TRUE' if you require mutual authentication when the Kerberos protocol is negotiated. The default value is 'FALSE'.
Note: When IBM Integration Bus is authenticating by using Kerberos, the integration node automatically generates a service principal name (SPN) for the service that is based on the host name for the request. For example, if the URL for the service is http://iib.iibservice/testservice/service1.svc the SPN is assumed to be HTTP/iib.iibservice. If the service exists at a different SPN, use the following local environment overrides to provide an explicit SPN for the service:
HTTP
SET OutputLocalEnvironment.Destination.HTTP.ServicePrincipalName = 'HTTP/iib.iibservice2.com:7800';
REST
SET OutputLocalEnvironment.Destination.REST.Request.ServicePrincipalName = 'HTTP/iib.iibservice2.com:7800';
SOAP
SET OutputLocalEnvironment.Destination.SOAP.Request.Transport.HTTP.ServicePrincipalName = 'HTTP/iib.iibservice2.com:7800';

To check the current outbound authentication setting, run the following command:

mqsireportproperties integrationNodeName -e integrationServerName
 -o ComIbmSocketConnectionManager -r
The following output is displayed within the connector properties:
  • allowedAuthTypes='PropertyValue'
Where PropertyValue is NTLM, Negotiate, Nego2, None, or Basic. If multiple values are set, they are separated by a semicolon.

Examples

Enable all IWA protocols:
mqsichangeproperties IBNODE -e default -o ComIbmSocketConnectionManager
 -n allowedAuthTypes -v "IWA"
Enable NTLM and Negotiate (SPNEGO) protocols:
mqsichangeproperties IBNODE -e default -o ComIbmSocketConnectionManager
 -n allowedAuthTypes -v "NTLM;Negotiate"
Disable all outbound security protocols:
mqsichangeproperties IBNODE -e default -o ComIbmSocketConnectionManager
 -n allowedAuthTypes -v "None"