Kerberos Service Authentication


The API Gateway can act as a Kerberos Service to consume Kerberos tokens sent from a client in either the HTTP header or in the message itself. The client must have obtained a ticket from the Ticket Granting Server (TGS) for this Service.

The Kerberos Service Authentication filter is available from the Authentication category of filters. Drag and drop this filter on to the Policy Editor to configure this filter. The sections below describe how to configure the fields on this filter screen.

Kerberos Service

The Kerberos Service selected in this field is responsible for consuming the client's Kerberos token. The client must have obtained a ticket for the service's Principal name to be able to use the service.

Click the button on the right, and select a previously configured Kerberos Service in the tree. To add a Kerberos Service, right-click the Kerberos Services tree node, and select Add Kerberos Service. Alternatively, you can add Kerberos Services under the External Connections node in the Policy Studio tree view. For more details, see the Kerberos Services topic.

Kerberos Standard

Complete the following fields on this tab.

Kerberos Standard:

You must first select one of the following Kerberos standards:

  • Kerberos Token Profile

  • WS-Trust for SPNEGO

  • SPNEGO over HTTP

[Note] Note

The Kerberos Service Authentication filter is used to consume the Kerberos client-side token regardless of whether the token is sent at the message layer (in the SOAP message), or at the transport layer (in an HTTP header).

Client Token Location for Message-Level Standards:

The Kerberos Service ticket can be sent in the Authorization HTTP header or inside the message itself (for example, inside a <BinarySecurityToken> element). Alternatively, it may be contained within a message attribute. Select one of the following options:

  • Message Body:

    Select this option if you expect the Kerberos Service ticket to be contained within the XML message. You must enter an XPath expression to point to the expected location of the Kerberos token.

    Some default expressions that point to common locations are available for selection from the dropdown. Otherwise you can add a new XPath expression by clicking the Add button. Similarly, existing XPath expressions can be configured by clicking the Edit and Delete buttons, respectively. Please refer to the Configuring XPath Expressions for more information on configuring XPath expressions.

  • Message Attribute:

    When using the WS-Trust for SPNEGO standard above, the Consume WS-Trust filter will place the client-side Kerberos token inside the message attribute.

Message Level

This section allows you to configure settings that adhere to the message-level standards, i.e. Kerberos Token Profile and WS-Trust for SPNEGO.

Extract Session Keys:

You must check this checkbox if you want to use the Kerberos/SPNEGO session keys to perform a signing or encryption/decryption operation in a subsequent filter. This option is only available when the token is extracted from the message body.

WS-Trust Settings: Key Length:

When using WS-Trust for SPNEGO, the Kerberos Service Authentication filter will generate a new symmetric key and wrap it using the Kerberos session key. This setting determines the length of the new symmetric key.

WS-Trust Settings: Cache Security Context Session Key:

The service-side may need to cache the session key in order to process (i.e. decrypt and verify) multiple requests from the client.

Transport Level

The options available in this section are specific to Kerberos tokens received over HTTP and are only relevant when the SPNEGO Over HTTP option is selected above.

Cookie Name:

The initial handshake between a Kerberos Client and Service can sometimes involve the exchange of a series of request and responses until the secure context has been established. In such cases, an HTTP cookie can be used to keep track of the context across multiple request and response messages. Enter the name of this cookie in the field provided.

Allow Client Challenge:

In some cases, the client may not authenticate (send the Authorization HTTP header) to the Kerberos Service on its first request. The Kerberos Service should then respond with an HTTP 401 response code, instructing the client to authenticate to the server by sending up the Authorization header. The client then sends up a second request, this time with the Authorization header, which contains the relevant Kerberos token. Check this option if you want to allow this type of negotiation between the client and service.

Client Sends Body Only After Context is Established:

The Kerberos client may wait to mutually authenticate the Kerberos service before sending the body of the message. If this setting is enabled, the Kerberos service will accept the body after the context has been established if the client provides the known cookie. The cookies are cached in the configured cache.

Advanced SPNEGO

Complete the following fields on this tab:

Cache Partially Established Contexts:

In theory, the Kerberos client and service may need to send and receive a number of tokens between each other in order to authenticate to each other. In this case, the Kerberos Service Authentication filter will need to cache the partially established context for each client. The contexts will only be cached during the establishment of the context.

In practice however, a single client-side Kerberos token is normally enough to establish a context on the service-side, in which case this setting is not required. This setting applies to the WS-Trust for SPENGO and SPENGO over HTTP standards only.