Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy

2. # Administering the WebLogic Windows NT security realm Introduction Setting up and configuring NTRealm Testing NTRealm Trusted Relationships Troubleshooting NTRealm Change history Several fixes and improvements were made in NTRealms with Service Pack 8 on WebLogic Server 5.1. It is recommended that NTRealms users upgrade their Server to the latest WebLogic Service Pack to take advantage of these enhancements. In the following document there are tips and instructions for all NTRealms users who use WebLogic 5.1, but some of the details are only for users who have installed Service Pack 8 or higher. To view the original version of our documentation see http://www.weblogic.com/docs51/admindocs/ntrealm.html This document describes how to set up and configure the WebLogic Windows NT security realm (NTRealm) for your WebLogic Server. NTRealm is an alternative authenticating realm for WebLogic Server. Instead of using weblogic.password and weblogic.security.group properties in the weblogic.properties file, the NTRealm and WebLogic Server query a Windows NT domain controller for information on users and groups. Note, however, that Access Control Lists (ACLs) are still defined in the weblogic.properties file. # Introduction Using NTRealm, you can manage Windows and WebLogic Server users in one place. You do not have to edit the weblogic.properties file whenever a user joins or leaves. You also do not have to restart WebLogic Server whenever you make a change. NTRealm provides authentication (users and groups), but not authorization (ACLs). ACLs are defined in the weblogic.properties file with properties that begin with 'weblogic.allow'. WebLogic Server accesses NTRealm through CachingRealm, a realm that hosts alternative realms such as NTRealm. CachingRealm also caches information it looks up to improve performance. The cache is disabled by default. See Administering the WebLogic Caching Realm for information on enabling and tuning the cache. CachingRealm uses the default realm, WLPropertyRealm, for ACLs and as a backup for users not found in NTRealm. Users defined in the weblogic.properties file are valid unless overridden in the Windows NT domain. CachingRealm always queries NTRealm first, so a user defined in NTRealm overrides a user with the same name in the properties file. The "system" user must be declared in the properties file to allow WebLogic Server to start. The "system" user may also be declared in the Windows NT domain. If it is, clients must supply the Windows NT "system" user password to authenticate successfully. NTRealm requires that you run the WebLogic Server as a Windows administrative user who can read security-related data from the Windows NT Domain Controller. To use NTRealm, you must run WebLogic Server as a Windows NT service on a computer in the Windows NT domain. You do not have to run it on a domain controller. ### Important notes: If you run WebLogic Server from the command line, NTRealm authentication will not succeed. See Using WebLogic Server as an NT 4.0 Service at http://www.weblogic.com/docs51/admindocs/ntservice.html for instructions on running WebLogic Server as a Windows NT service. Since the WebLogic Server reads ACLs from the weblogic.properties file at startup time, you must restart the WebLogic Server after you change an ACL. If you use groups with your ACLs, it is possible to avoid having to restart. Change your Windows NT group membership to allow yourself to manage individual users' access to WebLogic Server resources dynamically. # Setting up the WebLogic Windows NT realm There is no longer a need to edit or worry about the ntrealm.properties file in WebLogic 5.1.0 with Service Pack 8 or higher. In fact, it is recommended that you remove all instances of the ntrealm.properties file. For user with Service Pack 8 and above on WebLogic 5.1.0, you can specify all properties in the weblogic.properties file. However, if an ntrealm.properties file exists in the weblogic root installation (i.e. c:\weblogic) then WebLogic will read in this file, and any properties in this file override properties that you may have set in weblogic.properties. Tip: If you have Service Pack 8 or higher, you may find it simplifies matters to get rid of all ntrealm.properties files and to make all the required changes to your weblogic.properties file. Verify that WebLogic is running Service Pack 8 or higher. Open a command shell, set your environment, and type "java weblogic.Admin t3://WebLogicHost:WebLogicPort system mySystemPassword" You should see in the output:
       **********************************
       WebLogic Build: 5.1.0 Service Pack 8
       **********************************
- If you do not see a "Service Pack" number, then your Service Pack has not been installed correctly. Add the following property to your weblogic.properties file: weblogic.security.realmClass=weblogic.security.ntrealm.NTRealm Add the following property to your weblogic.properties file: weblogic.security.ntrealm.domains=hostname1 Please note that hostname1 is the DNS name of your Primary Domain Controller. If you enter the domain name itself, NTRealms will not start correctly. For most configurations, you will only need to specify a single hostname, unless you are setting up NTRealms to search multiple trusted domains. In the case that you require trusted domains, enter the string of trusted domain names delimited by commas. For example: weblogic.security.ntrealm.domains=hostname1, hostname2 Copy the file wlntrealm.dll from Service Pack 8 or higher into the /bin directory of your weblogic server install (e.g. c:\weblogic\bin). Verify that the /bin directory is in your system-wide PATH environment variable. (optional) Set up caching for the NTRealm. See Administrating the WebLogic Caching Realm for help. The WebLogic Caching Realm greatly improves performance. To access user and group information, the WebLogic Server must be able to make system calls on the Windows NT computer where the WebLogic Server is running. In other words, WebLogic needs the proper privileges to be able to talk to the Primary Domain Controller to perform authentication. To verify that this is true:
  Log into Windows NT with an Administrator account. Note that you are logging onto your local NT machine, where you have installed WebLogic. There is no need to log onto your Primary Domain Controller. Start User Manager, which is in the Administrative Tools program group. Select the user that will run the WebLogic Server. Choose User Rights from the Policies menu. Check the Show Advanced User Rights checkbox. Select Act as part of the operating system from the Rights list. Click the Add button and enter the name of the user under whose account the WebLogic Server will execute. Select Replace Process Level Token from the Rights list. Click the Add button and enter the name of the user under whose account the WebLogic Server will execute. Make sure that your system-wide PATH environment variable includes the weblogic\bin directory. The WebLogic Server loads Wlntrealm.dll from this directory. Start WebLogic Server as an NT Service.

