Class JAASRealm
- All Implemented Interfaces:
MBeanRegistration,Contained,JmxEnabled,Lifecycle,Realm
Implementation of Realm that authenticates users via the Java Authentication and Authorization Service (JAAS).
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 Summary
Nested classes/interfaces inherited from class org.apache.catalina.realm.RealmBase
RealmBase.AllRolesModeNested classes/interfaces inherited from interface org.apache.catalina.Lifecycle
Lifecycle.SingleUse -
Field Summary
FieldsModifier 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.RealmBase
allRolesMode, container, containerLog, realmPath, sm, stripRealmForGss, support, USER_ATTRIBUTES_DELIMITER, USER_ATTRIBUTES_WILDCARD, userAttributes, userAttributesList, validate, x509UsernameRetriever, x509UsernameRetrieverClassNameFields 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 -
Method Summary
Modifier 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.RealmBase
addPropertyChangeListener, authenticate, authenticate, authenticate, authenticate, backgroundProcess, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, getDomainInternal, getObjectNameKeyProperties, getPrincipal, 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.LifecycleMBeanBase
destroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister, unregisterMethods inherited from class org.apache.catalina.util.LifecycleBase
addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop
-
Field Details
-
appName
The application name passed to the JAASLoginContext, which uses it to select the set of relevantLoginModules. -
roleClasses
-
userClasses
-
useContextClassLoader
protected boolean useContextClassLoaderWhether to use context ClassLoader or default ClassLoader. True means use context ClassLoader, and True is the default value. -
configFile
Path to find a JAAS configuration file, if not set global JVM JAAS configuration will be used. -
jaasConfiguration
-
jaasConfigurationLoaded
protected volatile boolean jaasConfigurationLoaded -
roleClassNames
Comma-delimited list ofjava.security.Principalclasses that represent security roles. -
userClassNames
Comma-delimited list ofjava.security.Principalclasses that represent individual users.
-
-
Constructor Details
-
JAASRealm
public JAASRealm()
-
-
Method Details
-
getConfigFile
- Returns:
- the path of the JAAS configuration file.
-
setConfigFile
Set the JAAS configuration file.- Parameters:
configFile- The JAAS configuration file
-
setAppName
Set the JAASLoginContextapp name.- Parameters:
name- The application name that will be used to retrieve the set of relevantLoginModules
-
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
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
-
setRoleClassNames
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
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
-
setUserClassNames
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
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 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.- 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
Perform the actual JAAS authentication.- Parameters:
username- The user namecallbackHandler- The callback handler- Returns:
- the associated principal, or
nullif there is none.
-
getPassword
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
Description copied from class:RealmBaseGet the principal associated with the specified user.- Specified by:
getPrincipalin classRealmBase- Parameters:
username- The user name- Returns:
- the Principal associated with the given user name.
-
createPrincipal
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
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
Description 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
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
-