Securing WebLogic Server

Configuring Single Sign-On with Microsoft Clients

This section explains how to set up single sign-on (SSO) with Microsoft clients, using Windows authentication based on the Simple and Protected Negotiate (SPNEGO) mechanism and the Kerberos protocol, together with the WebLogic Negotiate Identity Assertion provider.

Single Sign-on with Microsoft Clients: Main Steps

Single sign-on (SSO) with Microsoft clients allows cross-platform authentication between Web applications or Web Services running in a WebLogic Server domain and .NET Web Service clients or browser clients (for example, Internet Explorer) in a Microsoft domain. The Microsoft clients must use Windows authentication based on the Simple and Protected Negotiate (SPNEGO) mechanism.

Cross-platform authentication is achieved by emulating the negotiate behavior of native Windows-to-Windows authentication services that use the Kerberos protocol. In order for cross-platform authentication to work, non-Windows servers (in this case, WebLogic Server) need to parse SPNEGO tokens in order to extract Kerberos tokens which are then used for authentication.

Configuring SSO with Microsoft clients involves set up procedures in the Microsoft Active Directory, the client, and the WebLogic Server domains.

The Kerberos protocol uses the Active Directory server in the Microsoft domain to store the necessary security information. Therefore, you need to define a principal in Active Directory to represent the WebLogic Server.
Any Microsoft client you want to access in the Microsoft domain must be set up to use Windows Integrated authentication, sending a Kerberos ticket when available.
In the WebLogic Server domain, a Negotiate Identity Assertion provider needs to be configured in the security realm. The Web application or Web Service used in SSO needs to have authentication set in a specific manner. A JAAS login file that defines the location of the Kerberos identification for WebLogic Server must be created.

The main configuration steps are as follows:

Configure your network domain to use Kerberos. See

Create a Kerberos identification for WebLogic Server.

Create a user account in Active Directory for the host on which WebLogic Server is running.

Create a Service Principal Name for this account.

Create a user mapping and keytab file for this account.

For more information, see Creating a Kerberos Identification for WebLogic Server.

Choose a Microsoft client (either a Web Service or a browser) and configure it to use Windows Integrated authentication. For more information, see Configuring Microsoft Clients to Use Windows Integrated Authentication.

Set up the WebLogic Server domain to use Kerberos authentication.

Create a JAAS login file that points to the Active Directory server in the Microsoft domain and the keytab file created in Step 1. For more information, see Creating a JAAS Login File.

Configure a Negotiate Identity Assertion provider in the WebLogic Server security realm. For more information, see Configuring a Negotiate Identity Assertion Provider.

Start WebLogic Server using specific start-up arguments. For more information, see Startup Arguments for Using Kerberos Authentication with WebLogic Server

The following sections describe these steps in detail.

System Requirements for SSO with Microsoft Clients

To use SSO with Microsoft clients, you must comply with these system requirements:

A host computer with:

Windows 2000 or greater installed
Fully-configured Active Directory authentication service. Specific Active Directory requirements include:

User accounts for mapping Kerberos services
Service Principal Names (SPNs) for those accounts
Key tab files created and copied to the start-up directory in the WebLogic Server domain

WebLogic Server installed and configured properly to authenticate via Kerberos, as described in this section, Configuring Single Sign-On with Microsoft Clients.

Client systems with:

Windows 2000 Professional SP2 or greater installed
One of the following types of clients:

A properly configured Internet Explorer browser. Internet Explorer 6.01 or greater is supported.
.NET Framework 1.1 and a properly configured Web Service client.

Clients must be logged on to a Windows 2000 domain and have Kerberos credentials acquired from the Active Directory server in the domain. Local logons will not work.

Configuring your Network Domain to Use Kerberos

A Windows domain controller can server as the Kerberos Key Distribution Center (KDC), using the Active Directory and the Kerberos services. On any domain controller, the Active Directory and the Kerberos services will be running automatically. To configure Kerberos in your Windows domain controller, you need to configure each machine that will access the KDC to locate the Kerberos realm and available KDC servers. For Windows machines, this configuration is in the krb5.ini file, in the C:\winnt folder. For UNIX machines, this configuration is in the krb5.conf file, the default location of which is /etc/krb5/. For example:

Listing 6-1 Sample krb5.ini File

[libdefaults]
default_realm = MYDOM.COM (Identifies the default realm. Set its value to your Kerberos realm)
default_tkt_enctypes = des-cbc-crc
default_tgs_enctypes = des-cbc-crc
ticket_lifetime = 600

