Enable and configuring SPNEGO Web authentication using the admin console
We can enable and configure the Simple and Protected GSS-API Negotiation (SPNEGO) as the Web Authenticator for the appserver by using the admin console
You must have completed the steps as described in Create a single sign-on for HTTP requests using SPNEGO Web authentication before enabling SPNEGO Web authentication using the admin console.
If we do not have a Kerberos keytab file (krb5.keytab) then we cannot use the createkrbConfigFile command to create a Kerberos configuration file. Read about Create a Kerberos configuration file for more information.
You must have a Kerberos keytab file (krb5.keytab) that contains the Kerberos service principal name, HTTP/<fully qualified hostname>@KerberosReam, for any WebSphere application server that processes an HTTP request.
- In the admin console, click...
Security | Global security
- Under Authentication, expand Web and SIP Security and then click SPNEGO Web authentication.
You must configure the filter before enabling SPNEGO Web authentication.
- Select the Dynamically update SPNEGO option to dynamically update the SPNEGO run time when SPNEGO changes occur without restarting the appserver.
- Select Enable SPNEGO to enable the SPNEGO as a Web Authenticator for WAS. The Dynamically update SPNEGO and Allow fall back to application authentication mechanism options are disabled unless you select Enable SPNEGO.
- When you select Allow fall back to application authentication mechanism, if SPNEGO authentication fails the authentication mechanism that is defined during application assembly time is used.
- Enter the Kerberos configuration file name with its full path, or click Browse to locate it. The Kerberos client configuration file, krb5.conf or krb5.ini, contains Kerberos configuration information, including the locations of the Key Distribution Centers (KDCs) for the realm of interest. The krb5.conf file is the default name for all platforms except the Windows operating system, which uses the krb5.ini file.
- Enter the Kerberos keytab file name with its full path, or click Browse to locate it. The Kerberos keytab file contains one or more Kerberos service principal names and keys. The default keytab file is krb5.keytab. It is important for hosts to protect their Kerberos keytab files by storing them on the local disk, which makes them readable only by authorized users. Read about Create a Kerberos service principal and keytab file for more information. If we do not specify this parameter, the default Kerberos realm name in the Kerberos configuration file is used.
- From SPNEGO filters, select an existing host name to edit or select New to create a new one. By convention, a Kerberos service principal name (SPN) is divided into three parts: the primary, the instance, and the Kerberos realm name. The SPNEGO service name must be HTTP, so the Kerberos service principal name for SPNEGO Web is HTTP/<fully qualified host name>@KERBEROS_REALM. The SPN is used to validate the incoming SPNEGO token and to establish security context with a requestor.
- Required: On the next page, enter a fully qualified host name in the Host name field. The host name is part of the Kerberos service principal name (SPN), HTTP/<fully qualified host name>, used by SPNEGO to establish a Kerberos secure context. For each filter entry, the configuration code forms the Kerberos service principal as HTTP/<fully qualified host name>@KERBEROS_REALM, the Kerberos realm that specify in the next step. The Kerberos keytab must content this Kerberos service principal and its keys.
- In the Kerberos realm name field, enter the Kerberos realm name. In most cases, the realm is the domain name in uppercase letters. For example, a machine with the domain name of test.mpls.setgetweb.com typically has a Kerberos realm name of AUSTIN.IBM.COM. If we do not specify this parameter, the default Kerberos realm name in the Kerberos configuration file is used.
- Enter a filter criteria in the Filter criteria field.
The filter criteria is the filtering parameter used by the Java class used by SPNEGO. 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 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 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 1. 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 lexogaphically as greater than.
remote-address>192.168.255.130 Less than <
Arguments are compared lexographically as less than.
- In the Filter class field, enter the name of the Java class used by SPNEGO to select which HTTP requests are subject to SPNEGO Web authentication. If we do not specify this parameter, the default filter class, com.ibm.ws.security.spnego.HTTPHeaderFilter, is used.
- In the SPNEGO not supported error page URL field optionally enter the URL of a resource that contains the content that 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 the SPNEGO not supported error page URL field is not specified, or the SPNEGO that is authenticated 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>;
- In the NTLM token received error page URL field optionally specify the URL of a resource that contains the content that 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 a NT LAN manager (NTLM) token instead of the expected SPNEGO token during the challenge-response handshake.If the NTLM token received error page URL field is not specified, or the SPNEGO that is authenticated 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 we have not logged into a supported Microsoft(R) Windows(R) Domain. <p>Please login to the application using the normal login page.</html>
- Select Trim Kerberos realm from principal name to specify whether SPNEGO removes the suffix of the principal user name, starting from the @ that precedes the Kerberos realm name. If this option is selected, the suffix of the principal user name is removed. If this attribute is not selected, the suffix of the principal name is retained. The default is for this option to not be selected.
- Select Enable delegation of Kerberos credentials to indicate whether the Kerberos delegated credentials are stored by SPNEGO. This option also enables an application to retrieve the stored credentials and to propagate them to other applications downstream for additional Kerberos authentication with the client Kerberos credential. An attempt is made to retrieve the GSS delegation credential and Kerberos tickets and to place these Kerberos credentials in the subject.
- Click Apply. The filter criteria and filter class are validated if they were specified.
- Click OK. This complete the SPNEGO Web Authentication page.
SPNEGO is now enabled as the Web Authenticator for the application server.
Set SPNEGO web authentication filters
SPNEGO Web authentication enablement
SPNEGO Web authentication filter values
Set Kerberos as the authentication mechanism
Create a Kerberos service principal and keytab file
Create a single sign-on for HTTP requests using SPNEGO Web authentication
CSIv2 inbound communications settings
CSIv2 outbound communications settings
SPNEGO Web authentication configuration commands
SPNEGO Web authentication filter commands