Class RealmBase
- All Implemented Interfaces:
- MBeanRegistration,- Contained,- JmxEnabled,- Lifecycle,- Realm
- Direct Known Subclasses:
- AuthenticatedUserRealm,- CombinedRealm,- DataSourceRealm,- JAASRealm,- JNDIRealm,- MemoryRealm,- NullRealm,- UserDatabaseRealm
- Author:
- Craig R. McClanahan
- 
Nested Class SummaryNested ClassesNested classes/interfaces inherited from interface org.apache.catalina.LifecycleLifecycle.SingleUse
- 
Field SummaryFieldsModifier and TypeFieldDescriptionprotected RealmBase.AllRolesModeThe all role mode.protected ContainerThe Container with which this Realm is associated.protected LogContainer logprotected Stringprotected static final StringManagerThe string manager for this package.protected booleanWhen processing users authenticated via the GSS-API, should any "@..." be stripped from the end of the user name?protected final PropertyChangeSupportThe property change support for this component.protected static final StringThe character used for delimiting user attribute names.protected static final StringThe character used as wildcard in user attribute lists.protected StringThe comma separated names of user attributes to additionally query from the realm.The list of user attributes to additionally query from the realm.protected booleanShould we validate client certificate chains when they are presented?protected X509UsernameRetrieverThe object that will extract user names from X509 client certificates.protected StringThe name of the class to use for retrieving user names from X509 certificates.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
- 
Method SummaryModifier and TypeMethodDescriptionvoidAdd a property change listener to this component.authenticate(String username) Try to authenticate with the specified username.authenticate(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 realm, String digestA2) Deprecated.authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realm, 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.authenticate(X509Certificate[] certs) Try to authenticate using a chain ofX509Certificates.authenticate(GSSContext gssContext, boolean storeCred) Try to authenticate using aGSSContext.authenticate(GSSName gssName, GSSCredential gssCredential) Try to authenticate using aGSSName.voidExecute a periodic task, such as reloading, etc.findSecurityConstraints(Request request, Context context) Find the SecurityConstraints configured to guard the request URI for this request.Return the all roles mode.Get theContainerwith which this instance is associated.protected StringDeprecated.Unused.protected StringReturn the digest associated with given principal's user name.Method implemented by sub-classes to identify the domain in which MBeans should be registered.Allow sub-classes to specify the key properties component of theObjectNamethat will be used to register this component.protected abstract StringgetPassword(String username) Get the password for the specified user.protected abstract PrincipalgetPrincipal(String username) Get the principal associated with the specified user.protected PrincipalgetPrincipal(X509Certificate usercert) Get the principal associated with the specified certificate.protected PrincipalgetPrincipal(GSSName gssName, GSSCredential gssCredential) Get the principal associated with the specifiedGSSName.protected Stringprotected ServerReturn the Server object that is the ultimate parent for the container with which this Realm is associated.intbooleanReturn the "validate certificate chains" flag.Gets the name of the class that will be used to extract user names from X509 client certificates.protected booleanhasMessageDigest(String algorithm) booleanhasResourcePermission(Request request, Response response, SecurityConstraint[] constraints, Context context) Perform access control based on the specified authorization constraint.booleanCheck if the specified Principal has the specified security role, within the context of this Realm.protected booleanhasRoleInternal(Principal principal, String role) Check if the specified Principal has the specified security role, within the context of this Realm.booleanhasUserDataPermission(Request request, Response response, SecurityConstraint[] constraints) Enforce any user data constraint required by the security constraint guarding this request URI.protected voidSub-classes wishing to perform additional initialization should override this method, ensuring that super.initInternal() is the first call in the overriding method.booleanstatic voidGenerate a stored credential string for the given password and associated parameters.parseUserAttributes(String userAttributes) Parse the specified delimiter separated attribute names and return a list of that names ornull, if no attributes have been specified.voidRemove a property change listener from this component.voidsetAllRolesMode(String allRolesMode) Set the all roles mode.voidsetContainer(Container container) Set theContainerwith which this instance is associated.voidsetCredentialHandler(CredentialHandler credentialHandler) Set the CredentialHandler to be used by this Realm.voidsetRealmPath(String theRealmPath) voidsetStripRealmForGss(boolean stripRealmForGss) voidsetTransportGuaranteeRedirectStatus(int transportGuaranteeRedirectStatus) Set the HTTP status code used when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee.voidsetUserAttributes(String userAttributes) Set the comma separated names of user attributes to additionally query from the realm.voidsetValidate(boolean validate) Set the "validate certificate chains" flag.voidsetX509UsernameRetrieverClassName(String className) Sets the name of the class that will be used to extract user names from X509 client certificates.protected voidPrepare for the beginning of active use of the public methods of this component and implement the requirements ofLifecycleBase.startInternal().protected voidGracefully terminate the active use of the public methods of this component and implement the requirements ofLifecycleBase.stopInternal().toString()Methods 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, stopMethods inherited from class java.lang.Objectclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitMethods inherited from interface org.apache.catalina.RealmisAvailable
- 
Field Details- 
USER_ATTRIBUTES_DELIMITERThe character used for delimiting user attribute names.Applies to some of the Realm implementations only. - See Also:
 
