Configuring Integration Server to Use Kerberos

Overview of Kerberos Usage in Integration Server

Kerberos is an authentication protocol that uses symmetric encryption and a trusted third party system to validate the identity of clients. The Kerberos protocol provides authentication over open and insecure networks in which communication between the hosts can be intercepted.

You can use Integration Server to enable and configure Kerberos authentication for service requests. Integration Server provides support for using Kerberos authentication with the following types of requests:

Inbound and outbound HTTP and HTTPs requests at the transport level.
Inbound and outbound HTTPS web service requests.

Note: Integration Server currently supports Kerberos authentication for outbound web service requests of transportType HTTPS only.

About Kerberos

Kerberos authentication system consists of the following:

A Kerberos client that needs to access and use Kerberos services.
A trusted third-party system, specifically a key distribution center (KDC).
A server that hosts services that are accessible using Kerberos authentication.

Kerberos authentication consists of the following phases:

Authentication phase. Client authenticates itself to the authentication service and requests a long-term ticket granting ticket (TGT).
Service authorization phase. Client uses the TGT to request a ticket for the specific service it wants to invoke.
Service invocation phase. Client sends the request to invoke the target service, including the service ticket obtained in the service authorization phase. If the server hosting the requested service authenticates the service ticket, the server invokes the requested service.

Kerberos Terminology

Before configuring Integration Server to use Kerberos authentication, you may find it helpful to first understand the following terminology:

Key Distribution Center (KDC). The trusted third party system that provides authentication and ticket granting services and hosts the principal database. That is, the KDC consists of an authorization server, a ticket-granting server, and a database that contains the principals and their keys.
Realm. All the computers that are managed by the KDC and secondary KDCs, if any, constitute the realm. That is, the realm includes all the nodes that share the same Kerberos database.
Principal. A service or user that is known to the Kerberos system. Each Kerberos principal is identified by its principal name. Principal names consist of three parts: a service or user name, an instance name, and a realm name in the following form: principal-name.instance-name@realm-name
Service principal name. The principal name of the service as registered with the principal database.
Keytab file. The file consisting of a set of principals and their passwords. It can contain the principal password encrypted using different encryption algorithms.
Kerberos configuration file. The file that contains configuration information such as Kerberos realm, location of KDC, defaults for the current realm, and encryption algorithms. Generally, this file is named "krb5.conf".
Subject. The user or service that is authenticated by the JAAS login context.

Kerberos Delegated Authentication

Kerberos delegation allows Integration Server to reuse the client credentials to invoke another service which is hosted either on the same or different server. In this case, a principal (delegated user) can invoke a service on behalf of another principal (original requester).

Kerberos delegated authentication comprises the following phases:

Authentication phase. Client authenticates itself to the authentication service and requests a forwardable TGT (delegable token).
Service authorization phase.
1. Using the forwardable TGT the client requests for a service ticket for an intermediary.
2. The intermediary uses the forwardable TGT to request a service ticket for a service on behalf of the original requester.
Note: Ticket is forwardable to any number of intermediaries. Irrespective of the number of intermediaries, the service request is invoked on behalf of the original requester.
Service invocation phase. The intermediary sends the request to invoke the target service, including the service ticket obtained in the service authorization phase (step 2.b).

Example Use Case

Following is an example use case that describes the steps involved in Kerberos delegated authentication.

In this use case, consider the following:

External client, intermediary (Integration Server), and the destination server (.Net Server) share the same KDC.
Alice is a user account which the external client uses to access the service S1 in the intermediary (Integration Server).
Bob is a user account that the intermediary uses to invoke the endpoint service S2 hosted on the .Net server.
Alice invokes S1.

an example use case that describes the steps involved in Kerberos delegated authentication

Settings:

In S1, the input parameter delegation is set to kerberos in http outbound call (pub.client:http).

Steps:

External client contacts KDC and requests for a forwardable TGT and a service ticket (ST1) for Alice.
External client invokes S1 using the forwardable TGT and ST1.
Integration Server receives the token and then validates and extracts the forwardable TGT. Integration Server logs in as Bob and using the forwardable TGT of Alice requests a service ticket (ST2) for S2.
Integration Server invokes the the target service S2 using ST2.
.Net Server contacts KDC and validates ST2. The service then gets invoked.
Integration Server receives the response for S2.
Integration Server forwards the response (success or error) to the external client.

