Class JAASRealm
- java.lang.Object
- 
- org.apache.catalina.util.LifecycleBase
- 
- org.apache.catalina.util.LifecycleMBeanBase
- 
- org.apache.catalina.realm.RealmBase
- 
- org.apache.catalina.realm.JAASRealm
 
 
 
 
- 
- All Implemented Interfaces:
- javax.management.MBeanRegistration,- Contained,- GSSRealm,- JmxEnabled,- Lifecycle,- Realm
 
 public class JAASRealm extends RealmBase Implementation 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.jarfile).The value configured for the appNameproperty is passed to thejavax.security.auth.login.LoginContextconstructor, to specify the application name used to select the set of relevantLoginModulesrequired.The JAAS Specification describes the result of a successful login as a javax.security.auth.Subjectinstance, which can contain zero or morejava.security.Principalobjects in the return value of theSubject.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 underlyingLoginMethodimplementation executed by JAAS, the following policy is implemented by this Realm:- The JAAS LoginModuleis assumed to return aSubjectwith at least onePrincipalinstance representing the user himself or herself, and zero or more separatePrincipalsrepresenting the security roles authorized for this user.
- On the Principalrepresenting the user, the Principal name is an appropriate value to return via the Servlet API methodHttpServletRequest.getRemoteUser().
- On the Principalsrepresenting 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 Principalsreturned bySubject.getPrincipals(), it will identify the firstPrincipalthat matches the "user classes" list as thePrincipalfor this user.
- As this Realm iterates over the Principalsreturned bySubject.getPrincipals(), it will accumulate the set of allPrincipalsmatching 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 Subjectwithout aPrincipalthat 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_OPTSenvironment 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-suppliedLoginModule
- As with other Realmimplementations, digested passwords are supported if the<Realm>element inserver.xmlcontains adigestattribute;JAASCallbackHandlerwill digest the password prior to passing it back to theLoginModule
 - Author:
- Craig R. McClanahan, Yoav Shapira
 
- 
- 
Nested Class Summary- 
Nested classes/interfaces inherited from class org.apache.catalina.realm.RealmBaseRealmBase.AllRolesMode
 - 
Nested classes/interfaces inherited from interface org.apache.catalina.LifecycleLifecycle.SingleUse
 
- 
 - 
Field SummaryFields Modifier and Type Field Description protected java.lang.StringappNameThe application name passed to the JAASLoginContext, which uses it to select the set of relevantLoginModules.protected java.lang.StringconfigFilePath to find a JAAS configuration file, if not set global JVM JAAS configuration will be used.protected javax.security.auth.login.ConfigurationjaasConfigurationprotected booleanjaasConfigurationLoadedprotected static java.lang.StringnameDeprecated.This will be removed in Tomcat 9 onwards.protected java.util.List<java.lang.String>roleClassesThe list of role class names, split out for easy processing.protected java.lang.StringroleClassNamesComma-delimited list ofjava.security.Principalclasses that represent security roles.protected booleanuseContextClassLoaderWhether to use context ClassLoader or default ClassLoader.protected java.util.List<java.lang.String>userClassesThe set of user class names, split out for easy processing.protected java.lang.StringuserClassNamesComma-delimited list ofjava.security.Principalclasses that represent individual users.- 
Fields inherited from class org.apache.catalina.realm.RealmBaseallRolesMode, container, containerLog, realmPath, sm, stripRealmForGss, support, validate, x509UsernameRetriever, x509UsernameRetrieverClassName
 - 
Fields inherited from class org.apache.catalina.util.LifecycleMBeanBasemserver
 - 
Fields inherited from interface org.apache.catalina.LifecycleAFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT
 
- 
 - 
Constructor SummaryConstructors Constructor Description JAASRealm()
 - 
