Package org.apache.catalina.realm

Class JNDIRealm

java.lang.Object
org.apache.catalina.util.LifecycleBase
org.apache.catalina.util.LifecycleMBeanBase
org.apache.catalina.realm.RealmBase
org.apache.catalina.realm.JNDIRealm
All Implemented Interfaces:
MBeanRegistration, Contained, JmxEnabled, Lifecycle, Realm
public class JNDIRealm extends RealmBase

Implementation of Realm that works with a directory server accessed via the Java Naming and Directory Interface (JNDI) APIs. The following constraints are imposed on the data structure in the underlying directory server:

  • Each user that can be authenticated is represented by an individual element in the top level DirContext that is accessed via the connectionURL property.
  • If a socket connection cannot be made to the connectURL an attempt will be made to use the alternateURL if it exists.
  • Each user element has a distinguished name that can be formed by substituting the presented username into a pattern configured by the userPattern property.
  • Alternatively, if the userPattern property is not specified, a unique element can be located by searching the directory context. In this case:
    • The userSearch pattern specifies the search filter after substitution of the username.
    • The userBase property can be set to the element that is the base of the subtree containing users. If not specified, the search base is the top-level context.
    • The userSubtree property can be set to true if you wish to search the entire subtree of the directory context. The default value of false requests a search of only the current level.
  • The user may be authenticated by binding to the directory with the username and password presented. This method is used when the userPassword property is not specified.
  • The user may be authenticated by retrieving the value of an attribute from the directory and comparing it explicitly with the value presented by the user. This method is used when the userPassword property is specified, in which case:
    • The element for this user must contain an attribute named by the userPassword property.
    • The value of the user password attribute is either a cleartext String, or the result of passing a cleartext String through the RealmBase.digest() method (using the standard digest support included in RealmBase).
    • The user is considered to be authenticated if the presented credentials (after being passed through RealmBase.digest()) are equal to the retrieved value for the user password attribute.
  • Each group of users that has been assigned a particular role may be represented by an individual element in the top level DirContext that is accessed via the connectionURL property. This element has the following characteristics:
    • The set of all possible groups of interest can be selected by a search pattern configured by the roleSearch property.
    • The roleSearch pattern optionally includes pattern replacements "{0}" for the distinguished name, and/or "{1}" for the username, and/or "{2}" the value of an attribute from the user's directory entry (the attribute is specified by the userRoleAttribute property), of the authenticated user for which roles will be retrieved.
    • The roleBase property can be set to the element that is the base of the search for matching roles. If not specified, the entire context will be searched.
    • The roleSubtree property can be set to true if you wish to search the entire subtree of the directory context. The default value of false requests a search of only the current level.
    • The element includes an attribute (whose name is configured by the roleName property) containing the name of the role represented by this element.
  • In addition, roles may be represented by the values of an attribute in the user's element whose name is configured by the userRoleName property.
  • A default role can be assigned to each user that was successfully authenticated by setting the commonRole property to the name of this role. The role doesn't have to exist in the directory.
  • If the directory server contains nested roles, you can search for them by setting roleNested to true. The default value is false, so role searches will not find nested roles.
  • Note that the standard <security-role-ref> element in the web application deployment descriptor allows applications to refer to roles programmatically by names other than those used in the directory server itself.

WARNING - There is a reported bug against the Netscape provider code (com.netscape.jndi.ldap.LdapContextFactory) with respect to successfully authenticated a non-existing user. The report is here: https://bz.apache.org/bugzilla/show_bug.cgi?id=11210 . With luck, Netscape has updated their provider code and this is not an issue.

Author:
John Holman, Craig R. McClanahan