RealmBase (Apache Tomcat 9.0.37 API Documentation)

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, JmxEnabled, Lifecycle, Realm
  Direct Known Subclasses:
    AuthenticatedUserRealm, CombinedRealm, DataSourceRealm, JAASRealm, JDBCRealm, JNDIRealm, MemoryRealm, NullRealm, UserDatabaseRealm

      public abstract class RealmBase
      extends LifecycleMBeanBase
      implements Realm

  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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `RealmBase.AllRolesMode`

    - ### Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle

      `Lifecycle.SingleUse`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected RealmBase.AllRolesMode` | `allRolesMode` The all role mode.
    `protected Container` | `container` The Container with which this Realm is associated.
    `protected Log` | `containerLog` Container log
    `protected String` | `realmPath`
    `protected static StringManager` | `sm` The string manager for this package.
    `protected boolean` | `stripRealmForGss` When processing users authenticated via the GSS-API, should any "@...
    `protected PropertyChangeSupport` | `support` The property change support for this component.
    `protected boolean` | `validate` Should we validate client certificate chains when they are presented?
    `protected X509UsernameRetriever` | `x509UsernameRetriever` The object that will extract user names from X509 client certificates.
    `protected String` | `x509UsernameRetrieverClassName` The name of the class to use for retrieving user names from X509 certificates.

    - ### 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 and Description
    `RealmBase()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addPropertyChangeListener(PropertyChangeListener listener)` Add a property change listener to this component.
    `Principal` | `authenticate(GSSContext gssContext, boolean storeCred)` Try to authenticate using a `GSSContext`
    `Principal` | `authenticate(GSSName gssName, GSSCredential gssCredential)` Try to authenticate using a `GSSName` Note that this default method will be turned into an abstract one in Tomcat 10.
    `Principal` | `authenticate(String username)` Return the Principal associated with the specified username, if there is one; otherwise return `null`.
    `Principal` | `authenticate(String username, String credentials)` Return the Principal associated with the specified username and credentials, if there is one; otherwise return `null`.
    `Principal` | `authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realm, String md5a2)` 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).
    `Principal` | `authenticate(X509Certificate[] certs)` Return the Principal associated with the specified chain of X509 client certificates.
    `void` | `backgroundProcess()` Execute a periodic task, such as reloading, etc.
    `SecurityConstraint[]` | `findSecurityConstraints(Request request, Context context)` Return the SecurityConstraints configured to guard the request URI for this request, or `null` if there is no such constraint.
    `String` | `getAllRolesMode()` Return the all roles mode.
    `Container` | `getContainer()` Return the Container with which this Realm has been associated.
    `CredentialHandler` | `getCredentialHandler()`
    `protected String` | `getDigest(String username, String realmName)` Return the digest associated with given principal's user name.
    `String` | `getDomainInternal()` Method implemented by sub-classes to identify the domain in which MBeans should be registered.
    `String` | `getObjectNameKeyProperties()` Allow sub-classes to specify the key properties component of the `ObjectName` that will be used to register this component.
    `protected abstract String` | `getPassword(String username)` Get the password for the specified user.
    `protected Principal` | `getPrincipal(GSSName gssName, GSSCredential gssCredential)` Get the principal associated with the specified `GSSName`.
    `protected abstract Principal` | `getPrincipal(String username)` Get the principal associated with the specified user.
    `protected Principal` | `getPrincipal(String username, GSSCredential gssCredential)` Deprecated. This will be removed in Tomcat 10 onwards. Use `getPrincipal(GSSName, GSSCredential)` instead.
    `protected Principal` | `getPrincipal(X509Certificate usercert)` Get the principal associated with the specified certificate.
    `String` | `getRealmPath()`
    `protected String` | `getRealmSuffix()`
    `String[]` | `getRoles(Principal principal)` Return roles associated with given principal
    `protected Server` | `getServer()` Return the Server object that is the ultimate parent for the container with which this Realm is associated.
    `int` | `getTransportGuaranteeRedirectStatus()`
    `boolean` | `getValidate()` Return the "validate certificate chains" flag.
    `String` | `getX509UsernameRetrieverClassName()` Gets the name of the class that will be used to extract user names from X509 client certificates.
    `protected boolean` | `hasMessageDigest()`
    `boolean` | `hasResourcePermission(Request request, Response response, SecurityConstraint[] constraints, Context context)` Perform access control based on the specified authorization constraint.
    `boolean` | `hasRole(Wrapper wrapper, Principal principal, String role)` Check if the specified Principal has the specified security role, within the context of this Realm.
    `protected boolean` | `hasRoleInternal(Principal principal, String role)` Check if the specified Principal has the specified security role, within the context of this Realm.
    `boolean` | `hasUserDataPermission(Request request, Response response, SecurityConstraint[] constraints)` Enforce any user data constraint required by the security constraint guarding this request URI.
    `protected void` | `initInternal()` Sub-classes wishing to perform additional initialization should override this method, ensuring that super.initInternal() is the first call in the overriding method.
    `boolean` | `isStripRealmForGss()`
    `static void` | `main(String[] args)` Generate a stored credential string for the given password and associated parameters.
    `void` | `removePropertyChangeListener(PropertyChangeListener listener)` Remove a property change listener from this component.
    `void` | `setAllRolesMode(String allRolesMode)` Set the all roles mode.
    `void` | `setContainer(Container container)` Set the Container with which this Realm has been associated.
    `void` | `setCredentialHandler(CredentialHandler credentialHandler)` Set the CredentialHandler to be used by this Realm.
    `void` | `setRealmPath(String theRealmPath)`
    `void` | `setStripRealmForGss(boolean stripRealmForGss)`
    `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.
    `void` | `setValidate(boolean validate)` Set the "validate certificate chains" flag.
    `void` | `setX509UsernameRetrieverClassName(String className)` Sets the name of the class that will be used to extract user names from X509 client certificates.
    `protected void` | `startInternal()` Prepare for the beginning of active use of the public methods of this component and implement the requirements of `LifecycleBase.startInternal()`.
    `protected void` | `stopInternal()` Gracefully terminate the active use of the public methods of this component and implement the requirements of `LifecycleBase.stopInternal()`.
    `String` | `toString()` Return a String representation of this component.

    - ### 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`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface org.apache.catalina.Realm

      `isAvailable`

