Skip Headers
Oracle® Fusion Middleware Securing Oracle WebLogic Server
12c Release 1 (12.1.1)

Part Number E24422-04
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

6 Configuring Single Sign-On with Microsoft Clients

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

This chapter includes the following sections:

Overview of Single Sign-On with Microsoft Clients

Single sign-on (SSO) with Microsoft clients allows cross-platform authentication between Web applications or Web services running in a WebLogic domain and .NET Web service clients or browser clients (for example, Internet Explorer) in a Microsoft domain. The Microsoft clients must use Windows Integrated 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.

For more information about Windows and Kerberos, see http://technet.microsoft.com/en-us/library/bb742431.aspx.

System Requirements for SSO with Microsoft Clients

To use SSO with Microsoft clients, you need to meet the requirements described in the following sections:

Host Computer Requirements for Supporting SSO with Microsoft Clients

The host computer that supports SSO for Microsoft clients must meet the following system requirements:

  • Windows Server 2000, 2003, or 2008 R2 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

    • Keytab files created and copied to the start-up directory in the WebLogic domain

  • WebLogic Server installed and configured properly with JDK 1.6.0_24, or later, to authenticate through Kerberos, as described in this chapter

Oracle recommends encrypting the user accounts that are mapped to Kerberos services on the WebLogic Server host. However, the ability to encrypt these accounts imposes additional requirements. The specific requirements depend on the encryption algorithm used, as shown in Table 6-1.

Table 6-1 Client Type Requirements for Using Encrypted User Accounts

Encryption Supported Client Type Active Directory Platform

DES

  • Internet Explorer 6.01 or later

  • Mozilla FireFox

  • .NET Web service

  • Java SE client

Windows 2003 or later

AES-128, AES-256, and RC4

  • Internet Explorer 8.0

  • Mozilla FireFox 7.0.1

  • Java SE clientFoot 1 

Windows 2008-R2 or later


Footnote 1 User accounts accessed with a Java SE client can also be encrypted with DES, AES-128, AES-256, and RC4 and defined in Active Directory running on a Windows 2003 platform.

Client Computer Requirements for Supporting Microsoft Clients Using SSO

The computer hosting a Microsoft client that uses SSO must meet the following requirements:

  • Windows 2000 Professional SP2 or later installed

    Note:

    Oracle certifies that Internet Explorer 8.0 and FireFox 7.0.1 clients accessing user accounts defined in Active Directory and encrypted with AES-128, AES-256, or RC4 will run on a Windows 7 Enterprise platform.

  • One of the following types of clients hosted:

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

Single Sign-On with Microsoft Clients: Main Steps

Configuring SSO with Microsoft clients requires set-up procedures in the Microsoft Active Directory, the client, and the WebLogic domain. (These procedures are detailed in the sections that follow.)

To configure SSO with Microsoft clients:

  1. Configure your network domain to use Kerberos. See Configuring Your Network Domain to Use Kerberos.

  2. Create a Kerberos identification for WebLogic Server.

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

    2. Create a service principal name (SPN) for this account.

    3. Create a user mapping and keytab file for this account.

    See Creating a Kerberos Identification for WebLogic Server.

  3. Choose a Microsoft client (either a Web service or browser) or a Java SE client and configure it to use Windows Integrated Authentication. See Configuring Microsoft Clients to Use Windows Integrated Authentication.

  4. Set up the WebLogic domain to use Kerberos authentication.

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

    2. Configure a Negotiate Identity Assertion provider in the WebLogic Server security realm. See Configuring a Negotiate Identity Assertion Provider.

  5. Start WebLogic Server using specific start-up arguments. See Using Startup Arguments for Kerberos Authentication with WebLogic Server.

The following sections describe these steps in detail.

Configuring Your Network Domain to Use Kerberos

A Windows domain controller can serve as the Kerberos Key Distribution Center (KDC) server for Kerberos-based client and host systems. On any domain controller, the Active Directory and the Kerberos services are running automatically.

Java GSS requires a Kerberos configuration file. The default name and location of the Kerberos configuration file depends on the operating system being used. Java GSS uses the following order to search for the default configuration file:

  1. The file referenced by the Java property java.security.krb5.conf.

  2. ${java.home}/lib/security/krb5.conf.

  3. %windir%\krb5.ini on Microsoft Windows platforms.

  4. /etc/krb5/krb5.conf on Solaris platforms.

  5. /etc/krb5.conf on other UNIX platforms.

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 example:

Example 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 port 88, 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 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 process requires the use of the following Active Directory utilities:

