CombinedRealm (Apache Tomcat 8.5.83 API Documentation)

Package org.apache.catalina.realm

## 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:
    `javax.management.MBeanRegistration`, `Contained`, `GSSRealm`, `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 org.apache.catalina.realm.RealmBase

      `RealmBase.AllRolesMode`

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

      `Lifecycle.SingleUse`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected static java.lang.String` | `name` | Deprecated. This will be removed in Tomcat 9 onwards.
    `protected java.util.List<Realm>` | `realms` | The list of Realms contained by this Realm.

    - ### Fields inherited from class org.apache.catalina.realm.RealmBase

      `allRolesMode, container, containerLog, realmPath, sm, stripRealmForGss, support, validate, x509UsernameRetriever, x509UsernameRetrieverClassName`

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addRealm​(Realm theRealm)` | Add a realm to the list of realms that will be used to authenticate users.
    `java.security.Principal` | `authenticate​(java.lang.String username)` | Return the Principal associated with the specified user name otherwise return `null`.
    `java.security.Principal` | `authenticate​(java.lang.String username, java.lang.String credentials)` | Return the Principal associated with the specified username and credentials, if there is one; otherwise return `null`.
    `java.security.Principal` | `authenticate​(java.lang.String username, java.lang.String clientDigest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realmName, java.lang.String md5a2)` | Return the Principal associated with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2069; otherwise return `null`.
    `java.security.Principal` | `authenticate​(java.security.cert.X509Certificate[] certs)` | Return the Principal associated with the specified chain of X509 client certificates.
    `java.security.Principal` | `authenticate​(org.ietf.jgss.GSSContext gssContext, boolean storeCred)` | Try to authenticate using a `GSSContext`
    `java.security.Principal` | `authenticate​(org.ietf.jgss.GSSName gssName, org.ietf.jgss.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.
    `protected java.lang.String` | `getName()` | Deprecated.
    `Realm[]` | `getNestedRealms()` |
    `protected java.lang.String` | `getPassword​(java.lang.String username)` | Get the password for the specified user.
    `protected java.security.Principal` | `getPrincipal​(java.lang.String username)` | Get the principal associated with the specified user.
    `javax.management.ObjectName[]` | `getRealms()` |
    `boolean` | `hasRole​(Wrapper wrapper, java.security.Principal principal, java.lang.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 Realm has been 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 org.apache.catalina.realm.RealmBase

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

    - ### Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase

      `getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, 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`

- - ### Field Detail

    - #### realms

          protected final java.util.List<Realm> realms

      The list of Realms contained by this Realm.

    - #### name

          @Deprecated
          protected static final java.lang.String name

      Deprecated.
      This will be removed in Tomcat 9 onwards.
      Descriptive information about this Realm implementation.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### CombinedRealm

          public CombinedRealm()

  - ### Method Detail

    - #### 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 javax.management.ObjectName[] getRealms()

      Returns:
        the set of Realms that this Realm is wrapping

    - #### getNestedRealms

          public Realm[] getNestedRealms()

      Returns:
        the list of Realms contained by this Realm.

    - #### authenticate

          public java.security.Principal authenticate​(java.lang.String username,
                                                      java.lang.String clientDigest,
                                                      java.lang.String nonce,
                                                      java.lang.String nc,
                                                      java.lang.String cnonce,
                                                      java.lang.String qop,
                                                      java.lang.String realmName,
                                                      java.lang.String md5a2)

      Return the Principal associated with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2069; otherwise return `null`.
      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
        `realmName` - Realm name
        `md5a2` - Second MD5 digest used to calculate the digest : MD5(Method + ":" + uri)
        `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`).
      Returns:
        the associated principal, or `null` if there is none.

    - #### authenticate

          public java.security.Principal authenticate​(java.lang.String username)

      Return the Principal associated with the specified user name otherwise return `null`.
      Specified by:
        `authenticate` in interface `Realm`
      Overrides:
        `authenticate` in class `RealmBase`
      Parameters:
        `username` - User name of the Principal to look up
      Returns:
        the associated principal, or `null` if none is associated.

    - #### authenticate

          public java.security.Principal authenticate​(java.lang.String username,
                                                      java.lang.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`
      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)

      Set the Container with which this Realm has been associated.
      Specified by:
        `setContainer` in interface `Contained`
      Overrides:
        `setContainer` in class `RealmBase`
      Parameters:
        `container` - The associated Container

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

      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 java.security.Principal authenticate​(java.security.cert.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`
      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 java.security.Principal authenticate​(org.ietf.jgss.GSSContext gssContext,
                                                      boolean storeCred)

      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 java.security.Principal authenticate​(org.ietf.jgss.GSSName gssName,
                                                      org.ietf.jgss.GSSCredential gssCredential)

      Try to authenticate using a `GSSName`
      Specified by:
        `authenticate` in interface `GSSRealm`
      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,
                                 java.security.Principal principal,
                                 java.lang.String role)

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

    - #### getName

          @Deprecated
          protected java.lang.String getName()

      Deprecated.
      Specified by:
        `getName` in class `RealmBase`
      Returns:
        a short name for this Realm implementation, for use in log messages.

    - #### getPassword

          protected java.lang.String getPassword​(java.lang.String username)

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

    - #### getPrincipal

          protected java.security.Principal getPrincipal​(java.lang.String username)

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

    - #### isAvailable

          public boolean isAvailable()

      Description copied from interface: `Realm`
      Return the availability of the realm for authentication.
      Specified by:
        `isAvailable` in interface `Realm`
      Overrides:
        `isAvailable` in class `RealmBase`
      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