Method SummaryAll Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description java.security.Principalauthenticate(java.lang.String username, java.lang.String credentials)Return thePrincipalassociated with the specified username and credentials, if there is one; otherwise returnnull.java.security.Principalauthenticate(java.lang.String username, java.lang.String clientDigest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realmName, java.lang.String md5a2)Return thePrincipalassociated with the specified username and digest, if there is one; otherwise returnnull.protected java.security.Principalauthenticate(java.lang.String username, javax.security.auth.callback.CallbackHandler callbackHandler)Perform the actual JAAS authentication.protected java.security.PrincipalcreatePrincipal(java.lang.String username, javax.security.auth.Subject subject, javax.security.auth.login.LoginContext loginContext)Identify and return ajava.security.Principalinstance representing the authenticated user for the specifiedSubject.java.lang.StringgetAppName()protected javax.security.auth.login.ConfigurationgetConfig()Load custom JAAS Configuration.java.lang.StringgetConfigFile()protected java.lang.StringgetName()Deprecated.protected java.lang.StringgetPassword(java.lang.String username)Get the password for the specified user.protected java.security.PrincipalgetPrincipal(java.lang.String username)Get the principal associated with the specified user.java.lang.StringgetRoleClassNames()java.lang.StringgetUserClassNames()booleanisAvailable()Return the availability of the realm for authentication.booleanisUseContextClassLoader()Returns whether to use the context or default ClassLoader.protected java.lang.StringmakeLegalForJAAS(java.lang.String src)Ensure the given name is legal for JAAS configuration.protected voidparseClassNames(java.lang.String classNamesString, java.util.List<java.lang.String> classNamesList)Parses a comma-delimited list of class names, and store the class names in the provided List.voidsetAppName(java.lang.String name)Set the JAASLoginContextapp name.voidsetConfigFile(java.lang.String configFile)Set the JAAS configuration file.voidsetContainer(Container container)Set the Container with which this Realm has been associated.voidsetRoleClassNames(java.lang.String roleClassNames)Sets the list of comma-delimited classes that represent roles.voidsetUseContextClassLoader(boolean useContext)Sets whether to use the context or default ClassLoader.voidsetUserClassNames(java.lang.String userClassNames)Sets the list of comma-delimited classes that represent individual users.protected voidstartInternal()Prepare for the beginning of active use of the public methods of this component and implement the requirements ofLifecycleBase.startInternal().- 
Methods inherited from class org.apache.catalina.realm.RealmBaseaddPropertyChangeListener, authenticate, authenticate, authenticate, authenticate, backgroundProcess, Digest, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getPrincipal, getPrincipal, getRealmPath, getRealmSuffix, getRoles, getServer, getTransportGuaranteeRedirectStatus, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRole, hasRoleInternal, hasUserDataPermission, initInternal, isStripRealmForGss, main, removePropertyChangeListener, setAllRolesMode, setCredentialHandler, setRealmPath, setStripRealmForGss, setTransportGuaranteeRedirectStatus, setValidate, setX509UsernameRetrieverClassName, stopInternal, toString
 - 
Methods inherited from class org.apache.catalina.util.LifecycleMBeanBasedestroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister
 - 
Methods inherited from class org.apache.catalina.util.LifecycleBaseaddLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop
 
- 
 
- 
- 
- 
Field Detail- 
appNameprotected java.lang.String appName The application name passed to the JAASLoginContext, which uses it to select the set of relevantLoginModules.
 - 
name@Deprecated protected static final java.lang.String name Deprecated.This will be removed in Tomcat 9 onwards.Descriptive information about thisRealmimplementation.- See Also:
- Constant Field Values
 
 - 
roleClassesprotected final java.util.List<java.lang.String> roleClasses The list of role class names, split out for easy processing.
 - 
userClassesprotected final java.util.List<java.lang.String> userClasses The set of user class names, split out for easy processing.
 - 
useContextClassLoaderprotected boolean useContextClassLoader Whether to use context ClassLoader or default ClassLoader. True means use context ClassLoader, and True is the default value.
 - 
configFileprotected java.lang.String configFile Path to find a JAAS configuration file, if not set global JVM JAAS configuration will be used.
 - 
jaasConfigurationprotected volatile javax.security.auth.login.Configuration jaasConfiguration 
 - 
jaasConfigurationLoadedprotected volatile boolean jaasConfigurationLoaded 
 - 
roleClassNamesprotected java.lang.String roleClassNames Comma-delimited list ofjava.security.Principalclasses that represent security roles.
 - 
userClassNamesprotected java.lang.String userClassNames Comma-delimited list ofjava.security.Principalclasses that represent individual users.
 
- 
 - 
Method Detail- 
getConfigFilepublic java.lang.String getConfigFile() - Returns:
- the path of the JAAS configuration file.
 
 - 
setConfigFilepublic void setConfigFile(java.lang.String configFile) Set the JAAS configuration file.- Parameters:
- configFile- The JAAS configuration file
 
 - 
setAppNamepublic void setAppName(java.lang.String name) Set the JAASLoginContextapp name.- Parameters:
- name- The application name that will be used to retrieve the set of relevant- LoginModules
 
 - 
getAppNamepublic java.lang.String getAppName() - Returns:
- the application name.
 
 - 
setUseContextClassLoaderpublic 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
 
 - 
isUseContextClassLoaderpublic boolean isUseContextClassLoader() Returns whether to use the context or default ClassLoader. True means to use the context ClassLoader.- Returns:
- The value of useContextClassLoader
 
 - 
setContainerpublic void setContainer(Container container) Description copied from class:RealmBaseSet the Container with which this Realm has been associated.- Specified by:
- setContainerin interface- Contained
- Overrides:
- setContainerin class- RealmBase
- Parameters:
- container- The associated Container
 
 - 
getRoleClassNamespublic java.lang.String getRoleClassNames() 
 - 
