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,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.RealmBase
RealmBase.AllRolesMode
-
Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle
Lifecycle.SingleUse
-
-
Field Summary
Fields 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 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.RealmBase
allRolesMode, container, containerLog, realmPath, sm, stripRealmForGss, support, USER_ATTRIBUTES_DELIMITER, USER_ATTRIBUTES_WILDCARD, userAttributes, userAttributesList, validate, x509UsernameRetriever, x509UsernameRetrieverClassName
-
Fields inherited from class org.apache.catalina.util.LifecycleMBeanBase
mserver
-
Fields inherited from interface org.apache.catalina.Lifecycle
AFTER_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 Summary
Constructors Constructor Description JAASRealm()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description java.security.Principalauthenticate(java.lang.String username, java.lang.String credentials)Try to authenticate using the specified username and credentials.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 digestA2, java.lang.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 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.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 theContainerwith which this instance is 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.RealmBase
addPropertyChangeListener, authenticate, authenticate, authenticate, authenticate, authenticate, backgroundProcess, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, getDigest, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getPrincipal, getPrincipal, getRealmPath, getRealmSuffix, getRoles, getServer, getTransportGuaranteeRedirectStatus, getUserAttributes, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRole, hasRoleInternal, hasUserDataPermission, initInternal, isStripRealmForGss, main, parseUserAttributes, removePropertyChangeListener, setAllRolesMode, setCredentialHandler, setRealmPath, setStripRealmForGss, setTransportGuaranteeRedirectStatus, setUserAttributes, setValidate, setX509UsernameRetrieverClassName, stopInternal, toString
-
Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase
destroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister, unregister
-
Methods inherited from class org.apache.catalina.util.LifecycleBase
addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop
-
-
-
-
Field Detail
-
appName
protected java.lang.String appName
The application name passed to the JAASLoginContext, which uses it to select the set of relevantLoginModules.
-
roleClasses
protected final java.util.List<java.lang.String> roleClasses
The list of role class names, split out for easy processing.
-
userClasses
protected final java.util.List<java.lang.String> 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.
-
configFile
protected java.lang.String configFile
Path to find a JAAS configuration file, if not set global JVM JAAS configuration will be used.
-
jaasConfiguration
protected volatile javax.security.auth.login.Configuration jaasConfiguration
-
jaasConfigurationLoaded
protected volatile boolean jaasConfigurationLoaded
-
roleClassNames
protected java.lang.String roleClassNames
Comma-delimited list ofjava.security.Principalclasses that represent security roles.
-
userClassNames
protected java.lang.String userClassNames
Comma-delimited list ofjava.security.Principalclasses that represent individual users.
-
-
Method Detail
-
getConfigFile
public java.lang.String getConfigFile()
- Returns:
- the path of the JAAS configuration file.
-
setConfigFile
public void setConfigFile(java.lang.String configFile)
Set the JAAS configuration file.- Parameters:
configFile- The JAAS configuration file
-
setAppName
public void setAppName(java.lang.String name)
Set the JAASLoginContextapp name.- Parameters:
name- The application name that will be used to retrieve the set of relevantLoginModules
-
getAppName
public java.lang.String getAppName()
- Returns:
- the application name.
-
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 interface:ContainedSet theContainerwith which this instance is associated.- Specified by:
setContainerin interfaceContained- Overrides:
setContainerin classRealmBase- Parameters:
container- The Container instance with which this instance is to be associated, ornullto disassociate this instance from any Container
-
getRoleClassNames
public java.lang.String getRoleClassNames()
-
setRoleClassNames
public 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
-
parseClassNames
protected 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.
-
getUserClassNames
public java.lang.String getUserClassNames()
-
setUserClassNames
public 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
-
authenticate
public java.security.Principal authenticate(java.lang.String username, java.lang.String credentials)Description copied from interface:RealmTry to authenticate using the specified username and credentials.- Specified by:
authenticatein interfaceRealm- Overrides:
authenticatein classRealmBase- Parameters:
username- Username of the Principal to look upcredentials- Password or other credentials to use in authenticating this username- Returns:
- the associated principal, or
nullif there is none
-
authenticate
public 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 digestA2, java.lang.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 interfaceRealm- Overrides:
authenticatein classRealmBase- Parameters:
username- Username of the Principal to look upclientDigest- Digest which has been submitted by the clientnonce- Unique (or supposedly unique) token which has been used for this requestnc- the nonce countercnonce- the client chosen nonceqop- the "quality of protection" (ncandcnoncewill only be used, ifqopis notnull).realmName- Realm namedigestA2- Second digest calculated as digest(Method + ":" + uri)algorithm- The message digest algorithm to use- Returns:
- the associated principal, or
nullif there is none.
-
authenticate
protected java.security.Principal authenticate(java.lang.String username, javax.security.auth.callback.CallbackHandler callbackHandler)Perform the actual JAAS authentication.- Parameters:
username- The user namecallbackHandler- The callback handler- Returns:
- the associated principal, or
nullif there is none.
-
getPassword
protected java.lang.String getPassword(java.lang.String username)
Description copied from class:RealmBaseGet the password for the specified user.- Specified by:
getPasswordin classRealmBase- 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.
-
getPrincipal
protected java.security.Principal getPrincipal(java.lang.String username)
Description copied from class:RealmBaseGet the principal associated with the specified user.- Specified by:
getPrincipalin classRealmBase- Parameters:
username- The user name- Returns:
- the
Principalassociated with the given user name.
-
createPrincipal
protected 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 namesubject- TheSubjectrepresenting the logged-in userloginContext- Associated with the Principal soLoginContext.logout()can be called later- Returns:
- the principal object
-
makeLegalForJAAS
protected 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
-
startInternal
protected void startInternal() throws LifecycleExceptionDescription 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 classRealmBase- Throws:
LifecycleException- if this component detects a fatal error that prevents this component from being used
-
getConfig
protected javax.security.auth.login.Configuration getConfig()
Load custom JAAS Configuration.- Returns:
- the loaded configuration
-
isAvailable
public boolean isAvailable()
Description copied from interface:RealmReturn the availability of the realm for authentication.- Returns:
trueif the realm is able to perform authentication
-
-