+

Search Tips   |   Advanced Search

Enable and configure SPNEGO web authentication using the administrative console

We can enable and configure the Simple and Protected GSS-API Negotiation (SPNEGO) as the web authenticator for the application server using the administrative console

Complete the steps described in Create a single sign-on for HTTP requests using SPNEGO Web authentication before enabling SPNEGO web authentication using the administrative console.

We must have a Kerberos keytab file (krb5.keytab) containing the Kerberos service principal name, HTTP/<fully qualified hostname>@KerberosRealm, for any WebSphere application server that processes an HTTP request.


Tasks

  1. In the administrative console, click...

      Security > Global security > Authentication > Web and SIP Security > SPNEGO web authentication

    Configure the filter before enabling SPNEGO web authentication.

  2. Optional: Select the Dynamically update SPNEGO option to dynamically update the SPNEGO run time when SPNEGO changes occur without restarting the application server.

  3. Select Enable SPNEGO to enable SPNEGO as a web authenticator for WAS.

    The Dynamically update SPNEGO and Allow fall back to application authentication mechanism options are disabled unless we select Enable SPNEGO.

  4. Optional: When we select Allow fall back to application authentication mechanism, if SPNEGO authentication fails the authentication mechanism that is defined during application assembly time is used.

  5. 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.

  6. Optional: 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.

    If not specified, the default Kerberos realm name in the Kerberos configuration file is used.

  7. 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.

    1. 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.

    2. Optional: In the Kerberos realm name field, enter the Kerberos realm name.

      In most cases, the realm is your domain name in uppercase letters. For example, a machine with the domain name of test.austin.ibm.com typically has a Kerberos realm name of AUSTIN.IBM.COM. If not specified, the default Kerberos realm name in the Kerberos configuration file is used.

    3. 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();

      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.

      		remote-address<192.168.255.135

    4. 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 not specified, the default filter class, com.ibm.ws.security.spnego.HTTPHeaderFilter, is used.

    5. Optional: In the SPNEGO not supported error page URL field we can optionally enter the URL of a resource containing the content that SPNEGO includes in the HTTP response 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>;

    6. Optional: In the NTLM token received error page URL field we can optionally specify the URL of a resource containing 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 icrosoft(R) Windows(R) Domain.
        <p>Please login to the application using the normal login page.</html>

    7. Optional: 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.

    8. Optional: Select Enable delegation of Kerberos credentials to indicate whether the Kerberos delegated credentials are stored by SPNEGO web authentication.

      If the client is sent to the Kerberos delegation credential, then SPNEGO extracts the GSSCredential and saves it in the subject. The KRBAuthnToken is created with the client Kerberos principal name, and delegates a Kerberos ticket if the client sent the Kerberos delegation credential as part of the request. The GSSCredential is not serializable, so it can not be propagated to downstream server and is lost during serialization and deserialization. However the KRBAuthnToken is serializable, and can be propagated to a downstream server. If a custom application needs the GSSCredential credential for authentication with backend resources or a downstream server, it must retrieve it from the KRBAuthnToken using the com.ibm.wsspi.wssecurity.platform.token.KRBAuthnToken.getGSSCredential() method and then place it in the subject.

      If we don't check this option, the KRBAuthnToken only has the Kerberos principal name.

  8. Click Apply. The filter criteria and filter class are validated if they were specified.

  9. Click OK. This complete the SPNEGO Web Authentication page.

SPNEGO is now enabled as the web authenticator for the application server.


Subtopics