Kerberos service authentication


The API Gateway can act as a Kerberos service to consume Kerberos tokens sent from a client in 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. Drag and drop this filter on to the policy canvas to configure it. This topic describes how to configure the fields on this filter window.

General settings


Enter an appropriate name for the filter.

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. To add a Kerberos service, right-click the Kerberos Services node, and select Add Kerberos Service. Alternatively, you can add Kerberos Services under External Connections in the Policy Studio tree. For more details, see the Configure Kerberos services topic.

Kerberos standard settings

Complete the following fields on the Kerberos Standard 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 if you expect the Kerberos Service ticket to be contained in the message. You must enter an XPath expression to point to the expected location of the Kerberos token. You can select some default expressions that point to common locations from the list. Otherwise you can add a new XPath expression by clicking the Add button. Similarly, existing XPath expressions can be configured by clicking Edit and Delete. For more details, see Configure XPath expressions.

  • Selector Expression:

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

Message level settings

The Message Level tab allows you to configure settings that adhere to the message-level standards, for example, Kerberos Token Profile and WS-Trust for SPNEGO.

Extract Session Keys:

You must check this check box 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 generates a new symmetric key and wraps 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 (decrypt and verify) multiple requests from the client.

Transport level settings

The options available on the Transport Level 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 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 settings

Complete the following fields on the Advanced SPNEGO 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.