Authenticating incoming requests with IWA on Linux or UNIX

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

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 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 Kerberos KDC. Any requests that cannot be authenticated are refused by IBM Integration Bus. To configure IBM Integration Bus on Linux or UNIX to use IWA, you must both configure Kerberos on your system, and enable IWA. By default IWA is disabled.

Procedure

If your Key Distribution Center (KDC) is on a Windows system, export a keytab that contains the private key of the service principal from the KDC.
For example:
```
ktpass -out c:\Windows\krb5.keytab -princ SomePrincipal@YourDomain
 -crypto RC4-HMAC-NT mapUser Username -pass Password -mapOp set 
```
where

out filename

Specifies the name and path of the keytab file to be generated.

princ principal_name

Specifies the principal name.

crypto encryption_type

Specifies the encryption type.

mapUser username

Maps the name of a Kerberos principal to a local account.

pass password

Specifies the password to use for this principal name.

mapOp attribute

Defines how the mapping attribute is set. The attribute alternatives are either add or set.
If your Key Distribution Center (KDC) is on a Linux or UNIX system, refer to the KDC documentation for instructions on creating a keytab for the service principal.
Copy the keytab file to the server that hosts the service. You can copy the file to the server by exporting the keytab file and transferring it to the server, for instance by using FTP. The Kerberos configuration file contains a reference to the keytab file in the form of a file URL (such as: /home/user/my.keytab).
Because the reference is in the configuration file on the server, the server service can take on the Kerberos principal that is defined in the keytab.
Create a Kerberos configuration file that specifies the location of the keytab file on the local workstation.
You can use more than one service principal name per integration node per Kerberos realm. Use your workstation default Kerberos configuration file when you are using Kerberos for security. The location for the configuration file differs depending on the system. The usual locations are:
- Linux: /etc/krb5.conf
- UNIX: /etc/krb5/krb5.conf
- z/OS®: /krb5/krb5.conf
Different Kerberos configuration files can be configured for use by the integration node and integration servers.
The following sample Kerberos configuration file shows typical values for the variables. The variables default_realm, default_keytab_name, and the names in the realms are among the values you change in the configuration file, depending on your network and location of the configuration file.
```
[libdefaults]
default_realm = MYREALM.EXAMPLE.COM
default_keytab_name = FILE:c:\Windows\krb5.keytab
default_tkt_enctypes = rc4-hmac
default_tgs_enctypes = rc4-hmac
dns_lookup_realm = false
dns_lookup_kdc = false
ticket_lifetime = 24h
renew_lifetime = 7d
forwardable = true
[realms]
MYREALM.EXAMPLE.COM = {
kdc = kdc.myrealm.example.com
admin_server = kdc.myrealm.example.com
}
```

Use one of these mqsichangeproperties commands to specify the location of your new configuration file.

For an integration node level Kerberos configuration:

mqsichangeproperties integrationNodeName -o BrokerRegistry 
-n brokerKerberosConfigFile -v kerberosConfigLocation

For an integration server level Kerberos configuration:

mqsichangeproperties integrationNodeName -e integrationServerName 
-o ComIbmJVMManager -n brokerKerberosConfigFile -v kerberosConfigLocation

To enable IWA on an integration node running on Linux or UNIX, run the following command:
```
mqsichangeproperties integrationNodeName -e integrationServerName -o ConnectorType
 -n integratedWindowsAuthentication -v "PropertyValue"
```
Where:
- integrationNodeName is the name of the integration node 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 Negotiate:Kerberos, and is not case-sensitive. To disable IWA, set this property to a blank string.
  
  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 Negotiate:Kerberos. 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 will 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 Kerberos protocol for a non-SSL connection:

mqsichangeproperties IBNODE -e default -o HTTPConnector
 -n integratedWindowsAuthentication -v "Negotiate:Kerberos"

Disable IWA for an SSL connection:

mqsichangeproperties IBNODE -e default -o HTTPSConnector
 -n integratedWindowsAuthentication -v ""