CombinedRealm (Apache Tomcat 10.1.57 API Documentation)
Description: declaration: package: org.apache.catalina.realm, class: CombinedRealm

# 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 usernames should be unique across all combined realms.

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from class RealmBase

  `RealmBase.AllRolesMode`

  ### Nested classes/interfaces inherited from interface Lifecycle

  `Lifecycle.SingleUse`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final List<Realm>`
  `realms`
  The list of Realms contained by this Realm.

  ### Fields inherited from class RealmBase

  `allRolesMode, container, containerLog, realmPath, sm, stripRealmForGss, support, USER_ATTRIBUTES_DELIMITER, USER_ATTRIBUTES_WILDCARD, userAttributes, userAttributesList, validate, x509UsernameRetriever, x509UsernameRetrieverClassName`

  ### Fields inherited from interface 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
  Description
  `CombinedRealm()`
  Default constructor for CombinedRealm.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addRealm(Realm theRealm)`
  Add a realm to the list of realms that will be used to authenticate users.
  `Principal`
  `authenticate(String username)`
  Try to authenticate with the specified username.
  `Principal`
  `authenticate(String username, String credentials)`
  Try to authenticate using the specified username and credentials.
  `Principal`
  `authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realmName, String digestA2, String algorithm)`
  Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 7616.
  `Principal`
  `authenticate(X509Certificate[] certs)`
  Try to authenticate using a chain of `X509Certificate`s.
  `Principal`
  `authenticate(GSSContext gssContext, boolean storeCred)`
  Try to authenticate using a `GSSContext`.
  `Principal`
  `authenticate(GSSName gssName, GSSCredential gssCredential)`
  Try to authenticate using a `GSSName`.
  `void`
  `backgroundProcess()`
  Delegate the backgroundProcess call to all sub-realms.
  `protected void`
  `destroyInternal()`
  Ensure child Realms are destroyed when this Realm is destroyed.
  `Realm[]`
  `getNestedRealms()`
  Returns the array of Realm instances contained by this realm.
  `protected String`
  `getPassword(String username)`
  Get the password for the specified user.
  `protected Principal`
  `getPrincipal(String username)`
  Get the principal associated with the specified user.
  `ObjectName[]`
  `getRealms()`
  Returns the JMX ObjectNames of the realms that this realm is wrapping.
  `boolean`
  `hasRole(Wrapper wrapper, Principal principal, String role)`
  Check if the specified Principal has the specified security role, within the context of this Realm.
  `boolean`
  `isAvailable()`
  Return the availability of the realm for authentication.
  `void`
  `setContainer(Container container)`
  Set the `Container` with which this instance is associated.
  `void`
  `setCredentialHandler(CredentialHandler credentialHandler)`
  Set the CredentialHandler to be used by this Realm.
  `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()`.

  ### Methods inherited from class RealmBase

  `addPropertyChangeListener, authenticate, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, getDigest, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getPrincipal, getPrincipal, getRealmPath, getRealmSuffix, getServer, getTransportGuaranteeRedirectStatus, getUserAttributes, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRoleInternal, hasUserDataPermission, initInternal, isStripRealmForGss, main, parseUserAttributes, removePropertyChangeListener, setAllRolesMode, setRealmPath, setStripRealmForGss, setTransportGuaranteeRedirectStatus, setUserAttributes, setValidate, setX509UsernameRetrieverClassName, toString`

  ### Methods inherited from class LifecycleMBeanBase

  `getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister, unregister`

  ### Methods inherited from class LifecycleBase

  `addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop`

  ### Methods inherited from class Object

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

- ## 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 theRealm)
    Add a realm to the list of realms that will be used to authenticate users.
    Parameters:
      `theRealm` - realm which should be wrapped by the combined realm

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

  - ### 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 `X509Certificate`s.
    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`.
    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