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.
- 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.
|
- 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."
- 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:
- 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.
- Display the realm in the WebLogic Console. The Console displays all the users and ACLs known in the realm.
- 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.
- 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.
- 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.
- 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
- Verify that Service Pack 8 or higher has been installed correctly using the steps outlined above in this document.

|