JAASRealm (Tomcat 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 JAASRealm

java.lang.Object
  org.apache.catalina.realm.RealmBase
      org.apache.catalina.realm.JAASRealm

All Implemented Interfaces:: Lifecycle, javax.management.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:

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.






Version:
  $Revision: 1.6.2.1 $ $Date: 2004/08/21 15:49:53 $
Author:
  Craig R. McClanahan, Yoav Shapira













Field Summary



protected  java.lang.String
appName



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



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.util.ArrayList
roleClasses



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



protected  java.lang.String
roleClassNames



          Comma-delimited list of javax.security.Principal classes
 that represent security roles.



protected static StringManager
sm



          The string manager for this package.



protected  boolean
useContextClassLoader



          Whether to use context ClassLoader or default ClassLoader.



protected  java.util.ArrayList
userClasses



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



protected  java.lang.String
userClassNames



          Comma-delimited list of javax.security.Principal classes
 that represent individual users.


 


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


container, controller, debug, digest, domain, host, initialized, lifecycle, md, md5Encoder, md5Helper, mserver, oname, path, 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


 






Constructor Summary


JAASRealm()



           


 






Method Summary



 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  java.security.Principal
createPrincipal(java.lang.String username,
                javax.security.auth.Subject subject)



          Construct and return a java.security.Principal instance
 representing the authenticated user for the specified Subject.



 java.lang.String
getAppName()



          getter for the appName member variable



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
getRoleClassNames()



           



 java.lang.String
getUserClassNames()



           



 boolean
isUseContextClassLoader()



          Returns whether to use the context or default ClassLoader.



 void
setAppName(java.lang.String name)



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



 void
setContainer(Container container)



          Set the Container with which this Realm has been associated.



 void
setRoleClassNames(java.lang.String roleClassNames)



           



 void
setUseContextClassLoader(boolean useContext)



          Sets whether to use the context or default ClassLoader.



 void
setUserClassNames(java.lang.String userClassNames)



           



 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, destroy, digest, Digest, findLifecycleListeners, findSecurityConstraints, getContainer, getController, getDebug, getDigest, getDigest, getDomain, getInfo, getObjectName, getType, getValidate, hasMessageDigest, hasResourcePermission, hasRole, hasUserDataPermission, init, log, log, main, postDeregister, postRegister, preDeregister, preRegister, removeLifecycleListener, removePropertyChangeListener, setController, setDebug, setDigest, setValidate


 


Methods inherited from class java.lang.Object


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


 








Field Detail




appName
protected java.lang.String appName

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







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




roleClasses
protected java.util.ArrayList roleClasses

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







sm
protected static final StringManager sm

The string manager for this package.







userClasses
protected java.util.ArrayList userClasses

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







useContextClassLoader
protected boolean useContextClassLoader

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







roleClassNames
protected java.lang.String roleClassNames

Comma-delimited list of javax.security.Principal classes
 that represent security roles.







userClassNames
protected java.lang.String userClassNames

Comma-delimited list of javax.security.Principal classes
 that represent individual users.











Constructor Detail




JAASRealm
public JAASRealm()









Method Detail




setAppName
public void setAppName(java.lang.String name)

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

setter for the appName member variable








getAppName
public java.lang.String getAppName()

getter for the appName member variable








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





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





setContainer
public void setContainer(Container container)

Description copied from class: RealmBase
Set the Container with which this Realm has been associated.


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


Parameters:
container - The associated Container





getRoleClassNames
public java.lang.String getRoleClassNames()








setRoleClassNames
public void setRoleClassNames(java.lang.String roleClassNames)








getUserClassNames
public java.lang.String getUserClassNames()








setUserClassNames
public void setUserClassNames(java.lang.String userClassNames)








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





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








createPrincipal
protected java.security.Principal createPrincipal(java.lang.String username,
                                                  javax.security.auth.Subject subject)

Construct and return a java.security.Principal instance
 representing the authenticated user for the specified Subject.  If no
 such Principal can be constructed, return null.


Parameters:
subject - The Subject representing the logged in user





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:
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:
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






Copyright ⌐ 2000-2003 Apache Software Foundation.  All Rights Reserved.

Field Summary
`protected java.lang.String`	`appName` The application name passed to the JAAS `LoginContext`, which uses it to select the set of relevant `LoginModules`.
`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.util.ArrayList`	`roleClasses` The list of role class names, split out for easy processing.
`protected java.lang.String`	`roleClassNames` Comma-delimited list of `javax.security.Principal` classes that represent security roles.
`protected static StringManager`	`sm` The string manager for this package.
`protected boolean`	`useContextClassLoader` Whether to use context ClassLoader or default ClassLoader.
`protected java.util.ArrayList`	`userClasses` The set of user class names, split out for easy processing.
`protected java.lang.String`	`userClassNames` Comma-delimited list of `javax.security.Principal` classes that represent individual users.

Method Summary
`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 java.security.Principal`	`createPrincipal(java.lang.String username, javax.security.auth.Subject subject)` Construct and return a `java.security.Principal` instance representing the authenticated user for the specified Subject.
`java.lang.String`	`getAppName()` getter for the appName member variable
`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`	`getRoleClassNames()`
`java.lang.String`	`getUserClassNames()`
`boolean`	`isUseContextClassLoader()` Returns whether to use the context or default ClassLoader.
`void`	`setAppName(java.lang.String name)` Deprecated. JAAS should use the Engine ( domain ) name and webpp/host overrides
`void`	`setContainer(Container container)` Set the Container with which this Realm has been associated.
`void`	`setRoleClassNames(java.lang.String roleClassNames)`
`void`	`setUseContextClassLoader(boolean useContext)` Sets whether to use the context or default ClassLoader.
`void`	`setUserClassNames(java.lang.String userClassNames)`
`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.

Constructor Summary
`JAASRealm()`

org.apache.catalina.realm Class JAASRealm

appName

info

name

roleClasses

sm

userClasses

useContextClassLoader

roleClassNames

userClassNames

JAASRealm

setAppName

getAppName

setUseContextClassLoader

isUseContextClassLoader

setContainer

getRoleClassNames

setRoleClassNames

getUserClassNames

setUserClassNames

authenticate

getName

getPassword

getPrincipal

createPrincipal

start

stop

org.apache.catalina.realm
Class JAASRealm