[realms]

MYDOM.COM = {
kdc = <IP address for MachineA> (host running the KDC)
(For Unix systems, you need to specify port88, as in <IP-address>:88)
admin_server = MachineA
default_domain = MYDOM.COM

[domain_realm]
.mydom.com = MYDOM.COM

[appdefaults]
autologin = true
forward = true
forwardable = true
encrypt = true

Creating a Kerberos Identification for WebLogic Server

Active Directory provides support for service principal names (SPN) which are a key component in Kerberos authentication. SPNs are unique identifiers for services running on servers. Every service that uses Kerberos authentication needs to have an SPN set for it so that clients can identify the service on the network. An SPN usually looks something like name@YOUR.REALM. You need to define an SPN to represent your WebLogic Server in the Kerberos realm. If an SPN is not set for a service, clients have no way of locating that service. Without correctly set SPNs, Kerberos authentication is not possible. Keytab files are the mechanism for storing the SPNs. Keytab files are copied to the WebLogic Server domain and are used in the login process. This configuration step describes how to create an SPN, user mapping, and keytab file for WebLogic Server.

This configuration step requires the use of the following Active Directory utilities:

setspn—Windows 2000 Resource Kit
ktpass—Windows 2000 distribution CD in Program Files\Support Tools

Note: The setspn and ktpass Active Directory utilities are products of Microsoft. Therefore, BEA Systems does not provide complete documentation for this utilities. For more information, see the appropriate Microsoft documentation.

To create a Kerberos identification for WebLogic Server:

Create a user account for the host computer on which WebLogic Server runs in the Active Directory server. (Select New > User, not New > Machine.)

When creating the user account, use the simple name of the computer. For example, if the host is named myhost.example.com, create a user in Active Directory called myhost.
Note the password you defined when creating the user account. You will need it in step 3. Do not select the User must change password at next logon option, or any other password options.

Configure the new user account to comply with the Kerberos protocol. The user account's encryption type must be DES and the account must require Kerberos pre-authentication.

Right-click the name of the user account in the Users tree in the left pane and select Properties.

Select the Account tab and check the box "Use DES encryption types for this account." Make sure no other boxes are checked, particularly the box "Do not require Kerberos pre-authentication."

Setting the encryption type may corrupt the password. Therefore, you should reset the user password by right-clicking the name of the user account, selecting Reset Password, and re-entering the same password specified earlier.

Use the setspn utility to create the Service Principal Names (SPNs) for the user account created in step 1. Enter the following commands:

setspn -a host/myhost.example.com myhost

setspn -a HTTP/myhost.example.com myhost

Check which SPNs are associated with your user account, using the following command:

setspn -L account name

This is an important step. If the same service is linked to a different account in the Active Directory server, the client will not send a Kerberos ticket to the server.

Create a user mapping using the ktpass utility:

Windows ktpass -princ host/myhost@Example.CORP -pass password -mapuser myhost -out c:\temp\myhost.host.keytab

Create a keytab file. On Windows, the ktab utility manages principal name and key pairs in the key table and allows you to list, add, update, or delete principal names and key pairs. On UNIX, it is preferable to use the ktpass utility.

Windows

Run the ktab utility on the host on which WebLogic Server is running to create the keytab file:

ktab -k keytab-filename -a myhost@Example.CORP

Copy the keytab file to the startup directory in the WebLogic Server domain.

UNIX

Create a user mapping using the ktpass utility:

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

where password is the password for the user account created in step 1.

Copy the keytab file created in Step a to the startup directory in the WebLogic Server domain.

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

Run the kinit utility to verify Kerberos authentication is working properly.

kinit -k -t keytab-file account-name

The output should be something similar to: New ticket is stored in cache file C:\Documents and Settings\Username\krb5cc_MachineB

Configuring Microsoft Clients to Use Windows Integrated Authentication

Ensure the Microsoft client you want to use for single sign-on is configured to use Windows Integrated authentication. The following sections describe how to configure a .NET Web server and an Internet Explorer browser to use Windows Integrated authentication.

Configuring a .NET Web Service

To configure a .NET Web Service to use Windows authentication, perform the following steps:

In the web.config file for the Web Service, set the authentication mode to Windows for IIS and ASP.NET as follows:

<authentication mode="Windows" />

This setting is usually the default.

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 a Web Service that is represented by the proxy object conv, the syntax is as follows: /* * Explicitly pass credentials to the Web Service */ conv.Credentials = System.Net.CredentialCache.DefaultCredentials;

Configuring an Internet Explorer Browser

To configure an Internet Explorer browser to use Windows authentication, follow these procedures in Internet Explorer:

Configure Local Intranet Domains

In Internet Explorer, select Tools > Internet Options.

Select the Security tab.

Select Local intranet and click Sites.

In the Local intranet popup, ensure that the "Include all sites that bypass the proxy server" and "Include all local (intranet) sites not listed in other zones" options are checked.

Click Advanced.

In the Local intranet (Advanced) dialog box, add all relative domain names that will be used for WebLogic Server instances participating in the SSO configuration (for example, myhost.example.com) and click OK.

Configure Intranet Authentication

Select Tools > Internet Options.

Select the Security tab.

Select Local intranet and click Custom Level....

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

Select Automatic logon only in Intranet zone. This option prevents users from having to re-enter logon credentials, which is a key piece to this solution.

Click OK.

Verify the Proxy Settings

If you have a proxy server enabled:

Select Tools > Internet Options.

Select the Connections tab and 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 Integrated Authentication for Internet Explorer 6.0

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

In Internet Explorer, select Tools > Internet Options.

Select the Advanced tab.

Scroll to the Security section.

Make sure that Enable Integrated Windows Authentication option is checked and click OK.

If this option was not checked, restart the computer.

Creating a JAAS Login File

If you are running WebLogic Server on either the Windows or UNIX platforms, you need a JAAS login file. The JAAS login file tells the WebLogic security framework to use Kerberos authentication and defines the location of the keytab file which contains Kerberos identification information for WebLogic Server. You specify the location of this file in the java.security.auth.login.config startup argument for WebLogic Server, as described in Startup Arguments for Using Kerberos Authentication with WebLogic Server.

Listing 6-2 contains a sample JAAS login file for Kerberos authentication.

Listing 6-2 Sample JAAS Login File for Kerberos Authentication

com.sun.security.jgss.initiate {

     com.sun.security.auth.module.Krb5LoginModule required
     principal="myhost@Example.CORP" useKeyTab=true
     keyTab=mykeytab storeKey=true;
};

com.sun.security.jgss.accept {

     com.sun.security.auth.module.Krb5LoginModule required
     principal="myhost@Example.CORP" useKeyTab=true 
     keyTab=mykeytab storeKey=true;

};

Configuring the Identity Asssertion Provider

WebLogic Server includes a security provider, the Negotiate Identity Assertion provider, to support single sign-on (SSO) with Microsoft clients. This identity assertion provider decodes Simple and Protected Negotiate (SPNEGO) tokens to obtain Kerberos tokens, validates the Kerberos tokens, and maps Kerberos tokens to WebLogic users. You need to configure a Negotiate Identity Assertion provider in your WebLogic security realm in order to enable SSO with Microsoft clients. For information, see Configuring a Negotiate Identity Assertion Provider and Configure Authentication and Identity Assertion providers in the Administration Console help.

Startup Arguments for Using Kerberos Authentication with WebLogic Server

To use Kerberos authentication with WebLogic Server, use the following start-up arguments when you start WebLogic Server:

-Djava.security.krb5.realm=Example.CORP
-Djava.security.krb5.kdc=ADhostname
-Djava.security.auth.login.config=krb5Login.conf
-Djavax.security.auth.useSubjectCredsOnly=false
-Dweblogic.security.enableNegotiate=true

where

java.security.krb5.realm defines the Microsoft domain in which the Active Directory server runs.
java.security.krb5.kdc defines the host name on which the Active Directory server runs.
java.security.auth.login.config defines the location of the Kerberos login information.
javax.security.auth.useSubjectCredsOnly specifies that it is permissible to use an authentication mechanism other than Subject credentials.

weblogic.security.enableNegotiate enables the Servlet container in WebLogic Server to support the Negotiate token used by SPNEGO.

Verifying that SSO with Microsoft Clients Works

To verify that SSO with Microsoft clients is properly configured, point a browser (that you have configured as described in Configuring an Internet Explorer Browser) to the Microsoft Web application or Web Service you want to use. If you are logged on to a Windows domain and have Kerberos credentials acquired from the Active Directory server in the domain, you should be able to access the Web application or Web Service without providing a username or password.