Authenticating incoming requests with IWA on Windows

Set up IBM® Integration Bus to use Integrated Windows Authentication (IWA) to secure inbound requests against an integration node on Windows.

Before you begin

Securing an IBM Integration Bus service with IWA modifies the behavior of only the HTTPInput and SOAPInput nodes. For inbound support, IWA requires the HTTP and SOAP nodes to use an embedded (integration server) listener. IWA is not supported by integration node listeners. SOAP nodes use embedded listeners by default, but HTTP nodes use integration node listeners by default. For information on how to switch to an embedded listener, see Switching from an integration node listener to embedded listeners.

If you are using HTTP over SSL (HTTPS), you must set up a public key infrastructure (PKI). For more information, see Setting up a public key infrastructure.

About this task

Use the following commands to set up and manage inbound support for the NTLM, Kerberos, and SPNEGO protocols, which together are referred to as Integrated Windows Authentication (IWA). When IBM Integration Bus is configured to provide an IWA-secured service, the HTTPInput and SOAPInput nodes accept only incoming requests that can be authenticated against the Windows domain controller, or the Kerberos KDC, as appropriate. Any requests that cannot be authenticated are refused by IBM Integration Bus. By default IWA is disabled.

To enable IWA on an integration node running on Windows, run the following command:

mqsichangeproperties integrationNodeName -e integrationServerName -o ConnectorType
 -n integratedWindowsAuthentication -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.
  • ConnectorType is HTTPSConnector for an SSL connection, or HTTPConnector for a non-SSL connection.
  • PropertyValue is NTLM, Negotiate, or Negotiate:Kerberos. Multiple values can be given, separated by a semicolon or a space, and these values are not case-sensitive. The order in which the values are specified, is the order in which they are returned to the client in the HTTP response. To disable IWA, set this property to a blank string.
    NTLM
    Specify this value to use the NTLM protocol.
    Negotiate
    Specify this value to use the Negotiate (SPNEGO) process. This process allows IBM Integration Bus to negotiate the use of the NTLM or Kerberos protocols. If Kerberos is available, it is the preferred protocol.
    Negotiate:Kerberos
    Specify this value to use the Negotiate (SPNEGO) process to negotiate only the use of the Kerberos protocol. If the client cannot support the Kerberos protocol, IBM Integration Bus refuses the connection.
You must restart the integration node, or reload the integration server, for the command to take effect.

To check what the current IWA setting is, run the following command:

mqsireportproperties integrationNodeName -e integrationServerName -o ConnectorType -r
The following output is displayed within the connector properties:
  • integratedWindowsAuthentication='PropertyValue'
Where PropertyValue is NTLM, Negotiate, or Negotiate:Kerberos. If multiple values are set, they are separated by a semicolon. If no value is set, IWA is disabled, and the following output is displayed within the connector properties:
  • integratedWindowsAuthentication=''

Results

When IBM Integration Bus is configured to provide an IWA-secured service, successfully authenticated messages have the client's identity credentials set in the local environment tree of the message flow. In addition, if the Default Propagation security profile is configured, a subset of these identity credentials are set in the Properties folder of the message tree structure. The following table lists the identity credentials set in the local environment tree of the message flow, and the associated subset of identity credentials set in the Properties folder of the message tree structure:
Table 1. List of identity credentials
Local environment tree credentials Properties folder credentials
username (root folder) IdentitySourceType
> fullName

(consisting of realm\username)

  
> username IdentitySourceToken
> realm IdentitySourceIssuedBy
> package  
> spn  
> sid  

Examples

Enable the Negotiate (SPNEGO) protocol for an SSL connection:
mqsichangeproperties IBNODE -e default -o HTTPSConnector
 -n integratedWindowsAuthentication -v "Negotiate"
Enable the NTLM and Negotiate (SPNEGO) protocols for a non-SSL connection:
mqsichangeproperties IBNODE -e default -o HTTPConnector
 -n integratedWindowsAuthentication -v "NTLM;Negotiate"
Disable all protocols for a non-SSL connection:
mqsichangeproperties IBNODE -e default -o HTTPConnector
 -n integratedWindowsAuthentication -v ""

What to do next

Note: If you are authenticating by using the Kerberos protocol, and IBM Integration Bus is receiving messages from a non-Windows client, the client must include the Windows KDC in its Kerberos configuration file (krb5.conf).