Administering the WebLogic Windows NT security realm

Introduction

Setting up and configuring NTRealm

Testing NTRealm

Troubleshooting NTRealm

Further troubleshooting and help

Change history

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. After installing NTRealm, WebLogic Server queries a Windows NT domain controller for information on users and groups instead of weblogic.password and weblogic.security.group properties in the weblogic.properties file. 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 and you do not have to restart WebLogic Server whenever you make a change.

NTRealm realm 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 you define 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. If you run WebLogic Server from the command line, NTRealm authentication will not succeed. See Using WebLogic Server as an NT 4.0 service 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, however, you can avoid having to restart as often. Changing Windows NT group membership allows you to manage individual users' access to WebLogic Server resources dynamically.

Setting up the WebLogic Windows NT realm

1. Edit the ntrealm.properties file, which you can find in the classes/weblogic/security/ntrealm directory. The ntrealm.properties file contains a single property that specifies the Windows NT Primary Domain Controller. The Primary Domain Controller is the computer where users and groups are defined for the domain. Here is an example that defines computer "hudson" in domain "domainj.com" as the Primary Domain Controller:

     weblogic.security.ntrealm.domain=hudson.domainj.com

   You can set the property to "." if the local computer (where the WebLogic Server executes) is the Primary Domain Controller.

   You can save the edited file in the WebLogic home directory (the directory where you start the server). NTRealm first looks for the file in the WebLogic home directory, and, if it is not found there, in the classes/weblogic/security/ntrealm directory.

2. Add the following property to your weblogic.properties file:

     weblogic.security.realmClass=\
         weblogic.security.ntrealm.NTRealm

3. Set up caching for the NTRealm. See Administring the WebLogic caching realm for help.

4. 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. To verify that this is true:

   Log into Windows NT with an Administrator account. 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.

5. Make sure that your PATH environment variable includes the weblogic\bin directory. The WebLogic Server loads Wlntrealm.dll from this directory.

6. Start WebLogic Server.

Testing 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

Diagnosing an NTRealm startup failure

1. The most common configuration problem with NTRealm has to do with Windows NT policies and 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.

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

Further troubleshooting and help

Information on Windows NT and NT Realms

NTRealm supports running on any machine that is a member of a Domain. A NTRealm can be run on the Primary Domain Controller (PDC) machine,and, additionally, NTRealm also supports running on any machine that is a member of a Domain and wants to use a second, mutually trusted, Domain. In that case, the two Domains must have an explicit mutual trust relationship set up. NTRealm does not support having a stand alone machine trying to authenticate to a Domain that it's not a member of.

If a stand alone machine is a PDC of it's own Domain, it can and should be able to authenticate to that Domain, however without a mutually trusted relationship set up with a second Domain, the local machine will be the only user/group store that works.

Windows2000 and NT Realms

There are a few differences between running on Windows2000 versus Windows NT. With Windows 2000, since all Domain Controllers now have an LDAP interface, it's recommended that cusomters use the LDAPRealm (V2) to authenticate against the Windows user and group store (via the ActiveDirectory LDAP server).

It is possible to use NTRealm to authenticate against a Windows 2000 ActiveDirectory PDC, but only from a machine which is a member of the domain, not the domain controller itself. Further, there is no way to authenticate to the local user and group store if the machine running NTRealm is a member of a Domain.

Also, on Windows 2000 there is a tool, 'Local Users and Groups,' you can use to manage local users and groups. It is available on computers running Windows 2000 Professional and member servers running Windows 2000 Server. To open, click Start, point to Settings, and then click Control Panel. Double-click Administrative Tools, and then double-click Computer Management. For further information, please see the help provided through Windows 2000.

Testing and errors

The first item in development with NTRealm is trying the internal unit test utility which is built into NTRealm. This administers a complete functional sweep of NTRealm features and will tell you immediately whether your configuration will work or not. Do the following:

> java weblogic.security.ntrealm.NTRealm username password

The first line of output will tell you if the username/password worked for authentication. For example:

auth?joe <--- means authentication worked for user 'joe'

auth?null <--- means it did not authenticate properly

The remaining output of the unit test utility will enumerate all the users and groups available to it.

If the NTRealm unit test utility comes up with an error immediately, stating that the client/user-running-WebLogic does not have the privleges to run NTRealm, you need to update the Permissions (or Rights) for that Windows user running the WebLogic instance.

To update the Priviledges/Rights on WindowsNT:

  Start->Programs->Administrative Tools->User Manager
   (a new window appears)
   Under the menu Policies->User Rights
   Select the "Show Advanced User Rights" checkbox in the
    lower left corner.
   Give the following Priviledges to the user:

     "Act as part of the operating system"
     "Create a token object"
     "Replace a process level token"

To update the Priviledges/Rights on Windows2000:

  Start->Programs->Administrative Tools->Local Security Policy
   (a new window appears, then in the left hand tree)
     Local Policies->User Rights Assignment

     "Act as part of the operating system"
     "Create a token object"
     "Replace a process level token"

For Windows2000 it is also required for the user running WebLogic to be a member of the Administrators group.

For both versions of Windows, make certain to set all above Rights to the specific user and that user is a member of the Administrators group, then reboot to make certain all modifications take effect.

Expalnation of common errors (from winerror.h)

OS error=1326

// MessageId: ERROR_LOGON_FAILURE
// MessageText:
//  Logon failure: unknown user name or bad password.
//
#define ERROR_LOGON_FAILURE              1326L

  This error is incorrectly described. for the purposes of NTRealm,
  it means that the client machine running the NTRealm unit test
  utility does not have a trust relationship with the attempted
  PDC, the client machine might not be a member of that Domain,
  or the Domain might simply not trust the client.


OS error=53

// MessageId: ERROR_BAD_NETPATH
// MessageText:
//  The network path was not found.
//
#define ERROR_BAD_NETPATH                53L

  Network error meaning that the path to the PDC cannot be found.
  probably due to a mispelling or mixing up the Domain name with
  the hostname of the Domain Controller.


OS error=1722

// MessageId: RPC_S_SERVER_UNAVAILABLE
// MessageText:
//  The RPC server is unavailable.
//
#define RPC_S_SERVER_UNAVAILABLE         1722L

  The Domain Controller will no longer answer these requests. If
  this error is seen, please report it to WebLogic support immediately
  with configuration information.

Change history

Release 5.0, Beta 1

WebLogic Server alternative realms, including the Windows NT realm, have been reorganized for this release.

1. The new CachingRealm hosts all alternative realms, including NTRealm. See Administering the WebLogic Caching Realm for help using this realm.

2. It is no longer necessary to duplicate the "guest" user and "system" user in your Windows NT domain.

3. Also, you no longer have to create the "everyone" group in Windows NT. All users automatically belong to the "everyone" group. Note: the WebLogic Console and the AdminRealm servlet display an "everyone" group containing all users except those from the Windows NT domain. For greater performance, NTRealm does not retrieve users from the Windows NT domain to create the "everyone" group.

4. The weblogic.security.ntrealm.NTDelegate class no longer has a main() that tests connectivity to your domain controller.

5. You must still run WebLogic Server on a Windows NT domain controller. This restriction should be removed in the next beta release.

Release 4.5

Initial release.

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 11/29/1999