SPNEGO web authentication filter values

The Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) web authentication filter values control different aspects of SPNEGO. Use this page to specify different filter values for each application server.

To view this administrative console page, click Security > Global security. From Authentication, expand Web and SIP Security, and then click SPNEGO web authentication. Under SPNEGO Filters, click New or select a filter to edit.

Host name

Specifies the fully-qualified host name in the Kerberos service principal name (SPN) that is used by SPNEGO to establish a Kerberos secure context.

The host name is the fully qualified form of the hostname. For example, myHostname.austin.ibm.com.

The Kerberos SPN is a string of the form HTTP/<fully qualified hostname>@KERBEROS_REALM. The complete SPN is used with the Java™ Generic Security Service (JGSS) by the SPNEGO provider to obtain the security credential and security context that are used in the authentication process.

Information	Value
Data type:	String

Kerberos realm name

Specifies the name of your Kerberos realm. In most cases, your realm is your domain name in uppercase letters. For example, a machine with the domain name of test.austin.ibm.com might usually have a Kerberos realm name of AUSTIN.IBM.COM.

If you do not specify the Kerberos realm name, then the default realm that is defined in the Kerberos configuration file is used.

Filter criteria

The filtering criteria used by the Java class that is used by SPNEGO.

The com.ibm.ws.security.spnego.HTTPHeaderFilter default implementation class uses this property to define a list of selection rules that represent conditions that are matched against the HTTP request headers to determine whether or not the HTTP request is selected for SPNEGO authentication.

Each condition is specified with a key-value pair, separated from each other by a semicolon. The conditions are evaluated from first to last, as they display in the specified property. If all conditions are met, the HTTP request is selected for SPNEGO authentication.

The key and value in the key-value pair are separated by an operator that defines which condition is checked. The key identifies an HTTP request header to extract from the request and its value is compared with the value that is specified in the key-value pair according to the operator specification. If the header that is identified by the key is not present in the HTTP request, the condition is treated as not being met.

Any of the standard HTTP request headers can be used as the key in the key-value pairs. Refer to the HTTP specification for the list of valid headers. In addition, two keys are defined to extract information from the request, also useful as a selection criterion, which is not available through standard HTTP request headers. The remote-address key is used as a pseudo header to retrieve the remote TCP/IP address of the client application that sent the HTTP request. The request-URL key is used as a pseudo header to retrieve the URL that is used by the client application to make the request. The interceptor uses the result of the getRequestURL operation in the javax.servlet.http.HttpServletRequest interface to construct the web address. If a query string is present, the result of the getQueryString operation in the same interface is also used. In this case, the complete URL is constructed as follows:

String url = request.getRequestURL() + ‘?' + request.getQueryString();

Table 1. Filter conditions and operations .
This table describes the filter criteria conditions and operations.
Condition	Operator	Example
Match exactly	== Arguments are compared as equal.	host==host.my.company.com
Match partially (includes)	%= Arguments are compared with a partial match being valid.	user-agent%=IE 6
Match partially (includes one of many)	^= Arguments are compared with a partial match being valid for one of many arguments specified.	request-url^=webApp1\|webApp2\|webApp3
Does not match	!= Arguments are compared as not equal.	request-url!=noSPNEGO user-agent!=Mac OS X;user-agent!=JavaCrawler
Greater than	> Arguments are compared lexogaphically as greater than.	remote-address>192.168.255.130
Less than	< Arguments are compared lexographically as less than.	remote-address<192.168.255.135

Note: In previous versions of WebSphere Application Server, SPNEGO HTTP header filters were not handling spaces, IP addresses and the != condition properly, but those issues have been fixed in this release.

Information	Value
Data type:	String

Filter class

Specifies the name of the Java class that is used by SPNEGO to select which HTTP requests are subject to SPNEGO authentication. If you do not specify this parameter, the default filter class, com.ibm.ws.security.spnego.HTTPHeaderFilter, is used.

An alternative SPNEGO filter that supports IP address ranges is available in Traditional Webspehere. The default filter com.ibm.ws.security.spnego.HTTPHeaderFilter can be changed to com.ibm.ws.security.spnego.HTTPHeaderFilter2 by specifying the filter class or by specifying the security custom property. For more information, see https://www.ibm.com/support/pages/node/1105311.

Information	Value
Data type	String

SPNEGO not supported error page URL

This choice is optional. It specifies the URL of a resource that contains the content which SPNEGO includes in the HTTP response that is displayed by the browser client application if it does not support SPNEGO authentication.

This property can specify a web (http://) or a file (file://) resource.

If this property is not specified, or the interceptor cannot find the specified resource, the following content is used:

<html><head><title>SPNEGO authentication is not supported</title></head>
<body>SPNEGO authentication is not supported on this client</body></html>;

Information	Value
Data type:	String

NTLM token received error page URL

This property is optional. It specifies the URL of a resource that contains the content which SPNEGO includes in the HTTP response, which is displayed by the browser client application.

The browser client application displays this HTTP response when the browser client sends an NT LAN manager (NTLM) token instead of the expected SPNEGO token during the challenge-response handshake.

If this property is not specified or the interceptor cannot find the specified resource, the following content is used:

<html><head><title>An NTLM Token was received.</title></head>
<body>Your browser configuration is correct, but you have not logged into a supported
Microsoft(R) Windows(R) Domain.
<p>Please login to the application using the normal login page.</html>

This property can specify a web (http://) or a file (file://) resource.

Information	Value
Data type:	String

Enable delegation of Kerberos credentials

Specifies whether the Kerberos delegated credentials should be stored by SPNEGO. It also enables an application to retrieve the stored credentials and to propagate them to other applications downstream for additional SPNEGO authentication.

This option requires the use of the advanced Kerberos credential delegation feature and the development of custom logic by the application developer. The developer must interact directly with the Kerberos KDC to obtain a Kerberos Ticket Granting Service (TGS) using the delegated Kerberos credentials on behalf of the user who originated the request. The developer must also construct the appropriate Kerberos SPNEGO token and include it in the HTTP request to continue the downstream SPNEGO authentication process, including handling additional SPNEGO challenge-response exchange, if necessary.

Note: If this option is enabled (which it is by default), the GSSCredential is not serializable and cannot be propagated to the downstream server. The client Kerberos delegation credential is extracted and the KRBAuthnToken base is created. The KRBAuthnToken contains the client Kerberos delegation and can be propagated to a downstream server.

If you want to propagate the KRBAuthnToken to a downstream server, the client Ticket Granting Ticket (TGT) must contain addressless and forwardable options. If a client TGT is addressed, the downstream server does not have a client GSS delegation credential after it is propagated.

You can extract the client delegation GSSCredential from the KRBAuthnToken by using the KRBAuthnToken.getGSSCredential() method.

Information	Value
Default:	Disabled

Trim Kerberos realm from principal name

This choice is optional. It specifies whether SPNEGO removes the suffix of the principal user name, starting from the @ that precedes the Kerberos realm name. If this attribute is set to true, the suffix of the principal user name is removed. If this attribute is set to false, the suffix of the principal name is retained. The default value used is true.

Information	Value
Default:	Disabled