Prerequisites to Configuring Kerberos

Before you configure Integration Server to use Kerberos authentication, you must ensure that:

A working key distribution center (KDC) is set up.
The KDC is configured as an LDAP directory, for authenticating incoming requests with Kerberos tickets.
The KDC is configured as a user directory in Central Users or LDAP so Integration Server can identify and authorize the user that is part of the Kerberos ticket submitted by the client. For more information about Kerberos authentication, see Kerberos Authentication.
The Kerberos client is registered with the principal database of the KDC.
The service that you want to access is registered with the KDC.
A valid Kerberos configuration file is available.

Limitations When Using Kerberos Authentication in Integration Server

Kerberos authentication in Integration Server currently supports only Kerberos login module that is provided by com.sun.security.auth.module.Krb5LoginModule.
Integration Server might overwrite system properties such as javax.security.auth.useSubjectCredsOnly if they are already present in the client systems.
The keytab configuration is certified on JDK 1.7_45 version and above.
Kerberos Delegated Authentication is currently not supported for web service requests.

Configuring Integration Server to Use Kerberos

About this task

Use Integration Server Administrator to enable and configure Integration Server to use Kerberos authentication for inbound and outbound service requests. Integration Server passes this information to the Kerberos login module.

Keep the following information in mind when configuring Kerberos for Integration Server:

Values specified for Realm and Key Distribution Center Host overwrite the default key distribution center (KDC) and realm set in the KDC configuration file specified in the Kerberos Configuration File. Do not specify values for Realm and Key Distribution Center Host if you do not want to overwrite the default KDC and realm in the Kerberos configuration file.
If you specify Key Distribution Center Host, you must also specify Realm, and vice versa.
By default, for outbound requests that require Kerberos authentication ,Integration Server generates a Java Kerberos ticket using the JGSS Kerberos OID. If you need Integration Server to generate a SPNEGO-based Kerberos ticket for outbound requests that use Kerberos authentication, set the watt.security.kerberos.client.useSPNEGO server configuration parameter to true. This instructs Integration Server to generate a SPNEGO token using SPNEGO OID (Object Identifier) for all outbound requests that require Kerberos authentication.

To configure Kerberos authentication

Procedure

Open Integration Server Administrator.
In the Navigation panel, select Security > Kerberos.
Click Edit Kerberos Settings.

On the Security > Kerberos > Edit page, under Kerberos Settings, provide the following information:

In this field...	Specify...
Realm	The domain name of the Kerberos server, in all uppercase letters. All the computers managed by the KDC and secondary KDCs, if any, constitute the realm. Example: `KERBEROS.RNDLAB.LOC` This field is optional. Note: A value specified for Realm overwrites the realm set in the KDC configuration file specified in Kerberos Configuration File.
Key Distribution Center Host	The host name of the machine on which the KDC resides. Example: `lab.kerberos.rndlab.loc` This field is optional. Note: A value specified for Key Distribution Center Host overwrites the default key distribution center set in the KDC configuration file specified in Kerberos Configuration File.
Kerberos Configuration File	The location of the Kerberos configuration file that contains the Kerberos configuration information, including the locations of KDCs, defaults for the realm and for Kerberos applications, and the host names and Kerberos realms mappings.
Use Subject Credentials Only	Specifies whether Integration Server requires a Kerberos V5 Generic Security Services (GSS) mechanism to obtain the necessary credentials from an existing subject set up by the JAAS authentication module. Here, “subject” represents the user or service being authenticated in the JAAS login context. When the Use Subject Credentials Only check box is selected, Integration Server requires a GSS mechanism to obtain the credentials from an existing Subject. Integration Server uses the Ticket Granting Ticket (TGT) stored in the subject to establish a GSS security context. The service ticket is also stored in the subject. When the Use Subject Credentials Only check box is selected, the JVM in which Integration Server runs can use only the credentials found in the Subject in the JAAS authentication module. The JVM cannot use another underlying mechanism to obtain the credentials. When the Use Subject Credentials Only check box is cleared, Integration Server does not require a GSS mechanism to obtain credentials from an existing Subject. Instead, the JVM in which Integration Server runs can use another underlying mechanism of its choice, such as a reading from a protected file on disk, to obtain credentials for the Subject. The JVM first checks the Subject in the JAAS authentication module. If the JVM does not find the credentials in the JAAS Subject, then the JVM uses an alternate credential mechanism to obtain credentials. The Use Subject Credentials Only check box must be selected if you want to use Kerberos authentication for service requests.

