Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
java.lang.Object
org.apache.catalina.realm.RealmBase
org.apache.catalina.realm.JNDIRealm
public class JNDIRealm
extends RealmBase
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.<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.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://nagoya.apache.org/bugzilla/show_bug.cgi?id=11210 .
With luck, Netscape has updated their provider code and this is not an
issue.
Field Summary | |
static String |
|
protected String |
|
protected String |
|
protected int |
|
protected String |
|
protected String |
|
protected String |
|
protected DirContext |
|
protected String |
|
protected int |
|
protected String |
|
protected static String |
|
protected static String |
|
protected String |
|
protected String |
|
protected String |
|
protected MessageFormat |
|
protected String |
|
protected String |
|
protected boolean |
|
protected String |
|
protected String |
|
protected String |
|
protected String[] |
|
protected MessageFormat[] |
|
protected String |
|
protected String |
|
protected MessageFormat |
|
protected boolean |
|
Fields inherited from class org.apache.catalina.realm.RealmBase | |
container , controller , debug , digest , digestEncoding , domain , host , info , initialized , lifecycle , md , md5Encoder , md5Helper , mserver , oname , path , sm , started , support , type , validate |
Fields inherited from interface org.apache.catalina.Lifecycle | |
AFTER_START_EVENT , AFTER_STOP_EVENT , BEFORE_START_EVENT , BEFORE_STOP_EVENT , START_EVENT , STOP_EVENT |
Method Summary | |
Principal |
|
Principal |
|
protected boolean |
|
protected boolean |
|
protected void |
|
protected boolean |
|
protected String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
java.lang.String |
|
protected Hashtable |
|
protected String |
|
protected String |
|
protected Principal |
|
String |
|
String |
|
String |
|
String |
|
String |
|
boolean |
|
protected List |
|
protected org.apache.catalina.realm.User |
|
String |
|
protected org.apache.catalina.realm.User |
|
protected org.apache.catalina.realm.User |
|
String |
|
String |
|
String |
|
String |
|
boolean |
|
protected DirContext |
|
protected String[] |
|
protected void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
Methods inherited from class org.apache.catalina.realm.RealmBase | |
Digest , addLifecycleListener , addPropertyChangeListener , authenticate , authenticate , authenticate , authenticate , destroy , digest , findLifecycleListeners , findSecurityConstraints , getContainer , getController , getDebug , getDigest , getDigest , getDigestEncoding , getDomain , getInfo , getName , getObjectName , getPassword , getPrincipal , getType , getValidate , hasMessageDigest , hasResourcePermission , hasRole , hasUserDataPermission , init , log , log , main , postDeregister , postRegister , preDeregister , preRegister , removeLifecycleListener , removePropertyChangeListener , setContainer , setController , setDebug , setDigest , setDigestEncoding , setValidate , start , stop |
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 String alternateURL
An alternate URL, to which, we should connect if connectionURL fails.
protected String authentication
The type of authentication to use
protected int connectionAttempt
The number of connection attempts. If greater than zero we use the alternate url.
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 int curUserPattern
The current user pattern to be used for lookup and binding of a user.
protected String derefAliases
How aliases should be dereferenced during search operations.
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 String referrals
How should we handle referrals? Microsoft Active Directory can't handle the default case, so an application authenticating against AD must set referrals to "follow".
protected String roleBase
The base element for role searches.
protected MessageFormat roleFormat
The MessageFormat object associated with the currentroleSearch
.
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 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. This is similar to userPattern, but allows for multiple searches for a user.
protected MessageFormat[] userPatternFormatArray
An array of MessageFormat objects associated with the currentuserPatternArray
.
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 currentuserSearch
.
protected boolean userSubtree
Should we search the entire subtree for matching users?
public 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 returnnull
.
- Parameters:
context
- The directory contextusername
- Username of the Principal to look upcredentials
- Password or other credentials to use in authenticating this username
public Principal authenticate(String username, String credentials)
Return the Principal associated with the specified username and credentials, if there is one; otherwise returnnull
. 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.
- Specified by:
- authenticate in interface Realm
- Overrides:
- authenticate in interface RealmBase
- Parameters:
username
- Username of the Principal to look upcredentials
- Password or other credentials to use in authenticating this username
protected boolean bindAsUser(DirContext context, org.apache.catalina.realm.User user, String credentials) throws NamingException
Check credentials by binding to the directory as the user
- Parameters:
context
- The directory contextuser
- The User to be authenticatedcredentials
- Authentication credentials
protected boolean checkCredentials(DirContext context, org.apache.catalina.realm.User user, String credentials) throws NamingException
Check whether the given User can be authenticated with the given credentials. If theuserPassword
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 contextuser
- The User to be authenticatedcredentials
- The credentials presented by the user
protected void close(DirContext context)
Close any open connection to the directory server for this Realm.
- Parameters:
context
- The directory context to be closed
protected boolean compareCredentials(DirContext context, org.apache.catalina.realm.User info, String credentials) throws NamingException
Check whether the credentials presented by the user match those retrieved from the directory.
- Parameters:
context
- The directory contextinfo
- The User to be authenticatedcredentials
- Authentication credentials
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
- Parameters:
inString
- string to escape according to RFC 2254 guidelines
- Returns:
- String the escaped/encoded result
public String getAlternateURL()
Getter for property alternateURL.
- Returns:
- Value of property alternateURL.
public String getAuthentication()
Return the type of authentication to use.
public String getConnectionName()
Return the connection username for this Realm.
public String getConnectionPassword()
Return the connection password for this Realm.
public String getConnectionURL()
Return the connection URL for this Realm.
public String getContextFactory()
Return the JNDI context factory for this Realm.
public java.lang.String getDerefAliases()
Return the derefAliases setting to be used.
protected Hashtable getDirectoryContextEnvironment()
Create our directory context configuration.
- Returns:
- java.util.Hashtable the configuration for the directory context.
protected String getName()
Return a short name for this Realm implementation.
- Overrides:
- getName in interface RealmBase
protected String getPassword(String username)
Return the password associated with the given principal's user name.
- Overrides:
- getPassword in interface RealmBase
protected Principal getPrincipal(String username)
Return the Principal associated with the given user name.
- Overrides:
- getPrincipal in interface RealmBase
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 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 getRoles(DirContext context, org.apache.catalina.realm.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.
- Parameters:
context
- The directory context we are searchinguser
- The User to be checked
protected org.apache.catalina.realm.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 returnnull
. If theuserPassword
configuration attribute is specified, the value of that attribute is retrieved from the user's directory entry. If theuserRoleName
configuration attribute is specified, all values of that attribute are retrieved from the directory entry.
- Parameters:
context
- The directory contextusername
- Username to be looked up
public String getUserBase()
Return the base element for user searches.
protected org.apache.catalina.realm.User getUserByPattern(DirContext context, String username, String[] attrIds) throws NamingException
Use theUserPattern
configuration attribute to locate the directory entry for the user with the specified username and return a User object; otherwise returnnull
.
- Parameters:
context
- The directory contextusername
- The usernameattrIds
- String[]containing names of attributes to retrieve.
protected org.apache.catalina.realm.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 returnnull
.
- Parameters:
context
- The directory contextusername
- The usernameattrIds
- String[]containing names of attributes to retrieve.
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).
- Parameters:
userPatternString
- - a string LDAP search paths surrounded by parentheses
protected void release(DirContext context)
Release our use of this connection so that it can be recycled.
- Parameters:
context
- The directory context to release
public void setAlternateURL(String alternateURL)
Setter for property alternateURL.
- Parameters:
alternateURL
- New value of property alternateURL.
public void setAuthentication(String authentication)
Set the type of authentication to use.
- Parameters:
authentication
- The authentication
public void setConnectionName(String connectionName)
Set the connection username for this Realm.
- Parameters:
connectionName
- The new connection username
public void setConnectionPassword(String connectionPassword)
Set the connection password for this Realm.
- Parameters:
connectionPassword
- The new connection password
public void setConnectionURL(String connectionURL)
Set the connection URL for this Realm.
- Parameters:
connectionURL
- The new connection URL
public void setContextFactory(String contextFactory)
Set the JNDI context factory for this Realm.
- Parameters:
contextFactory
- The new context factory
public void setDerefAliases(java.lang.String derefAliases)
Set the value for derefAliases to be used when searching the directory.
- Parameters:
derefAliases
- New value of property derefAliases.
public void setProtocol(String protocol)
Set the protocol for this Realm.
- Parameters:
protocol
- The new protocol.
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.
- Parameters:
roleBase
- The new base element
public void setRoleName(String roleName)
Set the role name attribute name for this Realm.
- Parameters:
roleName
- The new role name attribute name
public void setRoleSearch(String roleSearch)
Set the message format pattern for selecting roles in this Realm.
- Parameters:
roleSearch
- The new role search pattern
public void setRoleSubtree(boolean roleSubtree)
Set the "search subtree for roles" flag.
- Parameters:
roleSubtree
- The new search flag
public void setUserBase(String userBase)
Set the base element for user searches.
- Parameters:
userBase
- The new base element
public void setUserPassword(String userPassword)
Set the password attribute used to retrieve the user password.
- Parameters:
userPassword
- The new password attribute
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.
- Parameters:
userPattern
- The new user pattern
public void setUserRoleName(String userRoleName)
Set the user role name attribute name for this Realm.
- Parameters:
userRoleName
- The new userRole name attribute name
public void setUserSearch(String userSearch)
Set the message format pattern for selecting users in this Realm.
- Parameters:
userSearch
- The new user search pattern
public void setUserSubtree(boolean userSubtree)
Set the "search subtree for users" flag.
- Parameters:
userSubtree
- The new search flag
public void start() throws LifecycleException
Prepare for active use of the public methods of this Component.
- Overrides:
- start in interface RealmBase
- Throws:
LifecycleException
- if this component detects a fatal error that prevents it from being started
public void stop() throws LifecycleException
Gracefully shut down active use of the public methods of this Component.
- Overrides:
- stop in interface RealmBase
- Throws:
LifecycleException
- if this component detects a fatal error that needs to be reported