- 
USER_ATTRIBUTES_WILDCARDThe character used as wildcard in user attribute lists. Using it means query all available user attributes.Applies to some of the Realm implementations only. - See Also:
 
- 
containerThe Container with which this Realm is associated.
- 
containerLogContainer log
- 
smThe string manager for this package.
- 
supportThe property change support for this component.
- 
validateprotected boolean validateShould we validate client certificate chains when they are presented?
- 
x509UsernameRetrieverClassNameThe name of the class to use for retrieving user names from X509 certificates.
- 
x509UsernameRetrieverThe object that will extract user names from X509 client certificates.
- 
allRolesModeThe all role mode.
- 
stripRealmForGssprotected boolean stripRealmForGssWhen processing users authenticated via the GSS-API, should any "@..." be stripped from the end of the user name?
- 
userAttributesThe comma separated names of user attributes to additionally query from the realm. These will be provided to the user through the created Principal's attributes map. Support for this feature is optional.
- 
userAttributesListThe list of user attributes to additionally query from the realm. These will be provided to the user through the created Principal's attributes map. Support for this feature is optional.
- 
realmPath
 
- 
- 
Constructor Details- 
RealmBasepublic RealmBase()
 
- 
- 
Method Details- 
getTransportGuaranteeRedirectStatuspublic int getTransportGuaranteeRedirectStatus()- Returns:
- The HTTP status code used when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee.
 
- 
setTransportGuaranteeRedirectStatuspublic void setTransportGuaranteeRedirectStatus(int transportGuaranteeRedirectStatus) Set the HTTP status code used when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee.- Parameters:
- transportGuaranteeRedirectStatus- The status to use. This value is not validated
 
- 
getCredentialHandler- Specified by:
- getCredentialHandlerin interface- Realm
- Returns:
- the CredentialHandler configured for this Realm.
 
- 
setCredentialHandlerDescription copied from interface:RealmSet the CredentialHandler to be used by this Realm.- Specified by:
- setCredentialHandlerin interface- Realm
- Parameters:
- credentialHandler- the- CredentialHandlerto use
 
- 
getContainerDescription copied from interface:ContainedGet theContainerwith which this instance is associated.- Specified by:
- getContainerin interface- Contained
- Returns:
- The Container with which this instance is associated or
         nullif not associated with a Container
 
- 
setContainerDescription copied from interface:ContainedSet theContainerwith which this instance is associated.- Specified by:
- setContainerin interface- Contained
- Parameters:
- container- The Container instance with which this instance is to be associated, or- nullto disassociate this instance from any Container
 
- 
getAllRolesModeReturn the all roles mode.- Returns:
- A string representation of the current all roles mode
 
- 
setAllRolesModeSet the all roles mode.- Parameters:
- allRolesMode- A string representation of the new all roles mode
 
- 
getValidatepublic boolean getValidate()Return the "validate certificate chains" flag.- Returns:
- The value of the validate certificate chains flag
 
- 
setValidatepublic void setValidate(boolean validate) Set the "validate certificate chains" flag.- Parameters:
- validate- The new validate certificate chains flag
 
- 
getX509UsernameRetrieverClassNameGets the name of the class that will be used to extract user names from X509 client certificates.- Returns:
- The name of the class that will be used to extract user names from X509 client certificates.
 
- 
setX509UsernameRetrieverClassNameSets the name of the class that will be used to extract user names from X509 client certificates. The class must implement X509UsernameRetriever.- Parameters:
- className- The name of the class that will be used to extract user names from X509 client certificates.
- See Also:
 
- 
isStripRealmForGsspublic boolean isStripRealmForGss()
- 
setStripRealmForGsspublic void setStripRealmForGss(boolean stripRealmForGss) 
- 
getUserAttributes- Returns:
- the comma separated names of user attributes to additionally query from realm
 
- 
setUserAttributesSet the comma separated names of user attributes to additionally query from the realm. These will be provided to the user through the created Principal's attributes map. In this map, each field value is bound to the field's name, that is, the name of the field serves as the key of the mapping.If set to the wildcard character, or, if the wildcard character is part of the comma separated list, all available attributes - except the password attribute (as specified by userCredCol) - are queried. The wildcard character is defined by constantUSER_ATTRIBUTES_WILDCARD. It defaults to the asterisk (*) character.- Parameters:
- userAttributes- the comma separated names of user attributes
 
