Administering the WebLogic LDAP security realm
- Installing the WebLogic LDAP realm
- Testing your LDAP realm
- Sample ldaprealm.properties
- 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, the WebLogic Server uses a Lightweight Directory Access
Protocol (LDAP) service to authenticate users in place 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.
The WebLogic LDAP realm currently supports Netscape Directory Server
and Microsoft Site Server.
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 weblogic.properties 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 the 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.
- Users and groups are cached in the WebLogic Server as Enterprise Java Beans.
This reduces the frequency of LDAP lookups.
- Support for Microsoft Site Server and Netscape Directory Server.
- Secure (SSL) network connections between WebLogic Server and
the Netscape and Microsoft LDAP servers.
Currently, the LDAP realm has the following limitations:
- The WebLogic realm defers to the LDAP realm for authentication,
but not for authorization. Authorization is accomplished with
access control lists (ACLs), which are defined in the
weblogic.properties 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 ldaprealm.properties file.
- The "system" user must be defined in the weblogic.properties file and in your LDAP
server. The LDAP "system" user must be a member of the LDAP group that
has administrative privileges in the LDAP server.
-
The "guest" user must be defined in the LDAP server with the
password "guest".
- In the WebLogic property file realm, the "everyone" group
automatically includes all users. You must create an "everyone" group
and add every WebLogic Server user to its membership list, including
the "guest" and "system" users.
- Although the WebLogic realm extends a ManageableRealm, the methods
that add, remove, or modify realm users and groups are not currently supported.
Since the WebLogic Server reads ACLs from the weblogic.properties file at start up
time, you must still restart the 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 requires an LDAP user
with read access on all directory fields used for authentication.
The WebLogic LDAP realm currently supports Netscape Directory Server and Microsoft Site Server.
The LDAP realm retrieves configuration parameters from an ldaprealm.properties file. Although
we cannot support LDAP servers we have not tested and certified, the
properties in the ldaprealm.properties file are designed to provide a
generalized configurable interface for LDAP servers.
Installing the WebLogic LDAP realm
- Edit the ldaprealm.properties file, which you will find in the classes/weblogic/security/ldaprealm directory.
You can save the edited file in the WebLogic home directory (the directory where you start
the server). The LDAP realm first looks for the file in the WebLogic home directory,
and, if it is not found there, in the
classes/weblogic/security/ldaprealm directory.
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 ldaprealm.properties
file has sections for Netscape Directory Server and Microsoft Site
Server. Uncomment the section for your server and edit the properties
for your environment.
- weblogic.security.ldaprealm.url
- 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.
- weblogic.security.ldaprealm.ssl
- Set this property to false
if the LDAP server is not configured to use SSL.
- weblogic.security.ldaprealm.principal
- Set this property to the distinguished name of the LDAP user that
the WebLogic Server will use to connect with the LDAP server. This
user must be able to list LDAP users and groups.
- weblogic.security.ldaprealm.credential
- Set this property to the password that authenticates the principal
defined with the weblogic.security.ldaprealm.principal property.
- weblogic.security.ldaprealm.authentication
- 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 supports simple.
- weblogic.security.ldaprealm.userDN
- Set this property to the list of attributes that, when combined
with the attribute named in the weblogic.security.ldaprealm.userNameAttribute property,
uniquely identifies an individual.
- weblogic.security.ldaprealm.userNameAttribute
- 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.
- weblogic.security.ldaprealm.userCommonNameAttribute
- Set this property to the common name attribute, usually "cn".
- Add the following property to your weblogic.properties
file:
weblogic.security.realmClass=\
weblogic.security.ldaprealm.LDAPRealm
- Start the WebLogic Server.
Testing your LDAP realm
After you have started up the WebLogic Server with the LDAP realm
installed, you can perform the following checks to test that it
is working properly.
- Load the T3AdminRealm servlet in a browser. This servlet displays
information about the realm the WebLogic Server is using, and it
includes lists of all known users and groups. Load the servlet using a URL
like this:
http://localhost:7001/T3AdminRealm
- 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 not commented out. Add the following
property:
weblogic.allow.execute.weblogic.servlet.helloWorld=\
username,groupname
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 the WebLogic Server and then load the helloWorld servlet with an ACL like this:
http://localhost:7001/helloWorld
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.
Sample ldaprealm.properties
The ldaprealm.properties 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
weblogic.security.ldaprealm.url=ldap://localhost:389
weblogic.security.ldaprealm.principal=cn=Directory Manager
weblogic.security.ldaprealm.credential=jj..blake
weblogic.security.ldaprealm.ssl=false
# User Schema
weblogic.security.ldaprealm.userDN=o=airius.com, ou=People
weblogic.security.ldaprealm.userNameAttribute=uid
weblogic.security.ldaprealm.userPasswordAttribute=userpassword
# Group Schema
weblogic.security.ldaprealm.groupDN=o=airius.com, ou=Groups
weblogic.security.ldaprealm.groupNameAttribute=cn
weblogic.security.ldaprealm.groupUsernameAttribute=uniquemember
|
This example contains example LDAP realm properties for a Microsoft
Site Server:
# Directory Server Properties
weblogic.security.ldaprealm.url=ldap://172.17.10.46:1002
weblogic.security.ldaprealm.principal=cn=admin
weblogic.security.ldaprealm.credential=adminpw
weblogic.security.ldaprealm.ssl=false
weblogic.security.ldaprealm.authentication=simple
# User Schema
weblogic.security.ldaprealm.userDN=o=Microsoft, ou=Members
weblogic.security.ldaprealm.userNameAttribute=cn
weblogic.security.ldaprealm.userPasswordAttribute=userpassword
weblogic.security.ldaprealm.userCommonNameAttribute=cn
# Group Schema
weblogic.security.ldaprealm.groupDN=o=Microsoft, ou=Groups
weblogic.security.ldaprealm.groupNameAttribute=cn
weblogic.security.ldaprealm.groupIsContext=true
weblogic.security.ldaprealm.groupUsernameAttribute=memberObject
|
Troubleshooting the LDAP realm
- Diagnosing an LDAP realm startup failure
-
When you start the WebLogic Server with the LDAP realm installed,
you should see messages similar to
these in the WebLogic Server log:
Fri Jan 22 17:39:07 PST 1999:<I> \
<LDAP> LDAP connectivity initialized
Fri Jan 22 17:39:08 PST 1999:<I> \
<LDAP> Created connection to LDAP server
If you do not see the second message, the WebLogic Server could not
locate the LDAP server. To help diagnose the problem, you can start
the WebLogic Server as described in Command line
examples, and add a system property set to display debugging
messages:
$ ... -Dweblogic.security.ldaprealm.verbose=true \
-Dweblogic.security.ldaprealm.ejb.verbose=true ... \
Then watch the log for <LDAP> 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
-
The LDAP realm uses WebLogic EJBs to represent users and groups
internally. The EJBs are cached in the WebLogic Server to avoid overly
frequent lookups in the LDAP server.
The Deployment Descriptor for the LDAPUserEntity EJB specifies that up
to 1000 users can be cached at a time and users not active for at
least three minutes may be dropped from cache.
The LDAPGroupEntity EJB Deployment Descriptor allows 10 groups in
cache at a time and groups not active for 1000 seconds (about 17
minutes) can be dropped from cache.
When you add new users or groups to your LDAP server, the LDAP realm
should recognize them immediately. However, if you delete a user or
group, change a user password, or add or delete group members, the
WebLogic Server does not recognize the change until the user or group
EJB has been dropped from the cache. If you have more than 1000 users
and 10 groups, you can try flushing the cache by loading the
T3AdminRealm servlet in a browser. Since this servlet pulls all users
and groups from the LDAP server into the WebLogic Server, the cached
EJBs should be replaced. Otherwise, you must either reboot the WebLogic
Server or wait until the EJBs are dropped from the cache.
Change history
- Release 4.5
- Initial release.
