WebLogic Pro - Resolve LDAP Connection Issues in BEA WebLogic Server

Resolve LDAP Connection Issues in BEA WebLogic Server
Determine the cause before you make the call
by Roula Korkmaz

August 20, 2004

So, you're having trouble with the lightweight directory access protocol (LDAP) connections in WebLogic Server (WLS). Maybe your authentication provider is unable to connect to LDAP. Perhaps the user cannot authenticate or can authenticate but does not have the required code. Maybe group membership fails or you are having trouble defining multiple authentication providers. Or maybe client authentication is just plain slow. Whatever your problem, we have some useful troubleshooting tips for when LDAP connection failures occur.

Authentication is the process whereby an authentication provider proves and verifies the identity of users or system processes. WebLogic Server offers several authentication providers, including the LDAP authentication provider that accesses external LDAP stores. WebLogic Server provides LDAP authentication providers that access Open LDAP, Netscape iPlanet, Microsoft Active Directory, and Novell NDS stores, as well as other LDAP stores.

You may experience one or more of several common authentication failures when defining an LDAP authentication provider. Let's do some troubleshooting and see if we can solve some of these issues.

Connection problems. If WebLogic Server cannot connect to the LDAP server, you need to verify that:

The LDAP server is up and running. If so, you could try to connect using an LDAP browser like www.iit.edu/~gawojar/ldap
The host name of the LDAP server is properly defined and recognized by the machine where WLS is running
The port number is correct (default is 389, or 636 for SSL)
The principal is a user that exists in LDAP and the full DN, not just the user ID, is configured as principal. The principal could be like:

Principal="uid=admin, 
	ou=Administrators, 
	ou=TopologyManagement, 
	o=NetscapeRoot"

The password is the principal's password.

Some common connection errors messages you might receive are:

LDAP error (49)—incorrect password (credentials)
LDAP error (32)—incorrect principal (user)

For a complete list of LDAP result codes check out http://docs.sun.com/source/816-5608-10/log.htm#15324.

Debug flags. You can enable the flags DebugSecurityAdjudicator, DebugSecurityAtn, DebugSecurityAtz, and DebugSecurityRoleMap by using the weblogic.Admin command-line utility to turn the debug options on and off dynamically. For example, to turn on DebugSecurityAtz on all administration instances of ServerDebug MBean (such as admin server or all managed server), use this code:

java weblogic.Admin -url t3://host:port 
	-username adminuser -password adminpwd SET 
	-type ServerDebug -property DebugSecurityAtz 
	true

Note that although changing the value of the debug attributes will be reflected in the ServerDebugMBean status, the output will not be generated until the admin server is restarted.

You can also edit the config.xml and the MBean element in the <ServerDebug/> stanza for each server that you want to debug and set it to a value of "true" to enable or "false" to disable:

<ServerDebug 
DebugSecurityAdjudicator="true"
	// for security adjucator debug
DebugSecurityAtn="true" 
	// for security authentication debug
DebugSecurityAtz="true"
	// for security authorization debug
DebugSecurityRoleMap="true"
	// for security role mapping debug 
Name="MyServer"/>

Then you must restart the admin server.

Make sure the StdoutDebugEnabled is set to "true". You could verify this in config.xml. Debug to stdout may be enabled via the console or via the command-line using:

-Dweblogic.StdoutDebugEnabled=true

The debug information will be logged into the server log as well as to the standard out. The server log file is specified at the startup by the message BEA-170019:

BEA-170019 Notice: The server log file fileName 
	is opened. All server side log events will be 
	written to this file.

User authentication failure. WLS connects first to LDAP and then tries to search for the user based on the "User Base DN" and the "User Filter" defined in the authentication provider. Once the user is found, WLS tries to authenticate using the password provided.

If authentication fails, after enabling the debug flags, search for the pattern getDNForUser in the log file to see why it failed. It is possible that either the user does not exist in LDAP (javax.security.auth.login.FailedLoginException) or the password is not correct (authentication failed error 49).

The search will be similar to:

<SecurityDebug><getDNForUser search 
	("ou=people,dc=beasys,dc=com", 
	"(&(uid=fred)(objectclass=person))", 
	base DN & below)

If the user does not exist, we will see this message:

<SecurityDebug><returnConnection 
	conn:netscape.ldap.LDAPConnection@e4bb3c>
javax.security.auth.login.FailedLoginException: 
	[Security:090302]Authentication Failed: 
	User fred denied

If the user password is not correct we will see that the full DN was retrieved from LDAP, but authentication fails:

<SecurityDebug> <DN for user fred: 
	uid=fred,ou=People,dc=beasys,dc=com>