setRoleClassNamespublic void setRoleClassNames(java.lang.String roleClassNames) Sets the list of comma-delimited classes that represent roles. The classes in the list must implementjava.security.Principal. The supplied list of classes will be parsed whenLifecycleBase.start()is called.- Parameters:
- roleClassNames- The class names list
 
 - 
parseClassNamesprotected void parseClassNames(java.lang.String classNamesString, java.util.List<java.lang.String> classNamesList)Parses a comma-delimited list of class names, and store the class names in the provided List. Each class must implementjava.security.Principal.- Parameters:
- classNamesString- a comma-delimited list of fully qualified class names.
- classNamesList- the list in which the class names will be stored. The list is cleared before being populated.
 
 - 
getUserClassNamespublic java.lang.String getUserClassNames() 
 - 
setUserClassNamespublic void setUserClassNames(java.lang.String userClassNames) Sets the list of comma-delimited classes that represent individual users. The classes in the list must implementjava.security.Principal. The supplied list of classes will be parsed whenLifecycleBase.start()is called.- Parameters:
- userClassNames- The class names list
 
 - 
authenticatepublic java.security.Principal authenticate(java.lang.String username, java.lang.String credentials)Return thePrincipalassociated with the specified username and credentials, if there is one; otherwise returnnull.- Specified by:
- authenticatein interface- Realm
- Overrides:
- authenticatein class- RealmBase
- Parameters:
- username- Username of the- Principalto look up
- credentials- Password or other credentials to use in authenticating this username
- Returns:
- the associated principal, or nullif there is none.
 
 - 
authenticatepublic java.security.Principal authenticate(java.lang.String username, java.lang.String clientDigest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realmName, java.lang.String md5a2)Return thePrincipalassociated with the specified username and digest, if there is one; otherwise returnnull.- Specified by:
- authenticatein interface- Realm
- Overrides:
- authenticatein class- RealmBase
- Parameters:
- username- Username of the- Principalto look up
- clientDigest- Digest to use in authenticating this username
- nonce- Server generated nonce
- nc- Nonce count
- cnonce- Client generated nonce
- qop- Quality of protection applied to the message
- realmName- Realm name
- md5a2- Second MD5 digest used to calculate the digest MD5(Method + ":" + uri)
- Returns:
- the associated principal, or nullif there is none.
 
 - 
authenticateprotected java.security.Principal authenticate(java.lang.String username, javax.security.auth.callback.CallbackHandler callbackHandler)Perform the actual JAAS authentication.- Parameters:
- username- The user name
- callbackHandler- The callback handler
- Returns:
- the associated principal, or nullif there is none.
 
 - 
getName@Deprecated protected java.lang.String getName() Deprecated.
 - 
getPasswordprotected java.lang.String getPassword(java.lang.String username) Description copied from class:RealmBaseGet the password for the specified user.- Specified by:
- getPasswordin class- RealmBase
- Parameters:
- username- The user name
- Returns:
- the password associated with the given principal's user name. This always returns null as the JAASRealm has no way of obtaining this information.
 
 - 
getPrincipalprotected java.security.Principal getPrincipal(java.lang.String username) Description copied from class:RealmBaseGet the principal associated with the specified user.- Specified by:
- getPrincipalin class- RealmBase
- Parameters:
- username- The user name
- Returns:
- the Principalassociated with the given user name.
 
 - 
createPrincipalprotected java.security.Principal createPrincipal(java.lang.String username, javax.security.auth.Subject subject, javax.security.auth.login.LoginContext loginContext)Identify and return ajava.security.Principalinstance representing the authenticated user for the specifiedSubject. The Principal is constructed by scanning the list of Principals returned by the JAASLoginModule. The firstPrincipalobject that matches one of the class names supplied as a "user class" is the user Principal. This object is returned to the 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, returnnull.- Parameters:
- username- The associated user name
- subject- The- Subjectrepresenting the logged-in user
- loginContext- Associated with the Principal so- LoginContext.logout()can be called later
- Returns:
- the principal object
 
 - 
makeLegalForJAASprotected java.lang.String makeLegalForJAAS(java.lang.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
 
 - 
startInternalprotected void startInternal() throws LifecycleExceptionPrepare for the beginning of active use of the public methods of this component and implement the requirements ofLifecycleBase.startInternal().- Overrides:
- startInternalin class- RealmBase
- Throws:
- LifecycleException- if this component detects a fatal error that prevents this component from being used
 
 - 
getConfigprotected javax.security.auth.login.Configuration getConfig() Load custom JAAS Configuration.- Returns:
- the loaded configuration
 
 - 
isAvailablepublic boolean isAvailable() Description copied from interface:RealmReturn the availability of the realm for authentication.- Specified by:
- isAvailablein interface- Realm
- Overrides:
- isAvailablein class- RealmBase
- Returns:
- trueif the realm is able to perform authentication
 
 
- 
 
-