+

Search Tips   |   Advanced Search

Enable and configure SPNEGO web authentication using the administrative console


Overview

We can enable and configure the SPNEGO as the web authenticator for the application server using the administrative console

Before enabling SPNEGO web authentication, create a single sign-on for HTTP requests using SPNEGO Web authentication

For any WebSphere application server that processes an HTTP request, we must have a Kerberos keytab file (krb5.keytab) containing the Kerberos service principal name...


Procedure

  1. In the administrative console, click...

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

    We must configure the filter before enabling SPNEGO web authentication.

  2. Optional: To dynamically update the SPNEGO run time when SPNEGO changes occur without restarting the application server, select the option...

      Dynamically update SPNEGO

  3. Select "Enable SPNEGO" to enable the SPNEGO as a web authenticator for WebSphere Application Server.

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

  4. Optional: When you select "Allow fall back to application authentication mechanism", if SPNEGO authentication fails the authentication mechanism 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. Read about Create a Kerberos service principal name and keytab file for more information. 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 the 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 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>;

    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 Microsoft(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: To indicate whether the Kerberos delegated credentials are stored by SPNEGO web authentication, select...

        Enable delegation of Kerberos credentials

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

        com.ibm.wsspi.wssecurity.platform.token.KRBAuthnToken.getGSSCredential()

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


Results

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


Subtopics


Related tasks

Create a single sign-on for HTTP requests using SPNEGO Web authentication
  • Configure Kerberos as the authentication mechanism using the administrative console
  • Create a Kerberos service principal (SPN) and keytab file on the Microsoft domain controller machine
  • Create a Kerberos service principal name and keytab file
  • CSIv2 inbound communications settings
  • CSIv2 outbound communications settings
  • SPNEGO web authentication configuration commands
  • SPNEGO web authentication filter commands