<SecurityDebug> <authenticate user:fred with 
	DN:uid=fred,ou=People,dc=beasys,dc=com>
<Debug> <SecurityDebug>  
<authentication failed 49>

Group membership failure. After the user is authenticated, WLS searches to get the list of the groups to which this user belongs so that it can role map between groups and roles. This search is done using the "Static Group DNs from Member DN Filter" defined in the authentication provider. For example, for iPlanet this search looks like:

(&(uniquemember=%M)
	(objectclass=groupofuniquenames))

The %M is replaced by the full DN of the user for which we are locating groups. This search could be changed based on your LDAP hierarchy. If the user does not belong to any group, or if the search criteria are not valid, we will see similar debug messages:

<SecurityDebug> 
	<getDNForUser search("ou=people,dc=
	beasys,dc=com", "(&(uid=fred)
	(objectclass=person))", base DN & below)>
<SecurityDebug> 
	<DN for user fred: uid=fred,ou=People, 
	dc=beasys,dc=com>
<SecurityDebug> 
	<search("ou=groups, dc=beasys,dc=com", 
	"(&(uniquemember=uid=fred,ou=People, 
	dc=beasys,dc=com) (objectclass=
	groupofuniquenames))", base DN & below)>
<SecurityDebug> 
	<Result has more elements: false>

Note how the %M was replaced by the full DN of the user.

Role mapping failure. After the user is authenticated, and the groups are found, WLS compares the list of users and groups to the principals that are allowed access the resource. It then either grants or denies access. Thus a call to the role mapper is performed to determine the roles of the users and groups. After that, WLS makes a call to the authorization provider, which results in granting or denial of access to the requested resource. Listing 1 shows an example of a user being denied access because his role does not permit him to do what he's trying to do—boot the server.

If multiple authentication providers exist, then it is up to the adjudicator to decide, based on the authorization access decisions, to grant or deny access to the requested resource.

Performance issues. The groups to which the user belongs are compiled as a list. Then WLS finds all the groups to which each group in the list belongs. This happens recursively until a group belongs to no other groups.

So, for example, if user U1 belongs to group G1 and G2, and group G1 belongs to group G3, then user U1 belongs to G1, G2, and G3. Group membership is determined for U1 (results in G1 and G2), then for G1 (results in G3), then for G2 (results in nothing) and then G3 (results in nothing). This recursive search may result in performance issues, particularly if there are many groups in the LDAP. To avoid such performance issues and limit the number of recursive calls, we can configure two parameters: GroupMembershipSearching and MaxGroupMembershipSearchLevel.

The GroupMembershipSearching attribute controls whether group searches are limited in depth, or unlimited. The default is an unlimited search. If a limited search is configured, the MaxGroupMembershipSearchLevel attribute specifies the limitation. If an unlimited search is configured, the MaxGroupMembershipSearchLevel is ignored.

The MaxGroupMembershipSearchLevel attribute controls the depth of a group membership search, if the GroupMembershipSearching attribute has been set to limited. Otherwise, it is ignored. The default value is 0.

Note that these parameters are available in WLS 8.1 SP3. A patch is provided for WLS 8.1 SP1 and WLS 8.1 SP2.

Multiple authentication providers. We can configure multiple authentication providers. We should use the JAAS Control Flag attribute on the Authenticator-->General tab to control how the authentication provider is used in the login sequence. The Control Flag can have one of these values:

REQUIRED—The authentication provider is always called, and the user must always pass its authentication test.
SUFFICIENT—If the user passes the authentication test of the authentication provider, no other authentication providers are executed (except for authentication providers with the JAAS Control Flag set to REQUIRED) because the user was sufficiently authenticated.
REQUISITE—If the user passes the authentication test of this authentication provider, other providers are executed but can fail (except for authentication providers with the JAAS Control Flag set to REQUIRED).
OPTIONAL—The user is allowed to pass the authentication test of this authentication provider. However, if all authentication providers configured in a security realm have the JAAS Control Flag set to OPTIONAL, the user must pass the authentication test of one of the providers.

The WebLogic Server administration console sets the JAAS Control Flag to OPTIONAL when creating a security provider. MBeans for security providers defaults to REQUIRED.

These troubleshooting and debugging tips should help you fix your LDAP connection issues. If none of these hints direct you toward a solution, then contact BEA Customer Support for further diagnosis. You can open a case with a valid support contract by logging in at http://support.bea.com/login.jsp.

About the Author
Roula is a principal developer relations engineer with BEA systems, Customer Support Group. She specializes in troubleshooting and solving complex customer issues with their mission-critical applications on BEA products. Roula has a degree in electronic and computer engineering.