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, 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,
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 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 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
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.
Since WebLogic Server reads ACLs from the weblogic.properties 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
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 that are compliant
with the LDAP specification.
Installing the WebLogic LDAP realm
- Edit the ldaprealm.properties 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 ldaprealm.properties
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.
- 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. If you set weblogic.security.ldaprealm.authentication to external, this property must be set
to true.
- weblogic.security.ldaprealm.principal
- 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.
- 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 and Novell NDS support simple.
- weblogic.security.ldaprealm.userAuthentication
- 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.
- 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.groupDN
- Set this property to the list of attributes that, combined with the
weblogic.security.ldaprealm.groupNameAttribute,
uniquely identifies a group in the LDAP server.
- weblogic.security.ldaprealm.groupNameAttribute
- Set this property to the attribute that identifies the name of a group. It
is usually the common name.
- weblogic.security.ldaprealm.groupIsContext
- 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.
- weblogic.security.ldaprealm.groupUsernameAttribute
- Set this property to the name of the attribute that contains a
group member in a group entry.
- Add the following property to your weblogic.properties
file:
weblogic.security.realmClass=\
weblogic.security.ldaprealm.LDAPRealm
-
If you want to cache lookups in WebLogic Server, see Administering the CachingRealm
security realm for instructions on enabling and tuning
the cache.
- 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.
- 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:
http://localhost:7001/AdminRealm
- 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 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
# 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
|
This example contains example properties for a Novell NDS Server:
# Directory Server Properties
weblogic.security.ldaprealm.url=ldap://ldapserver:636
weblogic.security.ldaprealm.principal=cn=Admin,o=airius.com
weblogic.security.ldaprealm.credential=*REPLACE-ME*
weblogic.security.ldaprealm.ssl=true
weblogic.security.ldaprealm.authentication=simple
weblogic.security.ldaprealm.userAuthentication=bind
#
# User Schema
weblogic.security.ldaprealm.userDN=o=airius.com,ou=People
weblogic.security.ldaprealm.userNameAttribute=cn
# Group Schema
weblogic.security.ldaprealm.groupDN=o=airius.com,ou=Groups
weblogic.security.ldaprealm.groupNameAttribute=cn
weblogic.security.ldaprealm.groupUsernameAttribute=member
|
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:
$ ... -Dweblogic.security.realm.debug=true ... \
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.
|
