org.apache.catalina.realm
Class JAASRealm
- Lifecycle, MBeanRegistration, Realm
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:
- The JAAS
LoginModule
is assumed to return a
Subject
with at least one Principal
instance
representing the user himself or herself, and zero or more separate
Principals
representing the security roles authorized
for this user.
- On the
Principal
representing the user, the Principal
name is an appropriate value to return via the Servlet API method
HttpServletRequest.getRemoteUser()
.
- On the
Principals
representing the security roles, the
name is the name of the authorized security role.
- This Realm will be configured with two lists of fully qualified Java
class names of classes that implement
java.security.Principal
- one that identifies class(es)
representing a user, and one that identifies class(es) representing
a security role.
- As this Realm iterates over the
Principals
returned by
Subject.getPrincipals()
, it will identify the first
Principal
that matches the "user classes" list as the
Principal
for this user.
- As this Realm iterates over the
Princpals
returned by
Subject.getPrincipals()
, it will accumulate the set of
all Principals
matching the "role classes" list as
identifying the security roles for this user.
- It is a configuration error for the JAAS login method to return a
validated
Subject
without a Principal
that
matches the "user classes" list.
- By default, the enclosing Container's name serves as the
application name used to obtain the JAAS LoginContext ("Catalina" in
a default installation). Tomcat must be able to find an application
with this name in the JAAS configuration file. Here is a hypothetical
JAAS configuration file entry for a database-oriented login module that uses
a Tomcat-managed JNDI database resource:
Catalina {
org.foobar.auth.DatabaseLoginModule REQUIRED
JNDI_RESOURCE=jdbc/AuthDB
USER_TABLE=users
USER_ID_COLUMN=id
USER_NAME_COLUMN=name
USER_CREDENTIAL_COLUMN=password
ROLE_TABLE=roles
ROLE_NAME_COLUMN=name
PRINCIPAL_FACTORY=org.foobar.auth.impl.SimplePrincipalFactory;
};
- To set the JAAS configuration file
location, set the
CATALINA_OPTS
environment variable
similar to the following:
CATALINA_OPTS="-Djava.security.auth.login.config=$CATALINA_HOME/conf/jaas.config"
- As part of the login process, JAASRealm registers its own
CallbackHandler
,
called (unsurprisingly) JAASCallbackHandler
. This handler supplies the
HTTP requests's username and credentials to the user-supplied LoginModule
- As with other
Realm
implementations, digested passwords are supported if
the <Realm>
element in server.xml
contains a
digest
attribute; JAASCallbackHandler
will digest the password
prior to passing it back to the LoginModule
Version:
- Craig R. McClanahan
- Yoav Shapira
- Andrew R. Jaquith
protected String | appName - The application name passed to the JAAS
LoginContext ,
which uses it to select the set of relevant LoginModule s.
|
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 Principal s.
|
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.
|
container , controller , debug , digest , digestEncoding , domain , host , info , initialized , lifecycle , md , md5Encoder , md5Helper , mserver , oname , path , sm , started , support , type , validate |
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) - 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 .
|
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 |
appName
protected String appName
The application name passed to the JAAS LoginContext
,
which uses it to select the set of relevant LoginModule
s.
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 Principal
s.
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.
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.
- authenticate in interface Realm
- authenticate in interface RealmBase
username
- Username of the Principal
to look upcredentials
- 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
.
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.
- getName in interface RealmBase
getPassword
protected String getPassword(String username)
Return the password associated with the given principal's user name.
- getPassword in interface RealmBase
getPrincipal
protected Principal getPrincipal(String username)
Return the Principal
associated with the given user name.
- 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.
- hasRole in interface Realm
- hasRole in interface RealmBase
principal
- Principal
for whom the role is to be checkedrole
- 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.
- 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.
src
- The name to validate
- A string that's a valid JAAS realm name
setAppName
public void setAppName(String name)
JAAS should use the Engine
(domain) name and webpp/host overrides
setter for the appName
member variable
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.
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.
Copyright B) 2000-2003 Apache Software Foundation. All Rights Reserved.