Click Save Changes.

Order of Precedence for Principal Name and Password

The Kerberos login module uses the principal name and password to authenticate the principal to the key distribution center (KDC). However, you can specify principal name and password in other locations.

You can specify the principal name in the is_jaas.cnf file, which is the JAAS login configuration file, and the principal password in the keytab file. You must set principal=client_principal_name and useKeyTab=true in the is_jaas.cnf file to use the specific principal name and the corresponding password specified in the keytab file.
Note: If you use this mode to specify the principal, the use of the Kerberos login module is restricted to that principal.
For inbound service requests, you can also specify the principal name and password in the port configuration.
For outbound services requests, you can specify the principal name and password in the pub.client:http service in the clientPrincipal and clientPassword fields in the auth\kerberos document.
For inbound and outbound web service requests, you can also specify the principal name and password in the web service endpoint alias.
For outbound web service requests, you can also specify the principal name and password at run time in the web service connector using the clientPrincipal and clientPassword in the auth\message\kerberosSettings document.

For service requests, Integration Server uses this order of precedence when determining which principal name and password to use:

The principal name in the is_jaas.cnf file and the corresponding password specified in the keytab file.
For inbound service requests, the principal name and password specified in the port configuration, if present.
For outbound service requests, the principal name and password specified in the pub.client:http service, if present.

For web service requests, Integration Server uses this order of precedence when determining which principal name and password to use:

The principal name in the is_jaas.cnf file and the corresponding password specified in the keytab file.
For outbound web service requests, the principal name and password specified at run time in the web service connector, if present.
For inbound and outbound web service requests, the principal name and password specified in the web service endpoint alias, if present.

JAAS Contexts for Kerberos

The is_jaas.cnf file distributed with Integration Server is located in the Integration Server_directory \instances\instance_name\config folder and includes the following JAAS contexts:

IS_KERBEROS_INBOUND for use with inbound requests.
IS_KERBEROS_OUTBOUND for use with outbound requests.

You can use the JAAS contexts supplied in is_jaas.cnf or add your own.

Important: However, the default JAAS login contexts—IS_KERBEROS_INBOUND, IS_KERBEROS_OUTBOUND, IS_Transport, PlatformManagement, WSS_Message_IS, WSS_Transport_IS, and WSS_Transport_ProxyService—should not be deleted from the JAAS configuration file.

Troubleshooting Kerberos Configuration

I receive the following error when I execute the web service connector: org.apache.axis2.AxisFault: Error in building kerberos token.

Possible reasons for this error are:

The format of the JAAS context is incorrect.
There are no Kerberos login modules configured for the specified principal name.
The absolute path of the keytab file specified in the JAAS context is incorrect.
The encryption algorithm in the keytab file is different from the one used by KDC.
The JDK version you are using is lower than JDK 1.7_45. The keytab configuration is certified on JDK 1.7_45 version and above.

I receive the following error when I execute the web service connector: Pre-authentication information was invalid (24) KrbException: Identifier doesn't match expected value (906).

Possible causes for this error are:

The truststore or the keytab file is corrupt. In such cases, Software AG recommends that you recreate these files and place them in a location that is not frequently accessed.
Your system time and the time in the system that hosts the KDC are not the same. The clocks in these two systems cannot be out of sync for by more than 300 seconds, which is the default clockskew.

I receive the following error when I request for Kerberos delegation by setting delegation to kerberos: Kerberos delegatable credentials do not exist.

Possible reasons for this error is: The requestDelegatableToken parameter in pub.client:http service is not set to true.