Class JAASRealm
- All Implemented Interfaces:
- MBeanRegistration,- Contained,- JmxEnabled,- Lifecycle,- Realm
 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.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 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 SummaryNested classes/interfaces inherited from class org.apache.catalina.realm.RealmBaseRealmBase.AllRolesModeNested classes/interfaces inherited from interface org.apache.catalina.LifecycleLifecycle.SingleUse
- 
Field SummaryFieldsModifier and TypeFieldDescriptionprotected StringThe application name passed to the JAASLoginContext, which uses it to select the set of relevantLoginModules.protected StringPath to find a JAAS configuration file, if not set global JVM JAAS configuration will be used.protected Configurationprotected booleanThe list of role class names, split out for easy processing.protected StringComma-delimited list ofjava.security.Principalclasses that represent security roles.protected booleanWhether to use context ClassLoader or default ClassLoader.The set of user class names, split out for easy processing.protected StringComma-delimited list ofjava.security.Principalclasses that represent individual users.Fields inherited from class org.apache.catalina.realm.RealmBaseallRolesMode, container, containerLog, realmPath, sm, stripRealmForGss, support, USER_ATTRIBUTES_DELIMITER, USER_ATTRIBUTES_WILDCARD, userAttributes, userAttributesList, validate, x509UsernameRetriever, x509UsernameRetrieverClassNameFields 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
- 
Method SummaryModifier and TypeMethodDescriptionauthenticate(String username, String credentials) Try to authenticate using the specified username and credentials.authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realmName, String digestA2, String algorithm) Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 7616.protected Principalauthenticate(String username, CallbackHandler callbackHandler) Perform the actual JAAS authentication.protected PrincipalcreatePrincipal(String username, Subject subject, LoginContext loginContext) Identify and return ajava.security.Principalinstance representing the authenticated user for the specifiedSubject.protected ConfigurationLoad custom JAAS Configuration.protected StringgetPassword(String username) Get the password for the specified user.protected PrincipalgetPrincipal(String username) Get the principal associated with the specified user.booleanReturn the availability of the realm for authentication.booleanReturns whether to use the context or default ClassLoader.protected StringmakeLegalForJAAS(String src) Ensure the given name is legal for JAAS configuration.protected voidparseClassNames(String classNamesString, List<String> classNamesList) Parses a comma-delimited list of class names, and store the class names in the provided List.voidsetAppName(String name) Set the JAASLoginContextapp name.voidsetConfigFile(String configFile) Set the JAAS configuration file.voidsetContainer(Container container) Set theContainerwith which this instance is associated.voidsetRoleClassNames(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(String userClassNames) Sets the list of comma-delimited classes that represent individual users.protected voidPrepare 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, authenticate, backgroundProcess, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, getDigest, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getPrincipal, getRealmPath, getRealmSuffix, getServer, getTransportGuaranteeRedirectStatus, getUserAttributes, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRole, hasRoleInternal, hasUserDataPermission, initInternal, isStripRealmForGss, main, parseUserAttributes, removePropertyChangeListener, setAllRolesMode, setCredentialHandler, setRealmPath, setStripRealmForGss, setTransportGuaranteeRedirectStatus, setUserAttributes, setValidate, setX509UsernameRetrieverClassName, stopInternal, toStringMethods inherited from class org.apache.catalina.util.LifecycleMBeanBasedestroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister, unregisterMethods inherited from class org.apache.catalina.util.LifecycleBaseaddLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop
- 
Field Details- 
appNameThe application name passed to the JAASLoginContext, which uses it to select the set of relevantLoginModules.
- 
roleClassesThe list of role class names, split out for easy processing.
- 
userClassesThe set of user class names, split out for easy processing.
- 
useContextClassLoaderprotected boolean useContextClassLoaderWhether to use context ClassLoader or default ClassLoader. True means use context ClassLoader, and True is the default value.
- 
configFilePath to find a JAAS configuration file, if not set global JVM JAAS configuration will be used.
- 
jaasConfiguration
- 
jaasConfigurationLoadedprotected volatile boolean jaasConfigurationLoaded
- 
roleClassNamesComma-delimited list ofjava.security.Principalclasses that represent security roles.
- 
userClassNamesComma-delimited list ofjava.security.Principalclasses that represent individual users.
 
- 
- 
Constructor Details- 
JAASRealmpublic JAASRealm()
 
- 
- 
Method Details- 
getConfigFile- Returns:
- the path of the JAAS configuration file.
 
- 
setConfigFileSet the JAAS configuration file.- Parameters:
- configFile- The JAAS configuration file
 
- 
setAppNameSet the JAASLoginContextapp name.- Parameters:
- name- The application name that will be used to retrieve the set of relevant- LoginModules
 
- 
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
 
- 
setContainerDescription copied from interface:ContainedSet theContainerwith which this instance is associated.- Specified by:
- setContainerin interface- Contained
- Overrides:
- setContainerin class- RealmBase
- Parameters:
- container- The Container instance with which this instance is to be associated, or- nullto disassociate this instance from any Container
 
- 
getRoleClassNames
- 
setRoleClassNamesSets 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
 
- 
parseClassNamesParses 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.
 
- 
getUserClassNames
- 
setUserClassNamesSets 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
 
- 
authenticateDescription copied from interface:RealmTry to authenticate using the specified username and credentials.- Specified by:
- authenticatein interface- Realm
- Overrides:
- authenticatein class- RealmBase
- Parameters:
- username- Username of the Principal to look up
- credentials- Password or other credentials to use in authenticating this username
- Returns:
- the associated principal, or nullif there is none
 
- 
authenticatepublic Principal authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realmName, String digestA2, String algorithm) Description copied from interface:RealmTry to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 7616.The default implementation calls Realm.authenticate(String, String, String, String, String, String, String, String)for backwards compatibility which effectively forces the use of MD5 regardless of the algorithm specified in the call to this method.Implementations are expected to override the default implementation and take account of the algorithm parameter. - Specified by:
- authenticatein interface- Realm
- Overrides:
- authenticatein class- RealmBase
- Parameters:
- username- Username of the Principal to look up
- clientDigest- Digest which has been submitted by the client
- nonce- Unique (or supposedly unique) token which has been used for this request
- nc- the nonce counter
- cnonce- the client chosen nonce
- qop- the "quality of protection" (- ncand- cnoncewill only be used, if- qopis not- null).
- realmName- Realm name
- digestA2- Second digest calculated as digest(Method + ":" + uri)
- algorithm- The message digest algorithm to use
- Returns:
- the associated principal, or nullif there is none.
 
- 
authenticatePerform the actual JAAS authentication.- Parameters:
- username- The user name
- callbackHandler- The callback handler
- Returns:
- the associated principal, or nullif there is none.
 
- 
getPasswordDescription 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.
 
- 
getPrincipalDescription 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.
 
- 
createPrincipalIdentify 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
 
- 
makeLegalForJAASEnsure 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
 
- 
startInternalDescription copied from class:RealmBasePrepare 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
 
- 
getConfigLoad custom JAAS Configuration.- Returns:
- the loaded configuration
 
- 
isAvailablepublic boolean isAvailable()Description copied from interface:RealmReturn the availability of the realm for authentication.- Returns:
- trueif the realm is able to perform authentication
 
 
-