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 broker listeners. SOAP nodes use embedded listeners by default, but HTTP nodes use broker listeners by default. For information on how to switch to an embedded listener, see Switching from a broker-wide 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.
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.
- 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 principle name per broker 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 broker 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 a broker level Kerberos configuration:
mqsichangeproperties brokerName -o BrokerRegistry -n brokerKerberosConfigFile -v kerberosConfigLocation
- For an integration server level Kerberos configuration:
mqsichangeproperties brokerName -e integrationServerName -o ComIbmJVMManager -n brokerKerberosConfigFile -v kerberosConfigLocation
- To enable IWA on a broker running
on Linux or UNIX, run the following
command:
mqsichangeproperties broker_name -e IntegrationServerName -o ConnectorType
-n integratedWindowsAuthentication -v "PropertyValue"
Where:
- broker_name is
the name of the broker to
modify.
- IntegrationServerName is the name of the integration server on that broker.
- 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 broker,
or reload the integration server, for the command to take
effect.
To check what the current IWA setting is, run the following
command:
mqsireportproperties broker_name -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=''
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 credentialsLocal 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 IB9NODE -e default -o HTTPConnector
-n integratedWindowsAuthentication -v "Negotiate:Kerberos"
Disable IWA for an SSL connection:
mqsichangeproperties IB9NODE -e default -o HTTPSConnector
-n integratedWindowsAuthentication -v ""