BEA Logo BEA WebLogic Server Release 5.0

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

Administering the WebLogic LDAP security realm

Installing the WebLogic LDAP realm
Testing your LDAP realm
Troubleshooting the LDAP realm
Change history

This document describes how to install and configure the WebLogic LDAP security realm for your WebLogic Server. After installing the LDAP realm, WebLogic Server uses a Lightweight Directory Access Protocol (LDAP) service to authenticate users in place of weblogic.password and properties in the file. Access control lists (ACLs) are still defined in the file.

The WebLogic LDAP realm currently supports Netscape Directory Server, Microsoft Site Server, and Novell NDS.

Using an LDAP directory to authenticate users provides several benefits. First, you can manage users for your organization in one place--the LDAP directory. You do not have to edit the file whenever a user joins or leaves your company. This also means you do not have to restart the WebLogic Server whenever you change a user.

The WebLogic LDAP realm provides these features:

  • Simple authentication. The LDAP realm sends the username and password to the LDAP server for authentication.

  • Strong authentication. After the client has negotiated an SSL connection with WebLogic Server, the LDAP realm retrieves the user's common name from the X509 certificate and searches the LDAP server for that name. LDAP realm does not verify the certificate, since that is performed by the SSL protocol.

  • Full support for groups defined in the LDAP server.

  • Caching. LDAPRealm is hosted by the WebLogic CachingRealm security realm. This realm delegates to LDAPRealm and caches user and group lookups. See Administering the WebLogic CachingRealm security realm for instructions on enabling and tuning the cache.

  • Support for Microsoft Site Server, Netscape Directory Server, and Novell NDS.

  • Secure (SSL) network connections between WebLogic Server and LDAP servers.

Currently, the LDAP realm has the following limitations:

  • WebLogic Server defers to the LDAP realm for authentication, but not for authorization. Authorization is accomplished with access control lists (ACLs), which are defined in the file.

  • The LDAP realm requires a user with read access to security-related fields in the LDAP server for all users and groups. This principal LDAP user and password are defined in the realm configuration in the file.

Since WebLogic Server reads ACLs from the file at start up time, you must still restart WebLogic Server after you change an ACL. If you use groups with your ACLs, however, you can avoid having to restart the server as often. Changing group membership in the LDAP server allows you to manage individual users' access to WebLogic Server resources dynamically.

The WebLogic LDAP realm currently supports Netscape Directory Server, Microsoft Site Server, and Novell NDS. The LDAP realm retrieves configuration parameters from an file. Although we cannot support LDAP servers we have not tested and certified, the properties in the file are designed to provide a generalized configurable interface for LDAP servers that are compliant with the LDAP specification.

Installing the WebLogic LDAP realm

  1. Edit the file, which you will find in the classes/weblogic/security/ldaprealm directory. Save the edited file in the WebLogic home directory (the directory where you start the server).

    The properties in this file describe how to establish LDAP connections to your LDAP server and how to find users and groups in your LDAP directory. The information includes:

    • The network location of the LDAP service
    • Whether to use SSL for LDAP connections
    • Distinguished name and credential (password or certificate) of user for LDAP connections
    • Type of authentication to use for LDAP connections
    • User schema: attributes that locate unique users in the LDAP directory
    • Group schema: attributes that locate groups and their members in the LDAP directory

    The file has sections for Netscape Directory Server, Microsoft Site Server, and Novell NDS. Uncomment the section for your server and edit the properties for your environment.
    The location of your LDAP server. Change the url to the name of the computer where the LDAP server is running and the port number where it is listening. If you want WebLogic to connect to the LDAP server using SSL, be sure to use the LDAP server's SSL port in the url.
    Set this property to false if the LDAP server is not configured to use SSL. If you set to external, this property must be set to true.
    Set this property to the distinguished name of the LDAP user that WebLogic Server will use to connect with the LDAP server. This user must be able to list LDAP users and groups.
    Set this property to the password that authenticates the principal defined with the property.
    Set this property to simple for simple password authentication, CRAM-MD5 for a secure handshake authentication protocol, or none for no authentication. Netscape Directory Server supports CRAM-MD5. Microsoft Site Server and Novell NDS support simple.
    This property determines the method for authenticating users. If you set the property to local (appropriate for Netscape and Microsoft servers), LDAPRealm retrieves user data, including password, from the LDAP server and checks the password in WebLogic Server. If you set the value to external (appropriate for Novell NDS), LDAPRealm authenticates a user by attempting to bind to the LDAP server with the username and password supplied by the WebLogic client. If you use external authentication, you must also use SSL.
    Set this property to the list of attributes that, when combined with the attribute named in the property, uniquely identifies an individual.
    Set this property to the attribute that identifies the login name of the individual. This may be the common name, but is usually a shorter field, such as the User ID.
    Set this property to the list of attributes that, combined with the, uniquely identifies a group in the LDAP server.
    Set this property to the attribute that identifies the name of a group. It is usually the common name.
    This boolean property specifies how group membership is recorded in the LDAP server. Set the property to true true if each group entry contains one user. Set the property to false if there is one group entry containing an attribute for each group member.
    Set this property to the name of the attribute that contains a group member in a group entry.

  2. Add the following property to your file:\

  3. If you want to cache lookups in WebLogic Server, see Administering the CachingRealm security realm for instructions on enabling and tuning the cache.

  4. Start WebLogic Server.

