Package org.apache.catalina.ha.authenticator

## Class ClusterSingleSignOn

- java.lang.Object
- - org.apache.catalina.util.LifecycleBase
  - - org.apache.catalina.util.LifecycleMBeanBase
    - - org.apache.catalina.valves.ValveBase
      - - org.apache.catalina.authenticator.SingleSignOn
        - - org.apache.catalina.ha.authenticator.ClusterSingleSignOn

- All Implemented Interfaces:
    `MBeanRegistration`, `Contained`, `ClusterValve`, `JmxEnabled`, `Lifecycle`, `AbstractReplicatedMap.MapOwner`, `Valve`

      public class ClusterSingleSignOn
      extends SingleSignOn
      implements ClusterValve, AbstractReplicatedMap.MapOwner

  A Valve that supports a "single sign on" user experience on each nodes of a cluster, where the security identity of a user who successfully authenticates to one web application is propagated to other web applications and to other nodes cluster in the same security domain. For successful use, the following requirements must be met:
  - This Valve must be configured on the Container that represents a virtual host (typically an implementation of `Host`).
  - The `Realm` that contains the shared user and role information must be configured on the same Container (or a higher one), and not overridden at the web application level.
  - The web applications themselves must use one of the standard Authenticators found in the `org.apache.catalina.authenticator` package.
  Author:
    Fabien Carrion

- - ### Nested Class Summary

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

      `Lifecycle.SingleUse`

  - ### Field Summary

    - ### Fields inherited from class org.apache.catalina.authenticator.SingleSignOn

      `cache`

    - ### Fields inherited from class org.apache.catalina.valves.ValveBase

      `asyncSupported, container, containerLog, next`

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected boolean` | `associate​(String ssoId, Session session)` | Associate the specified single sign on identifier with the specified Session.
    `long` | `getAccessTimeout()` |
    `CatalinaCluster` | `getCluster()` | Returns the cluster the cluster deployer is associated with
    `int` | `getMapSendOptions()` |
    `long` | `getRpcTimeout()` |
    `protected SessionListener` | `getSessionListener​(String ssoId)` |
    `boolean` | `getTerminateOnStartFailure()` |
    `void` | `objectMadePrimary​(Object key, Object value)` |
    `void` | `setAccessTimeout​(long accessTimeout)` |
    `void` | `setCluster​(CatalinaCluster cluster)` | Associates the cluster deployer with a cluster
    `void` | `setMapSendOptions​(int mapSendOptions)` |
    `void` | `setRpcTimeout​(long rpcTimeout)` |
    `void` | `setTerminateOnStartFailure​(boolean terminateOnStartFailure)` |
    `protected void` | `startInternal()` | Start this component and implement the requirements of `LifecycleBase.startInternal()`.
    `protected void` | `stopInternal()` | Stop this component and implement the requirements of `LifecycleBase.stopInternal()`.
    `protected boolean` | `update​(String ssoId, Principal principal, String authType, String username, String password)` | Updates any `SingleSignOnEntry` found under key `ssoId` with the given authentication data.

    - ### Methods inherited from class org.apache.catalina.authenticator.SingleSignOn

      `deregister, getCookieDomain, getCookieName, getRequireReauthentication, invoke, reauthenticate, register, removeSession, sessionDestroyed, setCookieDomain, setCookieName, setRequireReauthentication`

    - ### Methods inherited from class org.apache.catalina.valves.ValveBase

      `backgroundProcess, getContainer, getDomainInternal, getNext, getObjectNameKeyProperties, initInternal, isAsyncSupported, setAsyncSupported, setContainer, setNext, toString`

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

      `backgroundProcess, getNext, invoke, isAsyncSupported, setNext`

- - ### Constructor Detail

    - #### ClusterSingleSignOn

          public ClusterSingleSignOn()

  - ### Method Detail

    - #### getCluster

          public CatalinaCluster getCluster()

      Description copied from interface: `ClusterValve`
      Returns the cluster the cluster deployer is associated with
      Specified by:
        `getCluster` in interface `ClusterValve`
      Returns:
        CatalinaCluster

    - #### setCluster

          public void setCluster​(CatalinaCluster cluster)

      Description copied from interface: `ClusterValve`
      Associates the cluster deployer with a cluster
      Specified by:
        `setCluster` in interface `ClusterValve`
      Parameters:
        `cluster` - CatalinaCluster

    - #### getRpcTimeout

          public long getRpcTimeout()

    - #### setRpcTimeout

          public void setRpcTimeout​(long rpcTimeout)

    - #### getMapSendOptions

          public int getMapSendOptions()

    - #### setMapSendOptions

          public void setMapSendOptions​(int mapSendOptions)

    - #### getTerminateOnStartFailure

          public boolean getTerminateOnStartFailure()

    - #### setTerminateOnStartFailure

          public void setTerminateOnStartFailure​(boolean terminateOnStartFailure)

    - #### getAccessTimeout

          public long getAccessTimeout()

    - #### setAccessTimeout

          public void setAccessTimeout​(long accessTimeout)

    - #### associate

          protected boolean associate​(String ssoId,
                                      Session session)

      Description copied from class: `SingleSignOn`
      Associate the specified single sign on identifier with the specified Session.
      Overrides:
        `associate` in class `SingleSignOn`
      Parameters:
        `ssoId` - Single sign on identifier
        `session` - Session to be associated
      Returns:
        `true` if the session was associated to the given SSO session, otherwise `false`

    - #### update

          protected boolean update​(String ssoId,
                                   Principal principal,
                                   String authType,
                                   String username,
                                   String password)

      Description copied from class: `SingleSignOn`
      Updates any `SingleSignOnEntry` found under key `ssoId` with the given authentication data.

      The purpose of this method is to allow an SSO entry that was established without a username/password combination (i.e. established following DIGEST or CLIENT_CERT authentication) to be updated with a username and password if one becomes available through a subsequent BASIC or FORM authentication. The SSO entry will then be usable for reauthentication.

      NOTE: Only updates the SSO entry if a call to `SingleSignOnEntry.getCanReauthenticate()` returns `false`; otherwise, it is assumed that the SSO entry already has sufficient information to allow reauthentication and that no update is needed.

      Overrides:
        `update` in class `SingleSignOn`
      Parameters:
        `ssoId` - identifier of Single sign to be updated
        `principal` - the `Principal` returned by the latest call to `Realm.authenticate`.
        `authType` - the type of authenticator used (BASIC, CLIENT_CERT, DIGEST or FORM)
        `username` - the username (if any) used for the authentication
        `password` - the password (if any) used for the authentication
      Returns:
        `true` if the credentials were updated, otherwise `false`

    - #### getSessionListener

          protected SessionListener getSessionListener​(String ssoId)

      Overrides:
        `getSessionListener` in class `SingleSignOn`

    - #### objectMadePrimary

          public void objectMadePrimary​(Object key,
                                        Object value)

      Specified by:
        `objectMadePrimary` in interface `AbstractReplicatedMap.MapOwner`

    - #### startInternal

          protected void startInternal()
                                throws LifecycleException

      Start this component and implement the requirements of `LifecycleBase.startInternal()`.
      Overrides:
        `startInternal` in class `SingleSignOn`
      Throws:
        `LifecycleException` - if this component detects a fatal error that prevents this component from being used

    - #### stopInternal

          protected void stopInternal()
                               throws LifecycleException

      Stop this component and implement the requirements of `LifecycleBase.stopInternal()`.
      Overrides:
        `stopInternal` in class `SingleSignOn`
      Throws:
        `LifecycleException` - if this component detects a fatal error that prevents this component from being used