Network Deployment (Distributed operating systems), v8.0 > Secure applications and their environment > Authenticate users > Implement single sign-on to minimize web user authentications > Create a single sign-on for HTTP requests using SPNEGO Web authentication > 3. Configure and enable SPNEGO web authentication on your WAS machine


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 by

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

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


Procedure

  1. In the administrative console, click Security > Global security.

  2. Under Authentication, expand Web and SIP Security and then click SPNEGO web authentication.

    Configure the filter before enabling SPNEGO web authentication.

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

  4. Select Enable SPNEGO to enable the Simple and Protected GSS-API Negotiation Mechanism (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.

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

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

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

  8. 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, your 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.//publib.boulder.ibm.com/infocenter/wasinfo/v8r0/index.jsp?topic=/ .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();

      Filter conditions and operations.

      This table describes the filter criteria conditions and operations.

      Condition Operator Example
      Match exactly ==

      aug2011

      Arguments are compared as equal.

      		host==host.my.company.com

      aug2011

      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 you can 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>;

    6. Optional: In the NTLM token received error page URL field you can 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>

    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.

      We must set this field to true if you are using both the Local Operating System registry on z/OS and select the Use the KERB segment of an SAF user profile check box button to map Kerberos principals to SAF identities.

    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 you don't check this option, the KRBAuthnToken only has the Kerberos principal name.

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

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


Results

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


Related


Set SPNEGO web authentication filters
SPNEGO web authentication enablement
SPNEGO web authentication filter values
Configure Kerberos as the authentication mechanism
Create a Kerberos service principal (SPN) and keytab file on your Microsoft domain controller machine
Create a Kerberos service principal name and keytab file
Create a single sign-on for HTTP requests using SPNEGO Web authentication


Related


CSIv2 inbound communications settings
CSIv2 outbound communications settings
SPNEGO web authentication configuration commands
SPNEGO web authentication filter commands

+

Search Tips   |   Advanced Search