<META NAME="keywords" CONTENT="org.apache.catalina.realm.JNDIRealm,JNDIRealm class"> <BODY BGCOLOR="white" onload="asd();">

JNDIRealm (Catalina Internal API Documentation)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.catalina.realm
Class JNDIRealm


java.lang.Object

  |

  +--org.apache.catalina.realm.RealmBase

        |

        +--org.apache.catalina.realm.JNDIRealm

All Implemented Interfaces:: 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. This element has the following characteristics:
- The distinguished name (dn) attribute of this element contains the username that is being presented for authentication.
- The distinguished name can be represented by a pattern passed to an instance of MessageFormat, where the string "{0}" in the pattern is replaced by the username being presented.
- The element for this user contains an attribute named by the userPassword property. The value of this attribute is retrieved for use in authentication.
- 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 is 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, 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.
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.

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

Version:: $Revision: 1.5 $ $Date: 2001/09/07 20:45:12 $
Author:: John Holman, Craig R. McClanahan

Field Summary

protected java.lang.String connectionName
          The connection username for the server we will contact.

protected java.lang.String connectionPassword
          The connection password for the server we will contact.

protected java.lang.String connectionURL
          The connection URL for the server we will contact.

protected javax.naming.directory.DirContext context
          The directory context linking us to our directory server.

protected java.lang.String contextFactory
          The JNDI context factory used to acquire our InitialContext.

protected static java.lang.String info
          Descriptive information about this Realm implementation.

protected static java.lang.String name
          Descriptive information about this Realm implementation.

protected java.lang.String roleBase
          The base element for role searches.

protected java.text.MessageFormat roleFormat
          The MessageFormat object associated with the current roleSearch.

protected java.lang.String[] roleName
          The name of the attribute containing the role name.

protected java.lang.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 java.text.MessageFormat userFormat
          The MessageFormat object associated with the current userPattern.

protected java.lang.String[] userPassword
          The attribute name used to retrieve the user password.

protected java.lang.String userPattern
          The message format used to select a user, with "{0}" marking the spot where the specified username goes.

Fields inherited from class org.apache.catalina.realm.RealmBase

container, debug, digest, lifecycle, md, md5Encoder, md5Helper, sm, started, support, validate

Fields inherited from interface org.apache.catalina.Lifecycle

START_EVENT, STOP_EVENT

Constructor Summary

JNDIRealm()


Method Summary

java.security.Principal authenticate(javax.naming.directory.DirContext context, java.lang.String username, java.lang.String credentials)
          Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.

java.security.Principal authenticate(java.lang.String username, java.lang.String credentials)
          Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.

protected void close(javax.naming.directory.DirContext context)
          Close any open connection to the directory server for this Realm.

java.lang.String getConnectionName()
          Return the connection username for this Realm.

java.lang.String getConnectionPassword()
          Return the connection password for this Realm.

java.lang.String getConnectionURL()
          Return the connection URL for this Realm.

java.lang.String getContextFactory()
          Return the JNDI context factory for this Realm.

protected java.lang.String getName()
          Return a short name for this Realm implementation.

protected java.lang.String getPassword(java.lang.String username)
          Return the password associated with the given principal's user name.

protected java.security.Principal getPrincipal(java.lang.String username)
          Return the Principal associated with the given user name.

java.lang.String getRoleBase()
          Return the base element for role searches.

java.lang.String getRoleName()
          Return the role name attribute name for this Realm.

protected java.util.List getRoles(javax.naming.directory.DirContext context, java.lang.String username, java.lang.String dn)
          Return a List of roles associated with the user with the specified distinguished name.

java.lang.String getRoleSearch()
          Return the message format pattern for selecting roles in this Realm.

boolean getRoleSubtree()
          Return the "search subtree for roles" flag.

protected java.lang.String getUserDN(javax.naming.directory.DirContext context, java.lang.String username, java.lang.String credentials)
          Return the distinguished name of an authenticated user (if successful) or null if authentication is unsuccessful.

java.lang.String getUserPassword()
          Return the password attribute used to retrieve the user password.

java.lang.String getUserPattern()
          Return the message format pattern for selecting users in this Realm.

protected javax.naming.directory.DirContext open()
          Open (if necessary) and return a connection to the configured directory server for this Realm.

protected void release(javax.naming.directory.DirContext context)
          Release our use of this connection so that it can be recycled.

void setConnectionName(java.lang.String connectionName)
          Set the connection username for this Realm.