- 
addPropertyChangeListenerDescription copied from interface:RealmAdd a property change listener to this component.- Specified by:
- addPropertyChangeListenerin interface- Realm
- Parameters:
- listener- The listener to add
 
- 
authenticateDescription copied from interface:RealmTry to authenticate with the specified username.- Specified by:
- authenticatein interface- Realm
- Parameters:
- username- Username of the Principal to look up
- Returns:
- the associated principal, or nullif none is associated.
 
- 
authenticateDescription copied from interface:RealmTry to authenticate using the specified username and credentials.- Specified by:
- authenticatein interface- Realm
- 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
 
- 
authenticate@Deprecated public Principal authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realm, String digestA2) Deprecated.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 2617 (which is a superset of RFC 2069).- Specified by:
- authenticatein interface- Realm
- 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).
- realm- Realm name
- digestA2- Second digest calculated as digest(Method + ":" + uri)
- 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 realm, 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
- 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).
- realm- 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.
 
- 
authenticateDescription copied from interface:RealmTry to authenticate using a chain ofX509Certificates.- Specified by:
- authenticatein interface- Realm
- Parameters:
- certs- Array of client certificates, with the first one in the array being the certificate of the client itself.
- Returns:
- the associated principal, or nullif there is none
 
- 
authenticateDescription copied from interface:RealmTry to authenticate using aGSSContext.- Specified by:
- authenticatein interface- Realm
- Parameters:
- gssContext- The gssContext processed by the- Authenticator.
- storeCred- Should the realm attempt to store the delegated credentials in the returned Principal?
- Returns:
- the associated principal, or nullif there is none
 
- 
authenticateDescription copied from interface:RealmTry to authenticate using aGSSName.- Specified by:
- authenticatein interface- Realm
- Parameters:
- gssName- The- GSSNameof the principal to look up
- gssCredential- The- GSSCredentialof the principal, may be- null
- Returns:
- the associated principal, or nullif there is none
 
- 
backgroundProcesspublic void backgroundProcess()Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of this container. Unexpected throwables will be caught and logged.The default implementation is NO-OP. - Specified by:
- backgroundProcessin interface- Realm
 
- 
findSecurityConstraintsDescription copied from interface:RealmFind the SecurityConstraints configured to guard the request URI for this request.- Specified by:
- findSecurityConstraintsin interface- Realm
- Parameters:
- request- Request we are processing
- context- Context the Request is mapped to
- Returns:
- the configured SecurityConstraint, ornullif there is none
 
- 
hasResourcePermissionpublic boolean hasResourcePermission(Request request, Response response, SecurityConstraint[] constraints, Context context) throws IOException Description copied from interface:RealmPerform access control based on the specified authorization constraint.- Specified by:
- hasResourcePermissionin interface- Realm
- Parameters:
- request- Request we are processing
- response- Response we are creating
- constraints- Security constraint we are enforcing
- context- The Context to which client of this class is attached.
- Returns:
- trueif this constraint is satisfied and processing should continue, or- falseotherwise
- Throws:
- IOException- if an input/output error occurs
 
- 
hasRoleCheck if the specified Principal has the specified security role, within the context of this Realm.This method or hasRoleInternal(Principal, String)can be overridden by Realm implementations, but the default is adequate when an instance ofGenericPrincipalis used to represent authenticated Principals from this Realm.- Specified by:
- hasRolein interface- Realm
- Parameters:
- wrapper- wrapper context for evaluating role
- principal- Principal for whom the role is to be checked
- role- Security role to be checked
- Returns:
- trueif the specified Principal has the specified security role, within the context of this Realm; otherwise return- false.
 
- 
parseUserAttributesParse the specified delimiter separated attribute names and return a list of that names ornull, if no attributes have been specified.If a wildcard character is found, return a list consisting of a single wildcard character only. - Parameters:
- userAttributes- comma separated names of attributes to parse
- Returns:
- a list containing the parsed attribute names or null, if no attributes have been specified
 
- 
hasRoleInternalCheck if the specified Principal has the specified security role, within the context of this Realm. This method orhasRoleInternal(Principal, String)can be overridden by Realm implementations, but the default is adequate when an instance ofGenericPrincipalis used to represent authenticated Principals from this Realm.- Parameters:
- principal- Principal for whom the role is to be checked
- role- Security role to be checked
- Returns:
- trueif the specified Principal has the specified security role, within the context of this Realm; otherwise return- false.
 
