Package org.apache.catalina.realm

Class RealmBase

java.lang.Object
org.apache.catalina.util.LifecycleBase
org.apache.catalina.util.LifecycleMBeanBase
org.apache.catalina.realm.RealmBase
All Implemented Interfaces:
MBeanRegistration, Contained, GSSRealm, JmxEnabled, Lifecycle, Realm
Direct Known Subclasses:
CombinedRealm, DataSourceRealm, JAASRealm, JDBCRealm, JNDIRealm, MemoryRealm, NullRealm, UserDatabaseRealm
public abstract class RealmBase extends LifecycleMBeanBase implements GSSRealm
Simple implementation of Realm that reads an XML file to configure the valid users, passwords, and roles. The file format (and default file location) are identical to those currently supported by Tomcat 3.X.
Author:
Craig R. McClanahan

  • Field Details

    • USER_ATTRIBUTES_DELIMITER

      protected static final String USER_ATTRIBUTES_DELIMITER
      The character used for delimiting user attribute names.

      Applies to some of the Realm implementations only.

      See Also:

    • USER_ATTRIBUTES_WILDCARD

      protected static final String USER_ATTRIBUTES_WILDCARD
      The 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:

    • container

      protected Container container
      The Container with which this Realm is associated.

    • containerLog

      protected Log containerLog
      Container log

    • sm

      protected static final StringManager sm
      The string manager for this package.

    • support

      protected final PropertyChangeSupport support
      The property change support for this component.

    • validate

      protected boolean validate
      Should we validate client certificate chains when they are presented?

    • x509UsernameRetrieverClassName

      protected String x509UsernameRetrieverClassName
      The name of the class to use for retrieving user names from X509 certificates.

    • x509UsernameRetriever

      protected X509UsernameRetriever x509UsernameRetriever
      The object that will extract user names from X509 client certificates.

    • allRolesMode

      protected RealmBase.AllRolesMode allRolesMode
      The all role mode.

    • stripRealmForGss

      protected boolean stripRealmForGss
      When processing users authenticated via the GSS-API, should any "@..." be stripped from the end of the user name?

    • userAttributes

      protected String userAttributes
      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. Support for this feature is optional.

    • userAttributesList

      protected List<String> userAttributesList
      The 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

      protected String realmPath

  • Constructor Details

    • RealmBase

      public RealmBase()

  • Method Details

    • getTransportGuaranteeRedirectStatus

      public 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.

    • setTransportGuaranteeRedirectStatus

      public 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

      public CredentialHandler getCredentialHandler()
      Specified by:
      getCredentialHandler in interface Realm
      Returns:
      the CredentialHandler configured for this Realm.

    • setCredentialHandler

      public void setCredentialHandler(CredentialHandler credentialHandler)
      Description copied from interface: Realm
      Set the CredentialHandler to be used by this Realm.
      Specified by:
      setCredentialHandler in interface Realm
      Parameters:
      credentialHandler - the CredentialHandler to use

    • getContainer

      public Container getContainer()
      Description copied from interface: Contained
      Get the Container with which this instance is associated.
      Specified by:
      getContainer in interface Contained
      Returns:
      The Container with which this instance is associated or null if not associated with a Container

    • setContainer

      public void setContainer(Container container)
      Description copied from interface: Contained
      Set the Container with which this instance is associated.
      Specified by:
      setContainer in interface Contained
      Parameters:
      container - The Container instance with which this instance is to be associated, or null to disassociate this instance from any Container

    • getAllRolesMode

      public String getAllRolesMode()
      Return the all roles mode.
      Returns:
      A string representation of the current all roles mode

    • setAllRolesMode

      public void setAllRolesMode(String allRolesMode)
      Set the all roles mode.
      Parameters:
      allRolesMode - A string representation of the new all roles mode

    • getValidate

      public boolean getValidate()
      Return the "validate certificate chains" flag.
      Returns:
      The value of the validate certificate chains flag

    • setValidate

      public void setValidate(boolean validate)
      Set the "validate certificate chains" flag.
      Parameters:
      validate - The new validate certificate chains flag

    • getX509UsernameRetrieverClassName

      public String getX509UsernameRetrieverClassName()
      Gets 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.

    • setX509UsernameRetrieverClassName

      public void setX509UsernameRetrieverClassName(String className)
      Sets 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:

    • isStripRealmForGss

      public boolean isStripRealmForGss()

    • setStripRealmForGss

      public void setStripRealmForGss(boolean stripRealmForGss)

    • getUserAttributes

      public String getUserAttributes()
      Returns:
      the comma separated names of user attributes to additionally query from realm

    • setUserAttributes

      public void setUserAttributes(String userAttributes)
      Set 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 constant USER_ATTRIBUTES_WILDCARD. It defaults to the asterisk (*) character.

      Parameters:
      userAttributes - the comma separated names of user attributes

    • addPropertyChangeListener

      public void addPropertyChangeListener(PropertyChangeListener listener)
      Description copied from interface: Realm
      Add a property change listener to this component.
      Specified by:
      addPropertyChangeListener in interface Realm
      Parameters:
      listener - The listener to add

    • authenticate

      public Principal authenticate(String username)
      Description copied from interface: Realm
      Try to authenticate with the specified username.
      Specified by:
      authenticate in interface Realm
      Parameters:
      username - Username of the Principal to look up
      Returns:
      the associated principal, or null if none is associated.

    • authenticate

      public Principal authenticate(String username, String credentials)
      Description copied from interface: Realm
      Try to authenticate using the specified username and credentials.
      Specified by:
      authenticate in 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 null if 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: Realm
      Try 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:
      authenticate in 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" (nc and cnonce will only be used, if qop is not null).
      realm - Realm name
      digestA2 - Second digest calculated as digest(Method + ":" + uri)
      Returns:
      the associated principal, or null if there is none.

    • authenticate

      public Principal authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realm, String digestA2, String algorithm)
      Description copied from interface: Realm
      Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 7616.
      Specified by:
      authenticate in 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" (nc and cnonce will only be used, if qop is 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 null if there is none.

    • authenticate

      public Principal authenticate(X509Certificate[] certs)
      Description copied from interface: Realm
      Try to authenticate using a chain of X509Certificates.
      Specified by:
      authenticate in 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 null if there is none

    • authenticate

      public Principal authenticate(GSSContext gssContext, boolean storeCred)
      Description copied from interface: Realm
      Try to authenticate using a GSSContext.
      Specified by:
      authenticate in 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 null if there is none

    • authenticate

      public Principal authenticate(GSSName gssName, GSSCredential gssCredential)
      Description copied from interface: GSSRealm
      Try to authenticate using a GSSName
      Specified by:
      authenticate in interface GSSRealm
      Parameters:
      gssName - The GSSName of the principal to look up
      gssCredential - The GSSCredential of the principal, may be null
      Returns:
      the associated principal, or null if there is none

    • backgroundProcess

      public 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:
      backgroundProcess in interface Realm

    • findSecurityConstraints

      public SecurityConstraint[] findSecurityConstraints(Request request, Context context)
      Description copied from interface: Realm
      Find the SecurityConstraints configured to guard the request URI for this request.
      Specified by:
      findSecurityConstraints in interface Realm
      Parameters:
      request - Request we are processing
      context - Context the Request is mapped to
      Returns:
      the configured SecurityConstraint, or null if there is none

    • hasResourcePermission

      public boolean hasResourcePermission(Request request, Response response, SecurityConstraint[] constraints, Context context) throws IOException
      Description copied from interface: Realm
      Perform access control based on the specified authorization constraint.
      Specified by:
      hasResourcePermission in 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:
      true if this constraint is satisfied and processing should continue, or false otherwise
      Throws:
      IOException - if an input/output error occurs

    • hasRole

      public boolean hasRole(Wrapper wrapper, Principal principal, String role)
      Check 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 of GenericPrincipal is used to represent authenticated Principals from this Realm.

      Specified by:
      hasRole in 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:
      true if the specified Principal has the specified security role, within the context of this Realm; otherwise return false.

    • parseUserAttributes

      protected List<String> parseUserAttributes(String userAttributes)
      Parse the specified delimiter separated attribute names and return a list of that names or null, 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

    • hasRoleInternal

      protected boolean hasRoleInternal(Principal principal, String role)
      Check 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 of GenericPrincipal is 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:
      true if the specified Principal has the specified security role, within the context of this Realm; otherwise return false.

    • hasUserDataPermission

      public boolean hasUserDataPermission(Request request, Response response, SecurityConstraint[] constraints) throws IOException
      Description copied from interface: Realm
      Enforce any user data constraint required by the security constraint guarding this request URI.
      Specified by:
      hasUserDataPermission in interface Realm
      Parameters:
      request - Request we are processing
      response - Response we are creating
      constraints - Security constraint being checked
      Returns:
      true if this constraint was not violated and processing should continue, or false if we have created a response already.
      Throws:
      IOException - if an input/output error occurs

    • removePropertyChangeListener

      public void removePropertyChangeListener(PropertyChangeListener listener)
      Description copied from interface: Realm
      Remove a property change listener from this component.
      Specified by:
      removePropertyChangeListener in interface Realm
      Parameters:
      listener - The listener to remove

    • isAvailable

      public boolean isAvailable()
      Description copied from interface: Realm
      Return the availability of the realm for authentication.
      Specified by:
      isAvailable in interface Realm
      Returns:
      true if the realm is able to perform authentication

    • initInternal

      protected void initInternal() throws LifecycleException
      Description copied from class: LifecycleMBeanBase
      Sub-classes wishing to perform additional initialization should override this method, ensuring that super.initInternal() is the first call in the overriding method.
      Overrides:
      initInternal in class LifecycleMBeanBase
      Throws:
      LifecycleException - If the initialisation fails

    • startInternal

      protected void startInternal() throws LifecycleException
      Prepare for the beginning of active use of the public methods of this component and implement the requirements of LifecycleBase.startInternal().
      Specified by:
      startInternal in class LifecycleBase
      Throws:
      LifecycleException - if this component detects a fatal error that prevents this component from being used

    • stopInternal

      protected void stopInternal() throws LifecycleException
      Gracefully terminate the active use of the public methods of this component and implement the requirements of LifecycleBase.stopInternal().
      Specified by:
      stopInternal in class LifecycleBase
      Throws:
      LifecycleException - if this component detects a fatal error that needs to be reported

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • hasMessageDigest

      protected boolean hasMessageDigest(String algorithm)

    • getDigest

      @Deprecated protected String getDigest(String username, String realmName)
      Deprecated.
      Unused. Use getDigest(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

    • getDigest

      protected String getDigest(String username, String realmName, String algorithm)
      Return 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

    • getName

      @Deprecated protected abstract String getName()
      Deprecated.
      This will be removed in Tomcat 9 onwards. Use Class.getSimpleName() instead.
      Returns:
      a short name for this Realm implementation, for use in log messages.

    • getPassword

      protected abstract String getPassword(String username)
      Get the password for the specified user.
      Parameters:
      username - The user name
      Returns:
      the password associated with the given principal's user name.

    • getPrincipal

      protected Principal getPrincipal(X509Certificate usercert)
      Get the principal associated with the specified certificate.
      Parameters:
      usercert - The user certificate
      Returns:
      the Principal associated with the given certificate.

    • getPrincipal

      protected abstract Principal getPrincipal(String username)
      Get the principal associated with the specified user.
      Parameters:
      username - The user name
      Returns:
      the Principal associated with the given user name.

    • getPrincipal

      @Deprecated protected Principal getPrincipal(String username, GSSCredential gssCredential)
      Deprecated.
      This will be removed in Tomcat 10 onwards. Use getPrincipal(GSSName, GSSCredential) instead.
      Get the principal associated with the specified user name.
      Parameters:
      username - The user name
      gssCredential - the GSS credential of the principal
      Returns:
      the principal associated with the given user name.

    • getPrincipal

      protected Principal getPrincipal(GSSName gssName, GSSCredential gssCredential)
      Get the principal associated with the specified GSSName.
      Parameters:
      gssName - The GSS name
      gssCredential - the GSS credential of the principal
      Returns:
      the principal associated with the given user name.

    • getServer

      protected Server getServer()
      Return 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), null is returned.
      Returns:
      the Server associated with the realm

    • Digest

      @Deprecated public static final String Digest(String credentials, String algorithm, String encoding)
      Deprecated.
      Unused. This will be removed in Tomcat 9.
      Digest password using the algorithm specified and convert the result to a corresponding hex string.
      Parameters:
      credentials - Password or other credentials to use in authenticating this username
      algorithm - Algorithm used to do the digest
      encoding - Character encoding of the string to digest
      Returns:
      The digested credentials as a hex string or the original plain text credentials if an error occurs.

    • main

      public static void main(String[] args) throws IOException
      Generate 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

    • getObjectNameKeyProperties

      public String getObjectNameKeyProperties()
      Description copied from class: LifecycleMBeanBase
      Allow sub-classes to specify the key properties component of the ObjectName that will be used to register this component.
      Specified by:
      getObjectNameKeyProperties in class LifecycleMBeanBase
      Returns:
      The string representation of the key properties component of the desired ObjectName

    • getDomainInternal

      public String getDomainInternal()
      Description copied from class: LifecycleMBeanBase
      Method implemented by sub-classes to identify the domain in which MBeans should be registered.
      Specified by:
      getDomainInternal in class LifecycleMBeanBase
      Returns:
      The name of the domain to use to register MBeans.

    • getRealmPath

      public String getRealmPath()

    • setRealmPath

      public void setRealmPath(String theRealmPath)

    • getRealmSuffix

      protected String getRealmSuffix()

    • getRoles

      public String[] getRoles(Principal principal)
      Description copied from interface: Realm
      Return roles associated with given principal
      Specified by:
      getRoles in interface Realm
      Parameters:
      principal - the Principal to get the roles for.
      Returns:
      principal roles