void setConnectionPassword(java.lang.String connectionPassword)
          Set the connection password for this Realm.

void setConnectionURL(java.lang.String connectionURL)
          Set the connection URL for this Realm.

void setContextFactory(java.lang.String contextFactory)
          Set the JNDI context factory for this Realm.

void setRoleBase(java.lang.String roleBase)
          Set the base element for role searches.

void setRoleName(java.lang.String roleName)
          Set the role name attribute name for this Realm.

void setRoleSearch(java.lang.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 setUserPassword(java.lang.String userPassword)
          Set the password attribute used to retrieve the user password.

void setUserPattern(java.lang.String userPattern)
          Set the message format pattern for selecting users in this Realm.

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.

Methods inherited from class org.apache.catalina.realm.RealmBase

addLifecycleListener, addPropertyChangeListener, authenticate, authenticate, authenticate, digest, Digest, getContainer, getDebug, getDigest, getDigest, getInfo, getValidate, hasMessageDigest, hasRole, log, log, main, removeLifecycleListener, removePropertyChangeListener, setContainer, setDebug, setDigest, setValidate

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

connectionName


protected java.lang.String connectionName

The connection username for the server we will contact.

connectionPassword


protected java.lang.String connectionPassword

The connection password for the server we will contact.

connectionURL


protected java.lang.String connectionURL

The connection URL for the server we will contact.

context


protected javax.naming.directory.DirContext context

The directory context linking us to our directory server.

contextFactory


protected java.lang.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.

info


protected static final java.lang.String info

Descriptive information about this Realm implementation.

See Also:: Constant Field Values

name


protected static final java.lang.String name

Descriptive information about this Realm implementation.

See Also:: Constant Field Values

roleBase


protected java.lang.String roleBase

The base element for role searches.

roleFormat


protected java.text.MessageFormat roleFormat

The MessageFormat object associated with the current roleSearch.

roleName


protected java.lang.String[] roleName

The name of the attribute containing the role name.

roleSearch


protected java.lang.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.

roleSubtree


protected boolean roleSubtree

Should we search the entire subtree for matching memberships?

userFormat


protected java.text.MessageFormat userFormat

The MessageFormat object associated with the current userPattern.

userPassword


protected java.lang.String[] userPassword

The attribute name used to retrieve the user password.

userPattern


protected java.lang.String userPattern

The message format used to select a user, with "{0}" marking the spot where the specified username goes.

Constructor Detail

JNDIRealm


public JNDIRealm()

Method Detail

getConnectionName


public java.lang.String getConnectionName()

Return the connection username for this Realm.

setConnectionName


public void setConnectionName(java.lang.String connectionName)

Set the connection username for this Realm.

Parameters:: connectionName - The new connection username

getConnectionPassword


public java.lang.String getConnectionPassword()

Return the connection password for this Realm.

setConnectionPassword


public void setConnectionPassword(java.lang.String connectionPassword)

Set the connection password for this Realm.

Parameters:: connectionPassword - The new connection password

getConnectionURL


public java.lang.String getConnectionURL()

Return the connection URL for this Realm.

setConnectionURL


public void setConnectionURL(java.lang.String connectionURL)

Set the connection URL for this Realm.

Parameters:: connectionURL - The new connection URL

getContextFactory


public java.lang.String getContextFactory()

Return the JNDI context factory for this Realm.

setContextFactory


public void setContextFactory(java.lang.String contextFactory)

Set the JNDI context factory for this Realm.

Parameters:: contextFactory - The new context factory

getRoleBase


public java.lang.String getRoleBase()

Return the base element for role searches.

setRoleBase


public void setRoleBase(java.lang.String roleBase)

Set the base element for role searches.

Parameters:: roleBase - The new base element

getRoleName


public java.lang.String getRoleName()

Return the role name attribute name for this Realm.

setRoleName


public void setRoleName(java.lang.String roleName)

Set the role name attribute name for this Realm.

Parameters:: roleName - The new role name attribute name

getRoleSearch


public java.lang.String getRoleSearch()

Return the message format pattern for selecting roles in this Realm.

setRoleSearch


public void setRoleSearch(java.lang.String roleSearch)

Set the message format pattern for selecting roles in this Realm.

Parameters:: roleSearch - The new role search pattern

getRoleSubtree


public boolean getRoleSubtree()

Return the "search subtree for roles" flag.

setRoleSubtree


public void setRoleSubtree(boolean roleSubtree)

Set the "search subtree for roles" flag.

Parameters:: roleSubtree - The new search flag

getUserPassword


public java.lang.String getUserPassword()

Return the password attribute used to retrieve the user password.

setUserPassword


public void setUserPassword(java.lang.String userPassword)

Set the password attribute used to retrieve the user password.

Parameters:: userPassword - The new password attribute

getUserPattern


public java.lang.String getUserPattern()

Return the message format pattern for selecting users in this Realm.

setUserPattern


public void setUserPattern(java.lang.String userPattern)

Set the message format pattern for selecting users in this Realm.

Parameters:: userPattern - The new user pattern

authenticate


public java.security.Principal authenticate(java.lang.String username,
                                            java.lang.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.

Specified by:: authenticate in interface Realm
Overrides:: authenticate in class RealmBase

Parameters:: username - Username of the Principal to look up; credentials - Password or other credentials to use in authenticating this username

authenticate


public java.security.Principal authenticate(javax.naming.directory.DirContext context,
                                            java.lang.String username,
                                            java.lang.String credentials)
                                     throws javax.naming.NamingException

Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.

Parameters:: username - Username of the Principal to look up; credentials - Password or other credentials to use in authenticating this username
Throws:: javax.naming.NamingException - if a directory server error occurs

close


protected void close(javax.naming.directory.DirContext context)

Close any open connection to the directory server for this Realm.

Parameters:: context - The directory context to be closed

getName


protected java.lang.String getName()

Return a short name for this Realm implementation.

Specified by:: getName in class RealmBase

getPassword


protected java.lang.String getPassword(java.lang.String username)

Return the password associated with the given principal's user name.

Specified by:: getPassword in class RealmBase

getPrincipal


protected java.security.Principal getPrincipal(java.lang.String username)

Return the Principal associated with the given user name.

Specified by:: getPrincipal in class RealmBase

getRoles


protected java.util.List getRoles(javax.naming.directory.DirContext context,
                                  java.lang.String username,
                                  java.lang.String dn)
                           throws javax.naming.NamingException

Return a List of roles associated with the user with the specified distinguished name. If no roles are associated with this user, a zero-length List is returned.

Parameters:: context - The directory context we are searching; username - The username of the user to be checked; dn - Distinguished name of the user to be checked
Throws:: javax.naming.NamingException - if a directory server error occurs

getUserDN


protected java.lang.String getUserDN(javax.naming.directory.DirContext context,
                                     java.lang.String username,
                                     java.lang.String credentials)
                              throws javax.naming.NamingException

Return the distinguished name of an authenticated user (if successful) or null if authentication is unsuccessful.

Parameters:: context - The directory context we are accessing; username - Username to be authenticated; credentials - Authentication credentials
Throws:: javax.naming.NamingException - if a directory server error occurs

open


protected javax.naming.directory.DirContext open()
                                          throws javax.naming.NamingException

Open (if necessary) and return a connection to the configured directory server for this Realm.

Throws:: javax.naming.NamingException - if a directory server error occurs

release


protected void release(javax.naming.directory.DirContext context)

Release our use of this connection so that it can be recycled.

Parameters:: context - The directory context to release

start


public void start()
           throws LifecycleException

Prepare for active use of the public methods of this Component.

Specified by:: start in interface Lifecycle
Overrides:: start in class RealmBase

Throws:: java.lang.IllegalStateException - if this component has already been started; LifecycleException - if this component detects a fatal error that prevents it from being started

stop


public void stop()
          throws LifecycleException

Gracefully shut down active use of the public methods of this Component.

Specified by:: stop in interface Lifecycle
Overrides:: stop in class RealmBase

Throws:: java.lang.IllegalStateException - if this component has not been started; LifecycleException - if this component detects a fatal error that needs to be reported

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.catalina.realm Class JNDIRealm

connectionName

connectionPassword

connectionURL

context

contextFactory

info

name

roleBase

roleFormat

roleName

roleSearch

roleSubtree

userFormat

userPassword

userPattern

JNDIRealm

getConnectionName

setConnectionName

getConnectionPassword

setConnectionPassword

getConnectionURL

setConnectionURL

getContextFactory

setContextFactory

getRoleBase

setRoleBase

getRoleName

setRoleName

getRoleSearch

setRoleSearch

getRoleSubtree

setRoleSubtree

getUserPassword

setUserPassword

getUserPattern

setUserPattern

authenticate

authenticate

close

getName

getPassword

getPrincipal

getRoles

getUserDN

open

release

start

stop

org.apache.catalina.realm
Class JNDIRealm