ClusterSingleSignOn (Apache Tomcat 10.1.57 API Documentation)
Description: declaration: package: org.apache.catalina.ha.authenticator, class: ClusterSingleSignOn

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

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from interface Lifecycle

  `Lifecycle.SingleUse`

- ## Field Summary

  ### Fields inherited from class SingleSignOn

  `cache`

  ### Fields inherited from class ValveBase

  `asyncSupported, container, containerLog, next`

  ### 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
  `ClusterSingleSignOn()`
  Default constructor for ClusterSingleSignOn.

- ## Method Summary

  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()`
  Returns the access timeout in milliseconds.
  `CatalinaCluster`
  `getCluster()`
  Returns the cluster the valve is associated with
  `int`
  `getMapSendOptions()`
  Returns the map send options.
  `long`
  `getRpcTimeout()`
  Returns the RPC timeout in milliseconds.
  `protected SessionListener`
  `getSessionListener(String ssoId)`
  Returns a session listener for the specified SSO identifier.
  `boolean`
  `getTerminateOnStartFailure()`
  Returns whether to terminate on start failure.
  `void`
  `objectMadePrimary(Object key, Object value)`
  Called when an object becomes primary on this node.
  `void`
  `setAccessTimeout(long accessTimeout)`
  Sets the access timeout in milliseconds.
  `void`
  `setCluster(CatalinaCluster cluster)`
  Associates the cluster valve with a cluster
  `void`
  `setMapSendOptions(int mapSendOptions)`
  Sets the map send options.
  `void`
  `setRpcTimeout(long rpcTimeout)`
  Sets the RPC timeout in milliseconds.
  `void`
  `setTerminateOnStartFailure(boolean terminateOnStartFailure)`
  Sets whether to terminate on start failure.
  `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 SingleSignOn

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

  ### Methods inherited from class ValveBase

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

  ### Methods inherited from class LifecycleMBeanBase

  `destroyInternal, 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`

  ### Methods inherited from interface Valve

  `backgroundProcess, getNext, invoke, isAsyncSupported, setNext`

- ## Constructor Details

  - ### ClusterSingleSignOn

    public ClusterSingleSignOn()
    Default constructor for ClusterSingleSignOn.

- ## Method Details

  - ### getCluster

    public CatalinaCluster getCluster()
    Description copied from interface: `ClusterValve`
    Returns the cluster the valve 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 valve with a cluster
    Specified by:
      `setCluster` in interface `ClusterValve`
    Parameters:
      `cluster` - CatalinaCluster

  - ### getRpcTimeout

    public long getRpcTimeout()
    Returns the RPC timeout in milliseconds.
    Returns:
      the RPC timeout

  - ### setRpcTimeout

    public void setRpcTimeout(long rpcTimeout)
    Sets the RPC timeout in milliseconds.
    Parameters:
      `rpcTimeout` - the RPC timeout

  - ### getMapSendOptions

    public int getMapSendOptions()
    Returns the map send options.
    Returns:
      the map send options

  - ### setMapSendOptions

    public void setMapSendOptions(int mapSendOptions)
    Sets the map send options.
    Parameters:
      `mapSendOptions` - the map send options

  - ### getTerminateOnStartFailure

    public boolean getTerminateOnStartFailure()
    Returns whether to terminate on start failure.
    Returns:
      `true` if termination on start failure is enabled

  - ### setTerminateOnStartFailure

    public void setTerminateOnStartFailure(boolean terminateOnStartFailure)
    Sets whether to terminate on start failure.
    Parameters:
      `terminateOnStartFailure` - the new value

  - ### getAccessTimeout

    public long getAccessTimeout()
    Returns the access timeout in milliseconds.
    Returns:
      the access timeout

  - ### setAccessTimeout

    public void setAccessTimeout(long accessTimeout)
    Sets the access timeout in milliseconds.
    Parameters:
      `accessTimeout` - the access timeout

  - ### 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)
    Description copied from class: `SingleSignOn`
    Returns a session listener for the specified SSO identifier.
    Overrides:
      `getSessionListener` in class `SingleSignOn`
    Parameters:
      `ssoId` - the SSO identifier
    Returns:
      the session listener

  - ### objectMadePrimary

    public void objectMadePrimary(Object key, Object value)
    Description copied from interface: `AbstractReplicatedMap.MapOwner`
    Called when an object becomes primary on this node.
    Specified by:
      `objectMadePrimary` in interface `AbstractReplicatedMap.MapOwner`
    Parameters:
      `key` - The key of the object
      `value` - The value of the object

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