Administration Application Guide

Enabling Single Sign On

Configuring Single Sign On with Microsoft Clients

Using a Single Pass Negotiate Identity Asserter shipped with WebLogic Enterprise Security, Version 4.2 SP01, you can achieve cross-platform authentication, single sign on (SSO), integration with Microsoft Internet Explorer browser clients and Microsoft .NET web services.

Cross-platform authentication is achieved by emulating the negotiate behavior of native Windows-to-Windows authentication services. The servlet container in this release was modified to handle the necessary header manipulation required by the Windows negotiate protocol, also known as Simple and Protected Negotiate (SPNEGO).

The negotiate identity asserter is an implementation of the Security Service Provider Interface (SSPI) as defined by the WebLogic Security Framework and provides the necessary logic to authenticate a client based on the client's SPNEGO token.

Requirements

The environment for cross-platform authentication requires the following components.

Domain controller back-end system

Windows 2000 or greater Active Directory
Service accounts for mapping Kerberos services
Service Principal Names (SPNs) properly configured
Keytab files created and inserted, based on platform environment of your server system

WebLogic application server system

WebLogic Enterprise Security, Version 4.2, SP01 installed
WebLogic 8.1 Security Service Module installed and an instance created
WebLogic application server configured to use Active Directory realm
Keytab import and configuration
MIT Kerberos V5 Generic Security Service API (GSS-API)

Client systems

.NET Framework 1.1
Windows 2000 Professional SP2 or greater
Internet Explorer 5.01, Internet Explorer v5.5 SP2, Internet Explorer 6.0 SP1
Proper configuration of the Internet Explorer browser
Proper configuration of web services clients

Note: Client users must be logged on to a Windows 2000 domain or realm, having acquired Kerberos credentials from the Active Directory domain. Local logons do not work.

The following sections describe how to configure the SPNEGO provider and how to set up the necessary components.

Enabling a Web Service or Web Application

To enable a particular web service, web application, or other protected resource for single sign on, you must use the Single Pass Negotiate Identity Asserter provider in conjunction with client certification set as the login configuration in your standard J2EE web.xml descriptor file.

Configuring the SPNEGO Provider

Configure the Single Pass Negotiate Identity Assertion provider using the Administration Console. To configure the provider, create an instance of the SPNEGO provider for the WebLogic Server 8.1 Security Service Module. For information on how to configure the provider, see Configuring a Single Pass Negotiate Identity Asserter on page 9-30.

Editing the Descriptor File

The following example shows a sample web.xml file for a protected WebLogic Web Service resource (Conversation) with the login configuration set to CLIENT-CERT.

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>

