Save This Page
Home » apache-tomcat-6.0.26-src » org.apache » catalina » realm » [javadoc | source]
org.apache.catalina.realm
public class: JNDIRealm [javadoc | source]
java.lang.Object
   org.apache.catalina.realm.RealmBase
      org.apache.catalina.realm.JNDIRealm

All Implemented Interfaces:
    Realm, MBeanRegistration, Lifecycle

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:

TODO - Support connection pooling (including message format objects) so that authenticate() does not have to be synchronized.

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: http://issues.apache.org/bugzilla/show_bug.cgi?id=11210 . With luck, Netscape has updated their provider code and this is not an issue.

Field Summary
protected  String authentication    The type of authentication to use 
protected  String connectionName    The connection username for the server we will contact. 
protected  String connectionPassword    The connection password for the server we will contact. 
protected  String connectionURL    The connection URL for the server we will contact. 
protected  DirContext context    The directory context linking us to our directory server. 
protected  String contextFactory    The JNDI context factory used to acquire our InitialContext. By default, assumes use of an LDAP server using the standard JNDI LDAP provider. 
protected  String derefAliases    How aliases should be dereferenced during search operations. 
public static final  String DEREF_ALIASES    Constant that holds the name of the environment property for specifying the manner in which aliases should be dereferenced. 
protected static final  String info    Descriptive information about this Realm implementation. 
protected static final  String name    Descriptive information about this Realm implementation. 
protected  String protocol    The protocol that will be used in the communication with the directory server. 
protected  boolean adCompat    Should we ignore PartialResultExceptions when iterating over NamingEnumerations? Microsoft Active Directory often returns referrals, which lead to PartialResultExceptions. Unfortunately there's no stable way to detect, if the Exceptions really come from an AD referral. Set to true to ignore PartialResultExceptions. 
protected  String referrals    How should we handle referrals? Microsoft Active Directory often returns referrals. If you need to follow them set referrals to "follow". Caution: if your DNS is not part of AD, the LDAP client lib might try to resolve your domain name in DNS to find another LDAP server. 
protected  String userBase    The base element for user searches. 
protected  String userSearch    The message format used to search for a user, with "{0}" marking the spot where the username goes. 
protected  MessageFormat userSearchFormat    The MessageFormat object associated with the current userSearch
protected  boolean userSubtree    Should we search the entire subtree for matching users? 
protected  String userPassword    The attribute name used to retrieve the user password. 
protected  String[] userPatternArray    A string of LDAP user patterns or paths, ":"-separated These will be used to form the distinguished name of a user, with "{0}" marking the spot where the specified username goes. This is similar to userPattern, but allows for multiple searches for a user. 
protected  String userPattern    The message format used to form the distinguished name of a user, with "{0}" marking the spot where the specified username goes. 
protected  MessageFormat[] userPatternFormatArray    An array of MessageFormat objects associated with the current userPatternArray
protected  String roleBase    The base element for role searches. 
protected  MessageFormat roleFormat    The MessageFormat object associated with the current roleSearch
protected  String userRoleName    The name of an attribute in the user's entry containing roles for that user 
protected  String roleName    The name of the attribute containing roles held elsewhere 
protected  String roleSearch    The message format used to select roles for a user, with "{0}" marking the spot where the distinguished name of the user goes. 
protected  boolean roleSubtree    Should we search the entire subtree for matching memberships? 
protected  boolean roleNested    Should we look for nested group in order to determine roles? 
protected  String alternateURL    An alternate URL, to which, we should connect if connectionURL fails. 
protected  int connectionAttempt    The number of connection attempts. If greater than zero we use the alternate url. 
protected  String commonRole    Add this role to every authenticated user 
protected  String connectionTimeout    The timeout, in milliseconds, to use when trying to create a connection to the directory. The default is 5000 (5 seconds). 
Fields inherited from org.apache.catalina.realm.RealmBase:
container,  containerLog,  digest,  digestEncoding,  info,  lifecycle,  md,  md5Encoder,  md5Helper,  sm,  started,  support,  validate,  allRolesMode,  type,  domain,  host,  path,  realmPath,  oname,  controller,  mserver,  initialized
Method from org.apache.catalina.realm.JNDIRealm Summary:
authenticate,   authenticate,   bindAsUser,   checkCredentials,   close,   compareCredentials,   doRFC2254Encoding,   getAdCompat,   getAlternateURL,   getAuthentication,   getCommonRole,   getConnectionName,   getConnectionPassword,   getConnectionTimeout,   getConnectionURL,   getContextFactory,   getDerefAliases,   getDirectoryContextEnvironment,   getDistinguishedName,   getInfo,   getName,   getPassword,   getPrincipal,   getPrincipal,   getProtocol,   getReferrals,   getRoleBase,   getRoleName,   getRoleNested,   getRoleSearch,   getRoleSubtree,   getRoles,   getUser,   getUser,   getUser,   getUserBase,   getUserByPattern,   getUserByPattern,   getUserBySearch,   getUserPassword,   getUserPattern,   getUserRoleName,   getUserSearch,   getUserSubtree,   open,   parseUserPatternString,   release,   setAdCompat,   setAlternateURL,   setAuthentication,   setCommonRole,   setConnectionName,   setConnectionPassword,   setConnectionTimeout,   setConnectionURL,   setContextFactory,   setDerefAliases,   setProtocol,   setReferrals,   setRoleBase,   setRoleName,   setRoleNested,   setRoleSearch,   setRoleSubtree,   setUserBase,   setUserPassword,   setUserPattern,   setUserRoleName,   setUserSearch,   setUserSubtree,   start,   stop
Methods from org.apache.catalina.realm.RealmBase:
Digest,   addLifecycleListener,   addPropertyChangeListener,   authenticate,   authenticate,   authenticate,   authenticate,   backgroundProcess,   destroy,   digest,   findLifecycleListeners,   findSecurityConstraints,   getAllRolesMode,   getContainer,   getController,   getDigest,   getDigest,   getDigestEncoding,   getDomain,   getInfo,   getName,   getObjectName,   getPassword,   getPrincipal,   getPrincipal,   getRealmPath,   getRealmSuffix,   getType,   getValidate,   hasMessageDigest,   hasResourcePermission,   hasRole,   hasUserDataPermission,   init,   main,   postDeregister,   postRegister,   preDeregister,   preRegister,   removeLifecycleListener,   removePropertyChangeListener,   setAllRolesMode,   setContainer,   setController,   setDigest,   setDigestEncoding,   setRealmPath,   setValidate,   start,   stop
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from org.apache.catalina.realm.JNDIRealm Detail:
 public Principal authenticate(String username,
    String credentials) 
    Return the Principal associated with the specified username and credentials, if there is one; otherwise return null. If there are any errors with the JDBC connection, executing the query or anything we return null (don't authenticate). This event is also logged, and the connection will be closed so that a subsequent request will automatically re-open it.
 public synchronized Principal authenticate(DirContext context,
    String username,
    String credentials) throws NamingException 
    Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
 protected boolean bindAsUser(DirContext context,
    User user,
    String credentials) throws NamingException 
    Check credentials by binding to the directory as the user
 protected boolean checkCredentials(DirContext context,
    User user,
    String credentials) throws NamingException 
    Check whether the given User can be authenticated with the given credentials. If the userPassword configuration attribute is specified, the credentials previously retrieved from the directory are compared explicitly with those presented by the user. Otherwise the presented credentials are checked by binding to the directory as the user.
 protected  void close(DirContext context) 
    Close any open connection to the directory server for this Realm.
 protected boolean compareCredentials(DirContext context,
    User info,
    String credentials) throws NamingException 
    Check whether the credentials presented by the user match those retrieved from the directory.
 protected String doRFC2254Encoding(String inString) 
    Given an LDAP search string, returns the string with certain characters escaped according to RFC 2254 guidelines. The character mapping is as follows: char -> Replacement --------------------------- * -> \2a ( -> \28 ) -> \29 \ -> \5c \0 -> \00
 public boolean getAdCompat() 
    Returns the current settings for handling PartialResultExceptions
 public String getAlternateURL() 
    Getter for property alternateURL.
 public String getAuthentication() 
    Return the type of authentication to use.
 public String getCommonRole() 
    Return the common role
 public String getConnectionName() 
    Return the connection username for this Realm.
 public String getConnectionPassword() 
    Return the connection password for this Realm.
 public String getConnectionTimeout() 
    Return the connection timeout.
 public String getConnectionURL() 
    Return the connection URL for this Realm.
 public String getContextFactory() 
    Return the JNDI context factory for this Realm.
 public String getDerefAliases() 
    Return the derefAliases setting to be used.
 protected Hashtable<String, String> getDirectoryContextEnvironment() 
    Create our directory context configuration.
 protected String getDistinguishedName(DirContext context,
    String base,
    SearchResult result) throws NamingException 
    Returns the distinguished name of a search result.
 public String getInfo() 
    Return descriptive information about this Realm implementation and the corresponding version number, in the format <description>/<version>.
 protected String getName() 
    Return a short name for this Realm implementation.
 protected String getPassword(String username) 
    Return the password associated with the given principal's user name.
 protected Principal getPrincipal(String username) 
    Return the Principal associated with the given user name.
 protected synchronized Principal getPrincipal(DirContext context,
    String username) throws NamingException 
    Return the Principal associated with the given user name.
 public String getProtocol() 
    Return the protocol to be used.
 public String getReferrals() 
    Returns the current settings for handling JNDI referrals.
 public String getRoleBase() 
    Return the base element for role searches.
 public String getRoleName() 
    Return the role name attribute name for this Realm.
 public boolean getRoleNested() 
    Return the "The nested group search flag" flag.
 public String getRoleSearch() 
    Return the message format pattern for selecting roles in this Realm.
 public boolean getRoleSubtree() 
    Return the "search subtree for roles" flag.
 protected List<String> getRoles(DirContext context,
    User user) throws NamingException 
    Return a List of roles associated with the given User. Any roles present in the user's directory entry are supplemented by a directory search. If no roles are associated with this user, a zero-length List is returned.
 protected User getUser(DirContext context,
    String username) throws NamingException 
    Return a User object containing information about the user with the specified username, if found in the directory; otherwise return null.
 protected User getUser(DirContext context,
    String username,
    String credentials) throws NamingException 
    Return a User object containing information about the user with the specified username, if found in the directory; otherwise return null.
 protected User getUser(DirContext context,
    String username,
    String credentials,
    int curUserPattern) throws NamingException 
    Return a User object containing information about the user with the specified username, if found in the directory; otherwise return null. If the userPassword configuration attribute is specified, the value of that attribute is retrieved from the user's directory entry. If the userRoleName configuration attribute is specified, all values of that attribute are retrieved from the directory entry.
 public String getUserBase() 
    Return the base element for user searches.
 protected User getUserByPattern(DirContext context,
    String username,
    String[] attrIds,
    String dn) throws NamingException 
    Use the distinguished name to locate the directory entry for the user with the specified username and return a User object; otherwise return null.
 protected User getUserByPattern(DirContext context,
    String username,
    String credentials,
    String[] attrIds,
    int curUserPattern) throws NamingException 
    Use the UserPattern configuration attribute to locate the directory entry for the user with the specified username and return a User object; otherwise return null.
 protected User getUserBySearch(DirContext context,
    String username,
    String[] attrIds) throws NamingException 
    Search the directory to return a User object containing information about the user with the specified username, if found in the directory; otherwise return null.
 public String getUserPassword() 
    Return the password attribute used to retrieve the user password.
 public String getUserPattern() 
    Return the message format pattern for selecting users in this Realm.
 public String getUserRoleName() 
    Return the user role name attribute name for this Realm.
 public String getUserSearch() 
    Return the message format pattern for selecting users in this Realm.
 public boolean getUserSubtree() 
    Return the "search subtree for users" flag.
 protected DirContext open() throws NamingException 
    Open (if necessary) and return a connection to the configured directory server for this Realm.
 protected String[] parseUserPatternString(String userPatternString) 
    Given a string containing LDAP patterns for user locations (separated by parentheses in a pseudo-LDAP search string format - "(location1)(location2)", returns an array of those paths. Real LDAP search strings are supported as well (though only the "|" "OR" type).
 protected  void release(DirContext context) 
    Release our use of this connection so that it can be recycled.
 public  void setAdCompat(boolean adCompat) 
    How do we handle PartialResultExceptions? True: ignore all PartialResultExceptions.
 public  void setAlternateURL(String alternateURL) 
    Setter for property alternateURL.
 public  void setAuthentication(String authentication) 
    Set the type of authentication to use.
 public  void setCommonRole(String commonRole) 
    Set the common role
 public  void setConnectionName(String connectionName) 
    Set the connection username for this Realm.
 public  void setConnectionPassword(String connectionPassword) 
    Set the connection password for this Realm.
 public  void setConnectionTimeout(String timeout) 
    Set the connection timeout.
 public  void setConnectionURL(String connectionURL) 
    Set the connection URL for this Realm.
 public  void setContextFactory(String contextFactory) 
    Set the JNDI context factory for this Realm.
 public  void setDerefAliases(String derefAliases) 
    Set the value for derefAliases to be used when searching the directory.
 public  void setProtocol(String protocol) 
    Set the protocol for this Realm.
 public  void setReferrals(String referrals) 
    How do we handle JNDI referrals? ignore, follow, or throw (see javax.naming.Context.REFERRAL for more information).
 public  void setRoleBase(String roleBase) 
    Set the base element for role searches.
 public  void setRoleName(String roleName) 
    Set the role name attribute name for this Realm.
 public  void setRoleNested(boolean roleNested) 
    Set the "search subtree for roles" flag.
 public  void setRoleSearch(String roleSearch) 
    Set the message format pattern for selecting roles in this Realm.
 public  void setRoleSubtree(boolean roleSubtree) 
    Set the "search subtree for roles" flag.
 public  void setUserBase(String userBase) 
    Set the base element for user searches.
 public  void setUserPassword(String userPassword) 
    Set the password attribute used to retrieve the user password.
 public  void setUserPattern(String userPattern) 
    Set the message format pattern for selecting users in this Realm. This may be one simple pattern, or multiple patterns to be tried, separated by parentheses. (for example, either "cn={0}", or "(cn={0})(cn={0},o=myorg)" Full LDAP search strings are also supported, but only the "OR", "|" syntax, so "(|(cn={0})(cn={0},o=myorg))" is also valid. Complex search strings with &, etc are NOT supported.
 public  void setUserRoleName(String userRoleName) 
    Set the user role name attribute name for this Realm.
 public  void setUserSearch(String userSearch) 
    Set the message format pattern for selecting users in this Realm.
 public  void setUserSubtree(boolean userSubtree) 
    Set the "search subtree for users" flag.
 public  void start() throws LifecycleException 
    Prepare for active use of the public methods of this Component.
 public  void stop() throws LifecycleException 
    Gracefully shut down active use of the public methods of this Component.