- 
hasUserDataPermissionpublic boolean hasUserDataPermission(Request request, Response response, SecurityConstraint[] constraints) throws IOException Description copied from interface:RealmEnforce any user data constraint required by the security constraint guarding this request URI.- Specified by:
- hasUserDataPermissionin interface- Realm
- Parameters:
- request- Request we are processing
- response- Response we are creating
- constraints- Security constraint being checked
- Returns:
- trueif this constraint was not violated and processing should continue, or- falseif we have created a response already.
- Throws:
- IOException- if an input/output error occurs
 
- 
removePropertyChangeListenerDescription copied from interface:RealmRemove a property change listener from this component.- Specified by:
- removePropertyChangeListenerin interface- Realm
- Parameters:
- listener- The listener to remove
 
- 
initInternalDescription copied from class:LifecycleMBeanBaseSub-classes wishing to perform additional initialization should override this method, ensuring that super.initInternal() is the first call in the overriding method.- Overrides:
- initInternalin class- LifecycleMBeanBase
- Throws:
- LifecycleException- If the initialisation fails
 
- 
startInternalPrepare for the beginning of active use of the public methods of this component and implement the requirements ofLifecycleBase.startInternal().- Specified by:
- startInternalin class- LifecycleBase
- Throws:
- LifecycleException- if this component detects a fatal error that prevents this component from being used
 
- 
stopInternalGracefully terminate the active use of the public methods of this component and implement the requirements ofLifecycleBase.stopInternal().- Specified by:
- stopInternalin class- LifecycleBase
- Throws:
- LifecycleException- if this component detects a fatal error that needs to be reported
 
- 
toString
- 
hasMessageDigest
- 
getDigestDeprecated.Unused. UsegetDigest(String, String, String). Will be removed in Tomcat 11.Return the digest associated with given principal's user name.- Parameters:
- username- The user name
- realmName- The realm name
- Returns:
- the digest for the specified user
 
- 
getDigestReturn the digest associated with given principal's user name.- Parameters:
- username- The user name
- realmName- The realm name
- algorithm- The name of the message digest algorithm to use
- Returns:
- the digest for the specified user
 
- 
getPasswordGet the password for the specified user.- Parameters:
- username- The user name
- Returns:
- the password associated with the given principal's user name.
 
- 
getPrincipalGet the principal associated with the specified certificate.- Parameters:
- usercert- The user certificate
- Returns:
- the Principal associated with the given certificate.
 
- 
getPrincipalGet the principal associated with the specified user.- Parameters:
- username- The user name
- Returns:
- the Principal associated with the given user name.
 
- 
getPrincipalGet the principal associated with the specifiedGSSName.- Parameters:
- gssName- The GSS name
- gssCredential- the GSS credential of the principal
- Returns:
- the principal associated with the given user name.
 
- 
getServerReturn the Server object that is the ultimate parent for the container with which this Realm is associated. If the server cannot be found (eg because the container hierarchy is not complete),nullis returned.- Returns:
- the Server associated with the realm
 
- 
mainGenerate a stored credential string for the given password and associated parameters.The following parameters are supported: - -a - The algorithm to use to generate the stored credential. If not specified a default of SHA-512 will be used.
- -e - The encoding to use for any byte to/from character conversion that may be necessary. If not
 specified, the system encoding (Charset.defaultCharset()) will be used.
- -i - The number of iterations to use when generating the stored credential. If not specified, the default for the CredentialHandler will be used.
- -s - The length (in bytes) of salt to generate and store as part of the credential. If not specified, the default for the CredentialHandler will be used.
- -k - The length (in bits) of the key(s), if any, created while generating the credential. If not specified, the default for the CredentialHandler will be used.
- -h - The fully qualified class name of the CredentialHandler to use. If not specified, the built-in handlers will be tested in turn and the first one to accept the specified algorithm will be used.
- -f - The name of the file that contains passwords to encode. Each line in the file should contain only one password. Using this option ignores other password input.
 This generation process currently supports the following CredentialHandlers, the correct one being selected based on the algorithm specified: - Parameters:
- args- The parameters passed on the command line
- Throws:
- IOException- If an error occurs reading the password file
 
- 
getObjectNameKeyPropertiesDescription copied from class:LifecycleMBeanBaseAllow sub-classes to specify the key properties component of theObjectNamethat will be used to register this component.- Specified by:
- getObjectNameKeyPropertiesin class- LifecycleMBeanBase
- Returns:
- The string representation of the key properties component of the
          desired ObjectName
 
- 
getDomainInternalDescription copied from class:LifecycleMBeanBaseMethod implemented by sub-classes to identify the domain in which MBeans should be registered.- Specified by:
- getDomainInternalin class- LifecycleMBeanBase
- Returns:
- The name of the domain to use to register MBeans.
 
- 
getRealmPath
- 
setRealmPath
- 
getRealmSuffix
 
-