SPNEGO TAI custom properties configuration

The Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) trust association interceptor (TAI) custom configuration properties control different operational aspects of the SPNEGO TAI. You can specify different property values for each application server.

Each of the properties defined in the following table is specified in the Custom Properties panel for the SPNEGO TAI using the administrative console facility. For convenience, you can optionally place these properties in a properties file. In this case, the SPNEGO TAI loads the configuration properties from the file instead of the Custom Properties panel definition. Refer to com.ibm.ws.security.spnego.propertyReloadFile property as defined in SPNEGO TAI JVM configuration custom properties.

To assign unique property names that identify each possible SPN, an SPN<id> is embedded in the property name and used to group the properties that are associated with each SPN. The SPN<id>s are numbered sequentially for each property group.

Table 1.
Property Name Required Default Value
com.ibm.ws.security.spnego.SPN<id>.hostName Yes None
com.ibm.ws.security.spnego.SPN<id>.filterClass No See the description that follows.
com.ibm.ws.security.spnego.SPN<id>.filter No See the description that follows.
com.ibm.ws.security.spnego.SPN<id>.enableCredDelegate No false
com.ibm.ws.security.spnego.SPN<id>.spnegoNotSupportedPage No See the description that follows.
com.ibm.ws.security.spnego.SPN<id>.NTLMTokenReceivedPage No See the description that follows.
com.ibm.ws.security.spnego.SPN<id>.trimUserName No true
com.ibm.ws.security.spnego.SPN<id>.hostName
This property is required. It specifies the hostname in the SPN used by the SPNEGO TAI to establish a Kerberos secure context.
Note: The hostname is the long form of hostname. For example, myHostName.austin.ibm.com.
The Kerberos SPN is a string of the form HTTP/hostname@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.
com.ibm.ws.security.spnego.SPN<id>.filterClass
This property is optional. It specifies the name of the Java class that is used by the SPNEGO TAI to select which HTTP requests are subject to SPNEGO authentication. If no class is specified, the default com.ibm.ws.security.spnego.HTTPHeaderFilter implementation class is used. The Java class that is specified must implement the com.ibm.wsspi.security.spnego.SpnegoFilter interface. A default implementation of this interface is provided. Specify the com.ibm.ws.security.spnego.HTTPHeaderFilter class to use the default implementation. This class uses the selection rules specified with the com.ibm.ws.security.spnego.SPN<id>.filter property.
com.ibm.ws.security.spnego.SPN<id>.filter
This property is optional. It defines the filtering criteria that is used by the specified class with the previous property. It defines arbitrary criteria that is meaningful to the implementation class used. 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 left to right, 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();
The following operators and conditions are defined:
Table 2. Filter 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
Greater than >

Arguments are compared lexicographically as greater than.

remote-address>192.168.255.130
Less than <

Arguments are compared lexicographically as less than.

remote-address<192.168.255.135
com.ibm.ws.security.spnego.SPN<id>.enableCredDelegate
This property is optional. It indicates whether the Kerberos-delegated credentials are stored by the SPNEGO TAI. When you use this property, an application can retrieve the stored credentials for additional SPNEGO authentication. However, this property requires the usage of the advanced Kerberos credential delegation feature and requires the development of custom logic by the application developer. The application developer must interact directly with the Kerberos Ticket Granting Service (TGS) to obtain a Kerberos Service Ticket (TGS) and use the delegated Kerberos credentials on behalf of the end user who originated the request. Also, the application developer must construct the appropriate Kerberos SPNEGO token and include it in the HTTP request. This process enables the token to continue the downstream SPNEGO authentication process including handling additional SPNEGO challenge and response exchange, if necessary.
Restrictions:
  • The GSS-delegated credential is available for retrieval immediately after SPNEGO TAI authentication is successful. If a Subject is serialized by any application or application server process, because the GSS-delegated credential is not serializable, it is lost from the Subject after deserialization. For example, after you make a JAX-WS Web service call, the GSS-delegated credential might be lost from the Subject because the run time for the JAX-WS Web service might serialize the Subject.
  • The GSS-delegated credential is available only for retrieval from the original server that created the delegation credential because the GSS-delegated credential is not serializable. The original server is the first server that intercepts the snoop application. In this situation, the GSS-delegated credential is not available to other applications downstream. For example, you have two servers: server1 and server2. server1 intercepts the snoop application, extracts the client GSS-delegated credential, and stores it in the Subject. However, because the GSS-delegated credential is not serializable, the server2 Subject does not have the GSS-delegated credential.
com.ibm.ws.security.spnego.SPN<id>.spnegoNotSupportedPage
This property is optional. It specifies the Web address of a resource that contains the content that the SPNEGO TAI includes in the HTTP response that the (browser) client application displays if it does not support SPNEGO authentication. It 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>;
com.ibm.ws.security.spnego.SPN<id>.NTLMTokenReceivedPage
This property is optional. It specifies the Web address of a resource that contains the content that the SPNEGO TAI includes in the HTTP response that the (browser) client application displays when the SPNEGO token is received by the interceptor when the challenge-response handshake contains a NT LAN Manager (NTLM) token instead of the expected SPNEGO token. It 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>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>
com.ibm.ws.security.spnego.SPN<id>.trimUserName
This property is optional. It specifies whether (true) or not (false) the SPNEGO TAI is to remove the suffix of the principal user name, starting from the "@" that precedes the Kerberos realm name. If this property is set to true, the suffix of the principal user name is removed. If this property is set to false, the suffix of the principal name is retained. The default value used is true. For example,
When com.ibm.ws.security.spnego.SPN<id>.trimUserName = true
bobsmith@myKerberosRealm  becomes  bobsmith
When com.ibm.ws.security.spnego.SPN<id>.trimUserName = false
bobsmith@myKerberosRealm  remains  bobsmith@myKerberosRealm



Related concepts
Single sign-on for HTTP requests using SPNEGO
Related tasks
Mapping Kerberos client principal name to WebSphere user registry ID for SPNEGO
Configuring WebSphere Application Server and enabling the SPNEGO TAI
Reference topic Reference topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Aug 31, 2013 12:02:36 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-zos&topic=rsec_SPNEGO_tai_attribs
File name: rsec_SPNEGO_tai_attribs.html