Class CombinedRealm

java.lang.Object
org.apache.catalina.util.LifecycleBase
org.apache.catalina.util.LifecycleMBeanBase
org.apache.catalina.realm.RealmBase
org.apache.catalina.realm.CombinedRealm
All Implemented Interfaces:
MBeanRegistration, Contained, JmxEnabled, Lifecycle, Realm
Direct Known Subclasses:
LockOutRealm
public class CombinedRealm extends RealmBase
Realm implementation that contains one or more realms. Authentication is attempted for each realm in the order they were configured. If any realm authenticates the user then the authentication succeeds. When combining realms user names should be unique across all combined realms.

For the typical usage (create realms, add realms to container, start container), each realm will be registered with JMX and RealmBase.getRealmPath() will match the JMX object name. For simple changes (remove a realm, add a new realm) RealmBase.getRealmPath() and the JMX object name will remain synchronized. For more unusual changes such as moving the realm to a new container, the JMX object names and RealmBase.getRealmPath() are very likely to end up out of sync. If there are naming conflicts it is possible for realms that are still in use to not be registered in JMX.

  • Field Details

    • realms

      protected final List<Realm> realms
      The list of Realms contained by this Realm.

  • Constructor Details

    • CombinedRealm

      public CombinedRealm()
      Default constructor for CombinedRealm.

  • Method Details

    • addRealm

      public void addRealm(Realm realm)
      Add a realm to the list of realms that will be used to authenticate users.
      Parameters:
      realm - Realm which should be added to the combined realm

    • removeRealm

      public boolean removeRealm(Realm realm)
      Remove a realm from the list of realms that are used to authenticate users.
      Parameters:
      realm - Realm which should be removed from the combined realm
      Returns:
      true if the realm was present and removed, false otherwise

    • getRealms

      public ObjectName[] getRealms()
      Returns the JMX ObjectNames of the realms that this realm is wrapping. Entries for realms that do not implement LifecycleMBeanBase will be null.
      Returns:
      the array of realm ObjectNames, which may contain null entries

    • getNestedRealms

      public Realm[] getNestedRealms()
      Returns the array of Realm instances contained by this realm.
      Returns:
      the array of nested realms

    • 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: Realm
      Try 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:
      authenticate in interface Realm
      Overrides:
      authenticate in class RealmBase
      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).
      realmName - 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(String username)
      Description copied from interface: Realm
      Try to authenticate with the specified username.
      Specified by:
      authenticate in interface Realm
      Overrides:
      authenticate in class RealmBase
      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
      Overrides:
      authenticate in class RealmBase
      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

    • 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
      Overrides:
      setContainer in class RealmBase
      Parameters:
      container - The Container instance with which this instance is to be associated, or null to disassociate this instance from any Container

    • setRealmPath

      public void setRealmPath(String theRealmPath)
      Set the path used in the JMX object name for this realm.

      Calling this method will also (re)set the paths for all of the nested realms. If a nested realm has been removed this will result in the remaining nested realms being re-numbered which may create an inconsistency between the nested realm's path and its JMX registration (if any).

      Overrides:
      setRealmPath in class RealmBase
      Parameters:
      theRealmPath - The realm path to use

    • startInternal

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

    • stopInternal

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

    • destroyInternal

      protected void destroyInternal() throws LifecycleException
      Ensure child Realms are destroyed when this Realm is destroyed.
      Overrides:
      destroyInternal in class LifecycleMBeanBase
      Throws:
      LifecycleException - If the destruction fails

    • backgroundProcess

      public void backgroundProcess()
      Delegate the backgroundProcess call to all sub-realms.
      Specified by:
      backgroundProcess in interface Realm
      Overrides:
      backgroundProcess in class RealmBase

    • 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
      Overrides:
      authenticate in class RealmBase
      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
      Overrides:
      authenticate in class RealmBase
      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: Realm
      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
      Overrides:
      authenticate in class RealmBase
      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

    • hasRole

      public boolean hasRole(Wrapper wrapper, Principal principal, String role)
      Description copied from class: RealmBase
      Check if the specified Principal has the specified security role, within the context of this Realm.

      This method or RealmBase.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
      Overrides:
      hasRole in class RealmBase
      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.

    • getPassword

      protected String getPassword(String username)
      Description copied from class: RealmBase
      Get the password for the specified user.
      Specified by:
      getPassword in class RealmBase
      Parameters:
      username - The username
      Returns:
      the password associated with the given principal's username.

    • getPrincipal

      protected Principal getPrincipal(String username)
      Description copied from class: RealmBase
      Get the principal associated with the specified user.
      Specified by:
      getPrincipal in class RealmBase
      Parameters:
      username - The username
      Returns:
      the Principal associated with the given username.

    • isAvailable

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

    • 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
      Overrides:
      setCredentialHandler in class RealmBase
      Parameters:
      credentialHandler - the CredentialHandler to use