<security-constraint>

        <display-name>Security Constraint on Conversation</display-name>

        <web-resource-collection>

            <web-resource-name>Conversation web service</web-resource-name>

            <description>Only those granted the ConversationUsers role may access the Conversation web service.</description>

            <url-pattern>/async/Conversation.jws/*</url-pattern>

            <http-method>GET</http-method>

            <http-method>POST</http-method>

        </web-resource-collection>

        <auth-constraint>

            <role-name>ConversationUsers</role-name>

        </auth-constraint>

    </security-constraint>

    <login-config>

      <auth-method>CLIENT-CERT</auth-method>

    </login-config>

    <security-role>

        <description>Role description</description>

        <role-name>ConversationUsers</role-name>

    </security-role>

</web-app>

You can use any role to protect your web resource collection. You want to make the corresponding security and run-as role assignments in your weblogic.xml descriptor as needed. For the previous example, the weblogic.xml file contains:

<?xml version="1.0" encoding="UTF-8"?>

  <!DOCTYPE weblogic-web-app

    PUBLIC "-//BEA Systems, Inc.//DTD Web Application 7.0//EN"

    "http://www.bea.com/servers/wls700/dtd/weblogic700-web-jar.dtd" >

<weblogic-web-app>

    

    <security-role-assignment>

        <role-name>ConversationUsers</role-name>

        <principal-name>weblogic</principal-name>

    </security-role-assignment>

        

</weblogic-web-app>

For more information on configuring protected resources for WebLogic Server, see Securing WebLogic Resources.

Configuring the Active Directory Authentication

This procedure requires the use of the following Active Directory utilities:

setspn - found on the Windows 2000 Resource Kit
ktpass - found on the Windows 2000 distribution CD in \Program Files\Support Tools

The first three steps assume you have two domains: one represents the WebLogic application server domain (bea.com) and one controlled by Active Directory (magellan.corp).

Create a user account for the hostname of the web server machine in Active Directory, by using the Active Directory Users and Computers Snap-in.

Click Start->Programs->Administrative Tools->Active Directory Users and Computers.
Use the simple name of the WebLogic server host. For example, if the host you are running the WebLogic application on is called myhost.bea.com, create a new user in Active Directory called myhost. Do not select "User must change password at next logon." Make a note of the password for use in step 3.

Create the Service Principal Names (SPNs) for this account:

setspn -A host/myhost.bea.com myhost
setspn -A HTTP/myhost.bea.com myhost

Create your user mapping and export the keytab files using the ktpass utility:

ktpass -princ host/myhost@MAGELLAN.CORP -pass <password> -mapuser myhost
-out c:\temp\myhost.host.keytab

ktpass -princ HTTP/myhost@MAGELLAN.CORP -pass <password> -mapuser myhost
-out c:\temp\myhost.HTTP.keytab

Note: If you generated the keytab files for a WebLogic server on a Unix host, copy the keytab files securely to the Unix host. Login as root and then merge them into a single keytab using the ktutil utility:

ktutil: "rkt myhost.host.keytab"
ktutil: "rkt myhost.HTTP.keytab"
ktutil: "wkt mykeytab"
ktutil: "q"

If your WebLogic server is running on a Windows platform, generate the keytab from that machine using the ktab.

Verify that authentication works.

To verify that Kerberos authentication is working on the Unix system, run the kinit utility:

kinit -t mykeytab myhost

You are prompted for the password and if authentication succeeds, the command prompt returns without an error message.

To verify that Kerberos authentication is working on a Windows system, use the ktab utility locally on the WebLogic server host to create the keytab file in the WebLogic server domain directory:

setEnv
ktab -k mykeytab -a myhost@MAGELLAN.CORP <password>

Create a JAAS login configuration file.

For either a Windows or a Unix server host, you need a JAAS login configuration file. You also need to set some system properties to direct WebLogic server to allow the proper Kerberos authentication to occur. A sample login configuration file called krb5Login.conf looks like this: com.sun.security.jgss.initiate { com.sun.security.auth.module.Krb5LoginModule required principal= "myhost@MAGELLAN.CORP" useKeyTab=true keyTab=mykeytab storeKey=true; }; com.sun.security.jgss.accept { com.sun.security.auth.module.Krb5LoginModule required principal= "myhost@MAGELLAN.CORP" useKeyTab=true keyTab=mykeytab storeKey=true; };

Add the following system properties to the start line of your WebLogic server:

-Djava.security.krb5.realm=MAGELLAN.CORP
-Djava.security.krb5.kdc=ADhostname
-Djava.security.auth.login.config=krb5Login.conf
-Djavax.security.auth.useSubjectCredsOnly=false

For a web service client, complete the steps described in Configure the Client .NET Web Service on page 8-6. For Internet Explorer configuration, complete the steps described in Configure the Internet Explorer Client Browser on page 8-7.

Configure the Active Directory Authentication Provider

To populate groups properly in the authenticated subject and to use the keystores, you must configure the Active Directory Authentication Provider. For information on how to configure this provider, see Configuring an Active Directory Authentication Provider on page 9-15.

Configure the Client .NET Web Service

To configure the client .NET web service:

Open the web.config file for the client web service.

Set the authentication mode to Windows for IIS and ASP.NET. This is usually the default.

<authentication mode="Windows" />

Add the statement needed for the web services client to pass to the proxy web service object so that the credentials are sent through SOAP.

For example, if you have a web service client for the conversation web service represented by the proxy object conv, then setting the web services client credentials in C# looks like this: /* * Explicitly pass credentials to the Web Service */ conv.Credentials = System.Net.CredentialCache.DefaultCredentials;

Configure the Internet Explorer Client Browser

If you are configuring Internet Explorer, you must perform the following steps:

Configure the Sites

To configure the sites:

In Internet Explorer, click Tools, and then click Internet Options.

Click the Security tab.

Click Local intranet.

Click Sites.

Ensure that Include all sites that bypass the proxy server is checked, and then click Advanced.

In the Local intranet (Advanced) dialog box, enter all relative domain names that will be used on the intranet (e.g. myhost.bea.com).

Click OK to close the dialog boxes.

Configure Intranet Authentication

To configure Intranet Authentication:

Click the Security tab, click Local intranet, and then click Custom Level.

In the Security Settings dialog box, scroll down to the User Authentication section of the list.

Select Automatic logon only in Intranet zone. This setting prevents users from having to re-enter logon credentials; a key piece to this solution.

Click OK to close the Security Settings dialog box.

Verify the Proxy Settings

To verify the Proxy Settings:

In Internet Explorer, click Tools, and then click Internet Options.

Click the Connections tab.

Click LAN Settings.

Verify that the proxy server address and port number are correct.

Click Advanced.

In the Proxy Settings dialog box, ensure that all desired domain names are entered in the Exceptions field.

Click OK to close the Proxy Settings dialog box.

Set the Internet Explorer 6.0 Configuration Settings

In addition to the previous settings, one additional setting is required if you are running Internet Explorer 6.0.

In Internet Explorer, click Tools, and then click Internet Options.

Click the Advanced tab.

Scroll down to the Security section.

Make sure that Enable Integrated Windows Authentication (requires restart) is checked, and then click OK.

If this box was not checked, restart the browser.