org.apache.catalina.realm

Class JAASRealm

Implemented Interfaces:
Lifecycle, MBeanRegistration, Realm

public class JAASRealm
extends RealmBase

Implmentation of Realm that authenticates users via the Java Authentication and Authorization Service (JAAS). JAAS support requires either JDK 1.4 (which includes it as part of the standard platform) or JDK 1.3 (with the plug-in jaas.jar file).

The value configured for the appName property is passed to the javax.security.auth.login.LoginContext constructor, to specify the application name used to select the set of relevant LoginModules required.

The JAAS Specification describes the result of a successful login as a javax.security.auth.Subject instance, which can contain zero or more java.security.Principal objects in the return value of the Subject.getPrincipals() method. However, it provides no guidance on how to distinguish Principals that describe the individual user (and are thus appropriate to return as the value of request.getUserPrincipal() in a web application) from the Principal(s) that describe the authorized roles for this user. To maintain as much independence as possible from the underlying LoginMethod implementation executed by JAAS, the following policy is implemented by this Realm:

Version:
$Revision: 1.6.2.4 $ $Date: 2004/10/01 12:28:47 $

Authors:
Craig R. McClanahan
Yoav Shapira
Andrew R. Jaquith

Field Summary

protected String
appName
The application name passed to the JAAS LoginContext, which uses it to select the set of relevant LoginModules.
protected static String
info
Descriptive information about this Realm implementation.
protected static String
name
Descriptive information about this Realm implementation.
protected String
roleClassNames
Comma-delimited list of java.security.Principal classes that represent security roles.
protected List
roleClasses
The list of role class names, split out for easy processing.
protected Map
roleMap
Map associating each user Principal object with an array of role Principals.
protected static StringManager
sm
The string manager for this package.
protected boolean
useContextClassLoader
Whether to use context ClassLoader or default ClassLoader.
protected String
userClassNames
Comma-delimited list of java.security.Principal classes that represent individual users.
protected List
userClasses
The set of user class names, split out for easy processing.

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
authenticate(String username, String credentials)
Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
protected Principal
createPrincipal(String username, Subject subject)
Identify and return a java.security.Principal instance representing the authenticated user for the specified Subject.
String
getAppName()
getter for the appName member variable
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.
String
getRoleClassNames()
String
getUserClassNames()
boolean
hasRole(Principal principal, String role)
Returns true if the specified user Principal has the specified security role, within the context of this Realm; otherwise return false.
boolean
isUseContextClassLoader()
Returns whether to use the context or default ClassLoader.
protected String
makeLegalForJAAS(String src)
Ensure the given name is legal for JAAS configuration.
void
setAppName(String name)
Deprecated. JAAS should use the Engine (domain) name and webpp/host overrides
void
setContainer(Container container)
void
setRoleClassNames(String roleClassNames)
Sets the list of comma-delimited classes that represent roles.
void
setUseContextClassLoader(boolean useContext)
Sets whether to use the context or default ClassLoader.
void
setUserClassNames(String userClassNames)
Sets the list of comma-delimited classes that represent individual users.
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

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

Field Details

appName

protected String appName
The application name passed to the JAAS LoginContext, which uses it to select the set of relevant LoginModules.


info

protected static final String info
Descriptive information about this Realm implementation.


name

protected static final String name
Descriptive information about this Realm implementation.


roleClassNames

protected String roleClassNames
Comma-delimited list of java.security.Principal classes that represent security roles.


roleClasses

protected List roleClasses
The list of role class names, split out for easy processing.


roleMap

protected Map roleMap
Map associating each user Principal object with an array of role Principals. This Map is read when hasRole is called.


sm

protected static final StringManager sm
The string manager for this package.


useContextClassLoader

protected boolean useContextClassLoader
Whether to use context ClassLoader or default ClassLoader. True means use context ClassLoader, and True is the default value.


userClassNames

protected String userClassNames
Comma-delimited list of java.security.Principal classes that represent individual users.


userClasses

protected List userClasses
The set of user class names, split out for easy processing.

Method Details

authenticate

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.
Specified by:
authenticate in interface Realm
Overrides:
authenticate in interface RealmBase

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


createPrincipal

protected Principal createPrincipal(String username,
                                    Subject subject)
Identify and return a java.security.Principal instance representing the authenticated user for the specified Subject. The Principal is constructed by scanning the list of Principals returned by the JAASLoginModule. The first Principal object that matches one of the class names supplied as a "user class" is the user Principal. This object is returned to tha caller. Any remaining principal objects returned by the LoginModules are mapped to roles, but only if their respective classes match one of the "role class" classes. If a user Principal cannot be constructed, return null.

Parameters:
subject - The Subject representing the logged-in user


getAppName

public String getAppName()
getter for the appName member variable


getName

protected String getName()
Return a short name for this Realm implementation.
Overrides:
getName in interface RealmBase


getPassword

protected String getPassword(String username)
Return the password associated with the given principal's user name.
Overrides:
getPassword in interface RealmBase


getPrincipal

protected Principal getPrincipal(String username)
Return the Principal associated with the given user name.
Overrides:
getPrincipal in interface RealmBase


getRoleClassNames

public String getRoleClassNames()


getUserClassNames

public String getUserClassNames()


hasRole

public boolean hasRole(Principal principal,
                       String role)
Returns true if the specified user Principal has the specified security role, within the context of this Realm; otherwise return false. This will be true when an associated role Principal can be found whose getName method returns a String equalling the specified role.
Specified by:
hasRole in interface Realm
Overrides:
hasRole in interface RealmBase

Parameters:
principal - Principal for whom the role is to be checked
role - Security role to be checked


isUseContextClassLoader

public boolean isUseContextClassLoader()
Returns whether to use the context or default ClassLoader. True means to use the context ClassLoader.

Returns:
The value of useContextClassLoader


makeLegalForJAAS

protected String makeLegalForJAAS(String src)
Ensure the given name is legal for JAAS configuration. Added for Bugzilla 30869, made protected for easy customization in case my implementation is insufficient, which I think is very likely.

Parameters:
src - The name to validate

Returns:
A string that's a valid JAAS realm name


setAppName

public void setAppName(String name)

Deprecated. JAAS should use the Engine (domain) name and webpp/host overrides

setter for the appName member variable


setContainer

public void setContainer(Container container)
Specified by:
setContainer in interface Realm
Overrides:
setContainer in interface RealmBase


setRoleClassNames

public void setRoleClassNames(String roleClassNames)
Sets the list of comma-delimited classes that represent roles. The classes in the list must implement java.security.Principal. When this accessor is called (for example, by a Digester instance parsing the configuration file), it will parse the class names and store the resulting string(s) into the ArrayList field roleClasses.


setUseContextClassLoader

public void setUseContextClassLoader(boolean useContext)
Sets whether to use the context or default ClassLoader. True means use context ClassLoader.

Parameters:
useContext - True means use context ClassLoader


setUserClassNames

public void setUserClassNames(String userClassNames)
Sets the list of comma-delimited classes that represent individual users. The classes in the list must implement java.security.Principal. When this accessor is called (for example, by a Digester instance parsing the configuration file), it will parse the class names and store the resulting string(s) into the ArrayList field userClasses.


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 interface RealmBase

Throws:
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 interface RealmBase

Throws:
LifecycleException - if this component detects a fatal error that needs to be reported


Copyright B) 2000-2003 Apache Software Foundation. All Rights Reserved.