The process for creating a Kerberos identification consists of the following steps:

Step 1: Create a User Account for the Host Computer

In the Active Directory server, create a user account for the host computer on which WebLogic Server runs. (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 for the instructions described in Step 3: Define a Service Principal Name and Create a Keytab for the Service. Do not select the User must change password at next logon option or any other password options.

Step 2: Configure the User Account to Comply with Kerberos

Configure the new user account to comply with the Kerberos protocol as follows. The user account's encryption type must be DES, at a minimum, and the account must require Kerberos pre-authentication. Stronger encryption types are supported, including AES-128, AES-256, and RC4.

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

  2. Select the Account tab and check the following:

    • If you plan to use DES encryption, check the box Use DES encryption types for this account.

      Note:

      DES encryption requires Active Directory to be running on Windows Server 2003 or later.

    • If you plan to use AES encryption, check the boxes This account supports Kerberos AES 128 and This account supports Kerberos AES 256, and make sure that Use Kerberos DES Encryption is unchecked.

      Note:

      AES-128 and AES-256 encryption require Active Directory to be running on Windows Server 2008-R2 or later.

    Make sure no other boxes are checked, particularly the box "Do not require Kerberos pre-authentication."

  3. Click OK.

Caution:

Setting the encryption type may corrupt the password. Therefore, reset the user password by right-clicking the name of the user account, selecting Reset Password, and re-entering the password created in Step 1: Create a User Account for the Host Computer.

Step 3: Define a Service Principal Name and Create a Keytab for the Service

As mentioned in Creating a Kerberos Identification for WebLogic Server, an SPN is a unique name that identifies an instance of a service and is associated with the logon account under which the service instance runs. The SPN is used in the process of mutual authentication between the client and the server hosting a particular service. The client finds a computer account based on the SPN of the service to which it is trying to connect. So, in a specific project, you need to link the service that will be invoked by your WebLogic clients to the account you just defined for your WebLogic Server. For example, the service invoked by the WebLogic browser clients is HTTP/myhost.example.com, which needs to be linked to the myhost account.

Windows account names are not multipart as Kerberos principal names. Because of this, it is not possible to directly create an account using the name HTTP/hostname.dns.com. Such a principal instance is created through SPN mappings. In this case, an account is created with a meaningful name hostname, and an SPN mapping is added for HTTP/hostname.dns.com.

The specific steps for defining an SPN and creating a keytab for the service depend on the underlying platform on which WebLogic Server is running. They are provided in the following sections:

Defining an SPN and Creating a Keytab on Windows Systems

If WebLogic Server runs on a Windows system, complete the following steps:

  1. Use the setspn utility to create the SPN for the HTTP service for the WebLogic Server account created in Step 1. For example:

    setspn -A HTTP/myhost.example.com myhost
    
  2. Identify the SPNs that are associated with your user account by entering the setspn -L command. For example:

    setspn -L myhost
    

    Tip:

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

  3. Use the ktab utility to create a keytab to be exported to the WebLogic Server machine. The command to run the ktab utility has the following syntax (note that the Kerberos realm name must be entered in all uppercase):

    ktab -k keytab-file-name -a account-name@REALM.NAME
    

    For example:

    ktab -k mykeytab -a myhost@MYDOM.COM
    

    When prompted for a password, enter the password created in Step 1.

  4. Save the keytab file in a secure location and export it to the domain directory of your WebLogic Server instance (for example, to myhost).

Defining an SPN and Creating a Keytab on UNIX Systems

If WebLogic Server runs on a UNIX system, create a service principal name (SPN) and a keytab file for the HTTP service for the WebLogic Server account by using the ktpass command-line tool. This tool enables an administrator to configure a non-Windows Server Kerberos service as a security principal in the Windows Server Active Directory.

The ktpass command configures the SPN for the service in Active Directory and generates a Kerberos keytab file containing the shared secret key of the service. The tool allows UNIX-based services that support Kerberos authentication to use the interoperability features provided by the Windows Server Kerberos KDC service.

The ktpass command has the following syntax:

ktpass -princ HTTP/hostname@REALM-NAME -mapuser account-name -pass password -out keytab-file-name -crypto algorithm -ptype KRB5_NT_PRINCIPAL

In the preceding syntax, algorithm identifies the encryption algorithm to use. If you are using AES, specify AES128-SHA1 or AES256-SHA1. For example:

ktpass -princ HTTP/myhost.example.com@MYDOM.COM -mapuser myhost -pass welcome1 -out mykeytab -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL

Note:

On UNIX systems, creating an SPN that uses a DES or an AES encryption algorithm is supported with JDK 1.6.0_24 or later.

To verify that the SPN and the keytab file are set up correctly, you can do the following:

  • Use the setspn -l command to verify that the SPN is mapped successfully.

  • Use the klist command to show Key type: 17 for AES-128, and Key type: 18 for AES-256. For example:

    -klist -e -k keytab-file-name
    
  • Use the kinit command to verify that the Kerberos setup and keytab are valid.

Note:

The ktpass command changes the principal name in the Active Directory server from account-name to HTTP/account-name. Consequently, the keytab file is generated for a principal named HTTP/account-name. However, sometimes the name change does not happen. If not, you should change it manually in the Active Directory server; otherwise the keytab you generate will not work properly.

To modify the user logon name manually:

  1. Right-click on the user node, select Properties, and click on the Account tab.

  2. Export the generated keytab file to your UNIX machine hosting the WebLogic Server in the WebLogic domain directory.

Step 4: Verify Correct Setup

You can use the following utilities to verify that your SPN and keytab files are set up correctly.

  • Use the setspn -l command to verify that the SPN is mapped successfully.

  • Use the klist command to verify the key type. For example:

    -klist -e -k keytab-file-name
    

    For AES 128, this command displays Key type: 17. For AES 256, Key type: 18 is displayed.

  • Use the kinit utility to verify that Kerberos is set up properly and that your principal and keytab are valid.

    The kinit utility is provided by the JRE and may be used to obtain and cache Kerberos ticket-granting tickets. You can run the kinit utility by entering the following command:

    kinit -k -t keytab-file account-name
    

    The output should appear similar to the following:

    New ticket is stored in cache file C:\Documents and Settings\Username\krb5cc_myhost
    

Step 5: Update Default JDK Security Policy Files

AES-256 requires the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 6, which are available at the following URL:

http://www.oracle.com/technetwork/java/javase/downloads/index.html

If you plan to use AES encryption, complete the following steps:

  1. Download JCE Unlimited Strength Jurisdiction Policy Files from the preceding URL.

  2. Uncompress and extract the jurisdiction policy files.

  3. Complete the installation procedure described in the included README.txt file.

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, an Internet Explorer browser client, a Mozilla Firefox client, and a Java SE client to use Windows Integrated Authentication:

Note:

If the SPN for the user account on the WebLogic Server host to which the Kerberos ticket is mapped is configured to use DES or AES-256 encryption (see Step 2: Configure the User Account to Comply with Kerberos), the client must be running with JDK 1.6.0_24 or later.

Configuring a .NET Web Service

To configure a .NET Web service to use Windows Integrated Authentication:

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

  2. 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 Integrated Authentication, complete the procedures described in the following sections:

Configure Local Intranet Domains

In Internet Explorer:

  1. Select Tools > Internet Options.

  2. Select the Security tab.

  3. Select Local intranet and click Sites.

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

  5. Click Advanced.

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

In Internet Explorer:

  1. Select Tools > Internet Options.

  2. Select the Security tab.

  3. Select Local intranet and click Custom Level... .

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

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

  6. Click OK.

Verify the Proxy Settings

If you have a proxy server enabled:

  1. In Internet Explorer, select Tools > Internet Options.

  2. Select the Connections tab and click LAN Settings.

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

  4. Click Advanced.

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

  6. Click OK to close the Proxy Settings dialog box.

Set Integrated Authentication for Internet Explorer 6.0

If the version of Internet Explorer you are configuring is 6.0, you also must complete the following steps:

  1. In Internet Explorer, select Tools > Internet Options.

  2. Select the Advanced tab.

  3. Scroll to the Security section.

  4. Verify that the Enable Integrated Windows Integrated Authentication option is checked and click OK.

    If this option was not checked, check it, click OK, and restart the computer.

Configuring a Mozilla Firefox Browser

To configure a Firefox browser to use Windows Integrated Authentication, complete the following steps:

  1. Start Firefox.

  2. In the Location Bar, enter about:config.

  3. Enter the filter string network.negotiate.

  4. Set the preferences as shown in Table 6-2.

    Table 6-2 Preferences Required in Firefox for Windows Integrated Authentication

    Preference Name Status Type Value
    network.negotiate-auth.allow-proxies
    
    default
    
    boolean
    
    true
    
    network.negotiate-auth.delegation-uris
    
    user set
    
    string
    
    http://,https://
    
    network.negotiate-auth.gsslib
    
    default
    
    string
    

    <blank>Foot 1 

    network.negotiate-auth.trusted-uris
    
    user set
    
    string
    
    http://,https://
    
    network.negotiate-auth.using-native-gsslib
    
    default
    
    boolean
    
    true
    

    Footnote 1 The value for the network.negotiate-auth.gsslib preference should be kept blank.

Configuring a Java SE Client Application

To configure a Java SE client application to use Windows Integrated Authentication, complete the following steps:

  1. Ensure that your Java SE client is running with JDK 1.6.0_24 or later.

  2. Create a JAAS configuration file that identifies the Kerberos login module, com.sun.security.auth.module.Krb5LoginModule. This configuration file defines two login entries:

    • com.sun.security.jgss.krb5.initiate — Invoked for the Java client.

    • com.sun.security.jgss.krb5.accept — Invoked for the WebLogic Server instance that is represented by a Kerberos identity and that hosts the Web application to which the client wants access.

    For each login entry, options are included that:

    • Require that authentication of the principal must succeed (that is, the user of the client application who is defined in the Microsoft domain).

    • Set useKeyTab to true, which causes the principal's key to be obtained from the keytab.

    • Identify the name of the keytab.

    • Set storeKey to true, which causes the principal's key to be stored in the Subject.

    • Optionally, set the debug option to true.

    The following example shows JAAS configuration file for the Kerberos login module used for the principal negotiatetester, who is defined in the Microsoft domain, SECURITYQA.COM, in which the Active Directory server runs:

    com.sun.security.jgss.krb5.initiate {
       com.sun.security.auth.module.Krb5LoginModule 
       required principal="negotiatetester@SECURITYQA.COM" 
       useKeyTab=true 
       keyTab=negotiatetester_keytab storeKey=true debug=true; };
     
    com.sun.security.jgss.krb5.accept {
       com.sun.security.auth.module.Krb5LoginModule 
       required principal="negotiatetester@SECURITYQA.COM" 
       useKeyTab=true keyTab=negotiatetester_keytab storeKey=true debug=true; };
    
  3. In the Java command that starts the client application, pass the following values as arguments:

    • The Microsoft domain in which the Active Directory server runs

    • The host name of the computer running the Kerberos Key Distribution Center (KDC) server

    • The JAAS configuration file that identifies the Kerberos login module

    • The javax.security.auth.useSubjectCredsOnly=false property, which specifies that it is permissible to use an authentication mechanism other than Subject credentials

    • The name of the Java SE client class

    • The Web application resource to which access is requested

    For example:

    java -Djava.security.krb5.realm = SECURITYQA.COM\
    -Djava.security.krb5.kdc = rno05089.example.com\
    -Djava.security.auth.login.config = negotiatetester_krb5Login.conf\
    -Djavax.security.auth.useSubjectCredsOnly = false\
    RunHttpSpnego http://myhost.example.com:7001/AuthenticatedServlet.jsp
    

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 the JAAS login file in the java.security.auth.login.config startup argument for WebLogic Server, as described in Using Startup Arguments for Kerberos Authentication with WebLogic Server.

Notes:

For JDK 6.0, the JAAS Login Entry names are com.sun.security.jgss.krb5.initiate and com.sun.security.jgss.krb5.accept.

Example 6-2 shows a sample JAAS login file for Kerberos authentication. Significant sections are shown in bold.

Example 6-2 Sample JAAS Login File for Kerberos Authentication

com.sun.security.jgss.krb5.initiate {

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

com.sun.security.jgss.krb5.accept {

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

};

For the principal option, specify the value of the userPrincipalName attribute of the account under which the service is running. (Incorrectly specifying the user principal name results in an error such as "Unable to obtain password from user.")

The keytab file specified in the keytab option must be accessible by the WebLogic Server process. Ensure that the appropriate permissions are set. If you are unsure of the search path WebLogic Server is using, provide the absolute path to the file. Make sure you enclose the path in double quotes, and replace any backslash (\) in the path with a double backslash (\\) or a forward slash (/).

Configuring the Identity Assertion 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. See Configuring a Negotiate Identity Assertion Provider and "Configure Authentication and Identity Assertion providers" in the Oracle WebLogic Server Administration Console Help.

Using Startup Arguments for Kerberos Authentication with WebLogic Server

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

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

where

Java GSS messages are often very useful during troubleshooting, so you might want to add -Dsun.security.krb5.debug=true as part of the initial setup.

Verifying Configuration of SSO with Microsoft Clients

To verify that SSO with Microsoft clients is configured properly, 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.