- - ### Field Detail

    - #### 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?

    - #### realmPath

          protected String realmPath

  - ### Constructor Detail

    - #### RealmBase

          public RealmBase()

  - ### Method Detail

    - #### 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()

      Return the Container with which this Realm has been 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)

      Set the Container with which this Realm has been associated.
      Specified by:
        `setContainer` in interface `Contained`
      Parameters:
        `container` - The associated 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:
        `X509UsernameRetriever`

    - #### isStripRealmForGss

          public boolean isStripRealmForGss()

    - #### setStripRealmForGss

          public void setStripRealmForGss(boolean stripRealmForGss)

    - #### addPropertyChangeListener

          public void addPropertyChangeListener(PropertyChangeListener listener)

      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)

      Return the Principal associated with the specified username, if there is one; otherwise return `null`.
      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)

      Return the Principal associated with the specified username and credentials, if there is one; otherwise return `null`.
      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

          public Principal authenticate(String username,
                                        String clientDigest,
                                        String nonce,
                                        String nc,
                                        String cnonce,
                                        String qop,
                                        String realm,
                                        String md5a2)

      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
        `md5a2` - Second MD5 digest used to calculate the digest : MD5(Method + ":" + uri)
      Returns:
        the associated principal, or `null` if there is none.

    - #### authenticate

          public Principal authenticate(X509Certificate[] certs)

      Return the Principal associated with the specified chain of X509 client certificates. If there is none, return `null`.
      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)

      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)

      Try to authenticate using a `GSSName` Note that this default method will be turned into an abstract one in Tomcat 10.
      Specified by:
        `authenticate` in interface `Realm`
      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.
      Specified by:
        `backgroundProcess` in interface `Realm`

    - #### findSecurityConstraints

          public SecurityConstraint[] findSecurityConstraints(Request request,
                                                              Context context)

      Return the SecurityConstraints configured to guard the request URI for this request, or `null` if there is no such constraint.
      Specified by:
        `findSecurityConstraints` in interface `Realm`
      Parameters:
        `request` - Request we are processing
        `context` - Context the Request is mapped to
      Returns:
        the configured `SecurityConstraint`, of `null` if there is none

    - #### hasResourcePermission

          public boolean hasResourcePermission(Request request,
                                               Response response,
                                               SecurityConstraint[] constraints,
                                               Context context)
                                        throws IOException

      Perform access control based on the specified authorization constraint. Return `true` if this constraint is satisfied and processing should continue, or `false` otherwise.
      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`.

    - #### 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

      Enforce any user data constraint required by the security constraint guarding this request URI. Return `true` if this constraint was not violated and processing should continue, or `false` if we have created a response already.
      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)

      Remove a property change listener from this component.
      Specified by:
        `removePropertyChangeListener` in interface `Realm`
      Parameters:
        `listener` - The listener to remove

    - #### 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()

      Return a String representation of this component.
      Overrides:
        `toString` in class `Object`

    - #### hasMessageDigest

          protected boolean hasMessageDigest()

    - #### getDigest

          protected String getDigest(String username,
                                     String realmName)

      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

    - #### 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

    - #### main

          public static void main(String[] args)

      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.

      This generation process currently supports the following CredentialHandlers, the correct one being selected based on the algorithm specified:

      - `MessageDigestCredentialHandler`
      - `SecretKeyCredentialHandler`
      Parameters:
        `args` - The parameters passed on the command line

    - #### 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

Copyright © 2000-2020 Apache Software Foundation. All Rights Reserved.