Testing your LDAP realm

After you have started WebLogic Server with the LDAP realm 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 WebLogic Server is using, and it includes lists of all known users and groups. Load the servlet using a URL like this:

  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 file for the helloWorld example servlet. First find the weblogic.httpd.register property for the helloWorld servlet and make sure that it is not commented out. Add the following property:

    Replace username with the name of a user in your LDAP server. Replace groupname with the name of a group in your LDAP server -- but select a group that does not include username.

    Restart WebLogic Server and then load the helloWorld servlet with an ACL like this:


    Try entering the name and password for an LDAP user who is not included in the ACL you added for the servlet. You should get a message telling you that you were not authorized.

    Try entering the name and password of an LDAP 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.


The file contains sections for the Microsoft Site Server and Netscape Directory Server. You uncomment the section for your LDAP server and edit the properties with the correct information for your site.

The file contains three sections. The first section contains the properties that enable the WebLogic LDAP realm to connect to the LDAP server. The second section contains properties that describe how users are stored in the directory. The third section describes how groups are stored in the directory

Here are sample properties for the Netscape Directory Server:

  # Directory Server Properties Manager

  # User Schema, ou=People

  # Group Schema, ou=Groups

This example contains example LDAP realm properties for a Microsoft Site Server:

  # Directory Server Properties

  # User Schema, ou=Members

  # Group Schema, ou=Groups

This example contains example properties for a Novell NDS Server:

  # Directory Server Properties,*REPLACE-ME*
  # User Schema,ou=People

  # Group Schema,ou=Groups

Troubleshooting the LDAP realm

Diagnosing an LDAP realm startup failure

To help diagnose startup problem, you can start WebLogic Server, as described in Command line examples, and add a system property to display debugging messages:

 $ ... ... \

Then watch the log for <CachingRealm> and <LDAPRealm> messages. The messages will help you determine the cause of the failure.

LDAP realm does not appear to recognize certain changes made in the LDAP server

If you have enabled caching, CachingRealm caches users and groups internally to avoid overly frequent lookups in the LDAP server. Each type of object has a TTL (time-to-live) in the cache, which you can tune by setting properties in weblogic.server. If you make changes in the LDAP server, they will not be reflected in WebLogic Server until the cached object expires or is flushed to make room in the cache. The default TTL is 60 seconds for successful lookups and 5 seconds for unsuccessful lookups. Unless you tuned the cache to increase the TTL values, changes in the LDAP server should be recognized in WebLogic Server within one minute.

If some server-side code has performed a realm lookup, for example a getUser() call on the realm, the object returned by the realm cannot be released until the code releases it. This means that a user authenticated by WebLogic Server remains valid as long as the connection persists, even if you delete the user in the LDAP server.

Change history

Release 5.0

LDAPRealm is now hosted by CachingRealm. This means that LDAPRealm no longer uses Enterprise JavaBeans to cache lookups. CachingRealm ensures that the "system" user and "guest" user exist. You can define them in the LDAP server if you choose, but this is no longer necessary. CachingRealm also makes it unnecessary to define an "everyone" group in the LDAP server. All users are automatically members of the "everyone" group.

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 2/24/2000