org.apache.catalina.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:
DirContext
that is accessed
via the connectionURL
property.connectURL
an attempt will be made to use the alternateURL
if it
exists.userPattern
property.userPattern
property is not
specified, a unique element can be located by searching the directory
context. In this case:
userSearch
pattern specifies the search filter
after substitution of the username.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.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.userPassword
property is not specified.userPassword
property is specified, in which case:
userPassword
property.
RealmBase.digest()
method (using the standard digest
support included in RealmBase
).
RealmBase.digest()
) are equal to the retrieved value
for the user password attribute.DirContext
that is accessed via the
connectionURL
property. This element has the following
characteristics:
roleSearch
property.roleSearch
pattern optionally includes pattern
replacements "{0}" for the distinguished name, and/or "{1}" for
the username, of the authenticated user for which roles will be
retrieved.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.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.roleName
property) containing the name of the
role represented by this element.userRoleName
property.commonRole
property to the
name of this role. The role doesn't have to exist in the directory.roleNested
to true
.
The default value is false
, so role searches will not find
nested roles.<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.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.
Version: $Revision: 898707 $ $Date: 2010-01-13 11:37:53 +0100 (Wed, 13 Jan 2010) $
Field Summary | |
---|---|
protected boolean | adCompat
Should we ignore PartialResultExceptions when iterating over NamingEnumerations?
|
protected String | alternateURL
An alternate URL, to which, we should connect if connectionURL fails. |
protected String | authentication
The type of authentication to use |
protected String | commonRole
Add this role to every authenticated user |
protected int | connectionAttempt
The number of connection attempts. |
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 | connectionTimeout
The timeout, in milliseconds, to use when trying to create a connection
to the directory. |
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. |
protected String | derefAliases
How aliases should be dereferenced during search operations. |
static String | DEREF_ALIASES
Constant that holds the name of the environment property for specifying
the manner in which aliases should be dereferenced. |
protected static String | info
Descriptive information about this Realm implementation. |
protected static 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 String | referrals
How should we handle referrals? |
protected String | roleBase
The base element for role searches. |
protected MessageFormat | roleFormat
The MessageFormat object associated with the current
roleSearch . |
protected String | roleName
The name of the attribute containing roles held elsewhere |
protected boolean | roleNested
Should we look for nested group in order to determine roles? |
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 String | userBase
The base element for user searches. |
protected String | userPassword
The attribute name used to retrieve the user password. |
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 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.
|
protected MessageFormat[] | userPatternFormatArray
An array of MessageFormat objects associated with the current
userPatternArray . |
protected String | userRoleName
The name of an attribute in the user's entry containing
roles for that user |
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? |
Method Summary | |
---|---|
Principal | authenticate(String username, String credentials)
Return the Principal associated with the specified username and
credentials, if there is one; otherwise return null .
|
Principal | authenticate(DirContext context, String username, String credentials)
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)
Check credentials by binding to the directory as the user
|
protected boolean | checkCredentials(DirContext context, User user, String credentials)
Check whether the given User can be authenticated with the
given credentials. |
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)
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.
|
boolean | getAdCompat()
Returns the current settings for handling PartialResultExceptions |
String | getAlternateURL()
Getter for property alternateURL.
|
String | getAuthentication()
Return the type of authentication to use. |
String | getCommonRole()
Return the common role |
String | getConnectionName()
Return the connection username for this Realm. |
String | getConnectionPassword()
Return the connection password for this Realm. |
String | getConnectionTimeout()
Return the connection timeout. |
String | getConnectionURL()
Return the connection URL for this Realm. |
String | getContextFactory()
Return the JNDI context factory for this Realm. |
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)
Returns the distinguished name of a search result.
|
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 Principal | getPrincipal(DirContext context, String username)
Return the Principal associated with the given user name. |
String | getProtocol()
Return the protocol to be used. |
String | getReferrals()
Returns the current settings for handling JNDI referrals. |
String | getRoleBase()
Return the base element for role searches. |
String | getRoleName()
Return the role name attribute name for this Realm. |
boolean | getRoleNested()
Return the "The nested group search flag" flag. |
protected List<String> | getRoles(DirContext context, User user)
Return a List of roles associated with the given User. |
String | getRoleSearch()
Return the message format pattern for selecting roles in this Realm. |
boolean | getRoleSubtree()
Return the "search subtree for roles" flag. |
protected User | getUser(DirContext context, String username)
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)
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)
Return a User object containing information about the user
with the specified username, if found in the directory;
otherwise return null .
|
String | getUserBase()
Return the base element for user searches. |
protected User | getUserByPattern(DirContext context, String username, String[] attrIds, String dn)
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)
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)
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 .
|
String | getUserPassword()
Return the password attribute used to retrieve the user password. |
String | getUserPattern()
Return the message format pattern for selecting users in this Realm. |
String | getUserRoleName()
Return the user role name attribute name for this Realm. |
String | getUserSearch()
Return the message format pattern for selecting users in this Realm. |
boolean | getUserSubtree()
Return the "search subtree for users" flag. |
protected DirContext | open()
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. |
protected void | release(DirContext context)
Release our use of this connection so that it can be recycled.
|
void | setAdCompat(boolean adCompat)
How do we handle PartialResultExceptions?
|
void | setAlternateURL(String alternateURL)
Setter for property alternateURL.
|
void | setAuthentication(String authentication)
Set the type of authentication to use.
|
void | setCommonRole(String commonRole)
Set the common role
|
void | setConnectionName(String connectionName)
Set the connection username for this Realm.
|
void | setConnectionPassword(String connectionPassword)
Set the connection password for this Realm.
|
void | setConnectionTimeout(String timeout)
Set the connection timeout.
|
void | setConnectionURL(String connectionURL)
Set the connection URL for this Realm.
|
void | setContextFactory(String contextFactory)
Set the JNDI context factory for this Realm.
|
void | setDerefAliases(String derefAliases)
Set the value for derefAliases to be used when searching the directory.
|
void | setProtocol(String protocol)
Set the protocol for this Realm.
|
void | setReferrals(String referrals)
How do we handle JNDI referrals? |
void | setRoleBase(String roleBase)
Set the base element for role searches.
|
void | setRoleName(String roleName)
Set the role name attribute name for this Realm.
|
void | setRoleNested(boolean roleNested)
Set the "search subtree for roles" flag.
|
void | setRoleSearch(String roleSearch)
Set the message format pattern for selecting roles in this Realm.
|
void | setRoleSubtree(boolean roleSubtree)
Set the "search subtree for roles" flag.
|
void | setUserBase(String userBase)
Set the base element for user searches.
|
void | setUserPassword(String userPassword)
Set the password attribute used to retrieve the user password.
|
void | setUserPattern(String userPattern)
Set the message format pattern for selecting users in this Realm.
|
void | setUserRoleName(String userRoleName)
Set the user role name attribute name for this Realm.
|
void | setUserSearch(String userSearch)
Set the message format pattern for selecting users in this Realm.
|
void | setUserSubtree(boolean userSubtree)
Set the "search subtree for users" flag.
|
void | start()
Prepare for active use of the public methods of this Component.
|
void | stop()
Gracefully shut down active use of the public methods of this Component.
|
roleSearch
.userPatternArray
.userSearch
.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.
Parameters: username Username of the Principal to look up credentials Password or other credentials to use in authenticating this username
null
.
Parameters: context The directory context username Username of the Principal to look up credentials Password or other credentials to use in authenticating this username
Throws: NamingException if a directory server error occurs
Parameters: context The directory context user The User to be authenticated credentials Authentication credentials
Throws: NamingException if a directory server error occurs
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.
Parameters: context The directory context user The User to be authenticated credentials The credentials presented by the user
Throws: NamingException if a directory server error occurs
Parameters: context The directory context to be closed
Parameters: context The directory context info The User to be authenticated credentials Authentication credentials
Throws: NamingException if a directory server error occurs
Parameters: inString string to escape according to RFC 2254 guidelines
Returns: String the escaped/encoded result
Returns: Value of property alternateURL.
Returns: java.util.Hashtable the configuration for the directory context.
Parameters: context Our DirContext base The base DN result The search result
Returns: String containing the distinguished name
Parameters: context The directory context we are searching user The User to be checked
Throws: NamingException if a directory server error occurs
null
.
Parameters: context The directory context username Username to be looked up
Throws: NamingException if a directory server error occurs
See Also: JNDIRealm
null
.
Parameters: context The directory context username Username to be looked up credentials User credentials (optional)
Throws: NamingException if a directory server error occurs
See Also: JNDIRealm
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.
Parameters: context The directory context username Username to be looked up credentials User credentials (optional) curUserPattern Index into userPatternFormatArray
Throws: NamingException if a directory server error occurs
null
.
Parameters: context The directory context username The username attrIds String[]containing names of attributes to dn Distinguished name of the user retrieve.
Throws: NamingException if a directory server error occurs
UserPattern
configuration attribute to
locate the directory entry for the user with the specified
username and return a User object; otherwise return
null
.
Parameters: context The directory context username The username credentials User credentials (optional) attrIds String[]containing names of attributes to curUserPattern Index into userPatternFormatArray
Throws: NamingException if a directory server error occurs
See Also: (DirContext, String, String[], String)
null
.
Parameters: context The directory context username The username attrIds String[]containing names of attributes to retrieve.
Throws: NamingException if a directory server error occurs
Throws: NamingException if a directory server error occurs
Parameters: userPatternString - a string LDAP search paths surrounded by parentheses
Parameters: context The directory context to release
Parameters: alternateURL New value of property alternateURL.
Parameters: authentication The authentication
Parameters: commonRole The common role
Parameters: connectionName The new connection username
Parameters: connectionPassword The new connection password
Parameters: timeout The new connection timeout
Parameters: connectionURL The new connection URL
Parameters: contextFactory The new context factory
Parameters: derefAliases New value of property derefAliases.
Parameters: protocol The new protocol.
Parameters: roleBase The new base element
Parameters: roleName The new role name attribute name
Parameters: roleNested The nested group search flag
Parameters: roleSearch The new role search pattern
Parameters: roleSubtree The new search flag
Parameters: userBase The new base element
Parameters: userPassword The new password attribute
Parameters: userPattern The new user pattern
Parameters: userRoleName The new userRole name attribute name
Parameters: userSearch The new user search pattern
Parameters: userSubtree The new search flag
Throws: LifecycleException if this component detects a fatal error that prevents it from being started
Throws: LifecycleException if this component detects a fatal error that needs to be reported