# Trusted Relationships

You may wish to set up a trusted relationship between two NT Servers so that they can share user and group information. If you set up a trusted relationship, WebLogic can then query both domains to get a combined list of users and groups from both stations. A trusting relationship has the following structure: One of the two members of the relationship will be designated as being "Trusted" while the other member of the relationship is "Trusting." Setting this up requires some extra steps. What follows in an example of having a TRUSTED_DOMAIN on Server1 and TRUSTING_DOMAIN on Server2. Both servers are Primary Domain Controllers.

1. Each computer must be added to the other's domain.

   Open each server's "Server Manager." Click the Computer tab and choose the Add to Domain option. In the new window, click the appropriate checkbox (for this example it is the NT Workstation or Server checkbox) and type in the computer name into the field below. The end result is that Server1 is now a member of TRUSTING_DOMAIN while Server 2 is a member of TRUSTED_DOMAIN.

2. In this example we will make ServerA the "Trusted" member of our Trust relationship. Server B will become the "Trusting" member of this relationship.

   Open the User Manager on Server1 Under the Policies tab, select Trust Relationships Click the Add button on the right side of the Trusting Domains box Type the domain of Server2 (TRUSTING_DOMAIN) as well as the administrative password for Server1 Under the Policies tab, select Trust Relationships Click the Add button on the right side of the "Trusted Domains" box Type the domain of Server1 (TRUSTED_DOMAIN) as well as the administrative password for Server1

You now have established a trusted relationship between Server1 and Server2–a dialogue box should pop up confirming this fact that says "Trust Relationship with TRUSTED_DOMAIN successfully established."

3. Open the weblogic.properties file and add the following line:

   weblogic.security.ntrealm.domains=server1, server2

   Please note that server1 and server2 are the DNS names of the two computers, and not the domain names.

   Note: This example was only tested with multiple PDC's (rather than one PDC and a BDC), but both configurations should work.

# Testing the NTRealm

After you have started WebLogic Server with NTRealm installed, you can perform the following checks to test that it is working properly:

1. Load the AdminRealm servlet in a browser. This servlet displays information about the realm the WebLogic Server is using, and it lists all known users, groups, and ACLs. Load the servlet using a URL like this:

   http://localhost:7001/AdminRealm

   The default weblogic.properties file has an ACL that restricts the AdminRealm servlet to the "system" user.

2. Display the realm in the WebLogic Console. The Console displays all the users and ACLs known in the realm.

3. Add an ACL to your weblogic.properties file for the helloWorld example servlet. First find the weblogic.httpd.register property for the helloWorld servlet and make sure that it is uncommented. Add the following property:

   weblogic.allow.execute.weblogic.servlet.helloWorld=username,groupname

   Replace username with the name of a user in your Windows NT domain. Replace groupname with the name of a group in your Windows NT domain–but select a group that does not include username. Restart the WebLogic Server and then load the helloWorld servlet with a URL like this:

   http://localhost:7001/helloWorld

   Try entering the name and password for a Windows NT user who is not included in the ACL you added for the servlet. You should get a message telling you that you are not authorized. Try entering the name and password of a Windows NT user who you did include in the ACL, either as an individual or a member of the group. The servlet should load and display the "Hello World" message.

# Troubleshooting NTRealm

This section gives instructions on how to diagnose an NTRealm startup failure.

1. Add the weblogic.security.realm.debug=true property to the weblogic.properties file. Then watch the log for messages. The messages may help you determine the cause of the failure. Sometimes the file "weblogicerr.log" (which gets generated into the root weblogic directory, for example: c:\weblogic) contains helpful information.

2. The most common configuration problems with NTRealm have to do with Windows NT policies and specifically the user whose account runs WebLogic Server. The user account that runs WebLogic Server requires special permissions to access the Windows NT domain. The steps for granting this permission are in the configuration instructions. For example, you may get messages like this:

           <Security Realm> Disabling guest access
            Unable to adjust token privileges
                           Unable to adjust token privileges
           java.lang.SecurityExceptioin: Unable to assert all required privileges

   This means that you have not checked the box for replace process level token from the Rights list as shown in the "Setting up the WebLogic Windows NT Realm" section.

3. WebLogic is reading values in from an ntrealm.properties file. Make sure that none exist on your computer. Sometimes an old WebLogic administrator may have placed this file under c:\winnt, c:\winnt\system32, or c:\winnt\system

4. Verify that Service Pack 8 or higher has been installed correctly using the steps outlined above in this document.

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher. Last updated 1/22/2001