## org.apache.catalina.authenticator
Class SingleSignOn

    java.lang.Object
      org.apache.catalina.valves.ValveBase
          org.apache.catalina.authenticator.SingleSignOn

All Implemented Interfaces:
  Contained, Lifecycle, SessionListener, Valve

public class SingleSignOn
extends ValveBase
implements Lifecycle, SessionListener

A Valve that supports a "single sign on" user experience, where the security identity of a user who successfully authenticates to one web application is propogated to other web applications 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.

Version:
  $Revision: 1.15 $ $Date: 2004/08/26 21:27:39 $
Author:
  Craig R. McClanahan

Field Summary
`protected java.util.HashMap` `cache` The cache of SingleSignOnEntry instances for authenticated Principals, keyed by the cookie value that is used to select them.
`protected int` `debug` The debugging detail level for this component.
`protected static java.lang.String` `info` Descriptive information about this Valve implementation.
`protected LifecycleSupport` `lifecycle` The lifecycle event support for this component.
`protected java.util.HashMap` `reverse` The cache of single sign on identifiers, keyed by the Session that is associated with them.
`protected static StringManager` `sm` The string manager for this package.
`protected boolean` `started` Component started flag.

Fields inherited from class org.apache.catalina.valves.ValveBase
`container`

Fields inherited from interface org.apache.catalina.Lifecycle
`AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, START_EVENT, STOP_EVENT`

Constructor Summary
`SingleSignOn()`

Method Summary
`void` `addLifecycleListener(LifecycleListener listener)` Add a lifecycle event listener to this component.
`LifecycleListener[]` `findLifecycleListeners()` Get the lifecycle listeners associated with this lifecycle.
`int` `getDebug()` Return the debugging detail level.
`java.lang.String` `getInfo()` Return descriptive information about this Valve implementation.
`boolean` `getRequireReauthentication()` Gets whether each request needs to be reauthenticated (by an Authenticator downstream in the pipeline) to the security `Realm`, or if this Valve can itself bind security info to the request based on the presence of a valid SSO entry without rechecking with the `Realm</code..</TD>`
`void` `invoke(Request request, Response response, ValveContext context)` Perform single-sign-on support processing for this request.
`protected void` `log(java.lang.String message)` Log a message on the Logger associated with our Container (if any).
`protected void` `log(java.lang.String message, java.lang.Throwable throwable)` Log a message on the Logger associated with our Container (if any).
`protected org.apache.catalina.authenticator.SingleSignOnEntry` `lookup(java.lang.String ssoId)` Look up and return the cached SingleSignOn entry associated with this sso id value, if there is one; otherwise return `null`.
`void` `removeLifecycleListener(LifecycleListener listener)` Remove a lifecycle event listener from this component.
`void` `sessionEvent(SessionEvent event)` Acknowledge the occurrence of the specified event.
`void` `setDebug(int debug)` Set the debugging detail level.
`void` `setRequireReauthentication(boolean required)` Sets whether each request needs to be reauthenticated (by an Authenticator downstream in the pipeline) to the security `Realm`, or if this Valve can itself bind security info to the request, based on the presence of a valid SSO entry, without rechecking with the `Realm</code.</TD>`
`void` `start()` Prepare for the beginning of active use of the public methods of this component.
`void` `stop()` Gracefully terminate the active use of the public methods of this component.
`java.lang.String` `toString()` Return a String rendering of this object.

Methods inherited from class org.apache.catalina.valves.ValveBase
`getContainer, setContainer`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### cache

    protected java.util.HashMap cache

  The cache of SingleSignOnEntry instances for authenticated Principals, keyed by the cookie value that is used to select them.

### debug

    protected int debug

  The debugging detail level for this component.

### info

    protected static java.lang.String info

  Descriptive information about this Valve implementation.

### lifecycle

    protected LifecycleSupport lifecycle

  The lifecycle event support for this component.

### reverse

    protected java.util.HashMap reverse

  The cache of single sign on identifiers, keyed by the Session that is associated with them.

### sm

    protected static final StringManager sm

  The string manager for this package.

### started

    protected boolean started

  Component started flag.

Constructor Detail

### SingleSignOn

    public SingleSignOn()

Method Detail

### getDebug

    public int getDebug()

  Return the debugging detail level.

  Overrides:
    `getDebug` in class `ValveBase`

### setDebug

    public void setDebug(int debug)

  Set the debugging detail level.

  Overrides:
    `setDebug` in class `ValveBase`
  Parameters:
    `debug` - The new debugging detail level

### getRequireReauthentication

    public boolean getRequireReauthentication()

  Gets whether each request needs to be reauthenticated (by an Authenticator downstream in the pipeline) to the security `Realm`, or if this Valve can itself bind security info to the request based on the presence of a valid SSO entry without rechecking with the `Realm</code.. <P>`
  Returns:
    `true` if it is required that a downstream Authenticator reauthenticate each request before calls to `HttpServletRequest.setUserPrincipal()` and `HttpServletRequest.setAuthType()` are made; `false` if the `Valve` can itself make those calls relying on the presence of a valid SingleSignOn entry associated with the request.
  See Also:
    `setRequireReauthentication(boolean)`

### setRequireReauthentication

    public void setRequireReauthentication(boolean required)

  Sets whether each request needs to be reauthenticated (by an Authenticator downstream in the pipeline) to the security `Realm`, or if this Valve can itself bind security info to the request, based on the presence of a valid SSO entry, without rechecking with the `Realm</code. <p> If this property is `false` (the default), this `Valve` will bind a UserPrincipal and AuthType to the request if a valid SSO entry is associated with the request. It will not notify the security `Realm` of the incoming request.

  This property should be set to `true` if the overall server configuration requires that the `Realm` reauthenticate each request thread. An example of such a configuration would be one where the `Realm` implementation provides security for both a web tier and an associated EJB tier, and needs to set security credentials on each request thread in order to support EJB access.

  If this property is set to `true`, this Valve will set flags on the request notifying the downstream Authenticator that the request is associated with an SSO session. The Authenticator will then call its `reauthenticateFromSSO` method to attempt to reauthenticate the request to the `Realm`, using any credentials that were cached with this Valve.

  The default value of this property is `false`, in order to maintain backward compatibility with previous versions of Tomcat.

  `
  Parameters:
    `required` - `true` if it is required that a downstream Authenticator reauthenticate each request before calls to `HttpServletRequest.setUserPrincipal()` and `HttpServletRequest.setAuthType()` are made; `false` if the `Valve` can itself make those calls relying on the presence of a valid SingleSignOn entry associated with the request.
  See Also:
    `AuthenticatorBase.reauthenticateFromSSO(java.lang.String, org.apache.catalina.HttpRequest)`

### addLifecycleListener

    public void addLifecycleListener(LifecycleListener listener)

  Add a lifecycle event listener to this component.

  Specified by:
    `addLifecycleListener` in interface `Lifecycle`
  Parameters:
    `listener` - The listener to add

### findLifecycleListeners

    public LifecycleListener[] findLifecycleListeners()

  Get the lifecycle listeners associated with this lifecycle. If this Lifecycle has no listeners registered, a zero-length array is returned.

  Specified by:
    `findLifecycleListeners` in interface `Lifecycle`

### removeLifecycleListener

    public void removeLifecycleListener(LifecycleListener listener)

  Remove a lifecycle event listener from this component.

  Specified by:
    `removeLifecycleListener` in interface `Lifecycle`
  Parameters:
    `listener` - The listener to remove

### start

    public void start()
               throws LifecycleException

  Prepare for the beginning of active use of the public methods of this component. This method should be called after `configure()`, and before any of the public methods of the component are utilized.

  Specified by:
    `start` in interface `Lifecycle`
  Throws:
    `LifecycleException` - if this component detects a fatal error that prevents this component from being used

### stop

    public void stop()
              throws LifecycleException

  Gracefully terminate the active use of the public methods of this component. This method should be the last one called on a given instance of this component.

  Specified by:
    `stop` in interface `Lifecycle`
  Throws:
    `LifecycleException` - if this component detects a fatal error that needs to be reported

### sessionEvent

    public void sessionEvent(SessionEvent event)

  Acknowledge the occurrence of the specified event.

  Specified by:
    `sessionEvent` in interface `SessionListener`
  Parameters:
    `event` - SessionEvent that has occurred

### getInfo

    public java.lang.String getInfo()

  Return descriptive information about this Valve implementation.

  Specified by:
    `getInfo` in interface `Valve`
  Overrides:
    `getInfo` in class `ValveBase`

### invoke

    public void invoke(Request request,
                       Response response,
                       ValveContext context)
                throws java.io.IOException,
                       javax.servlet.ServletException

  Perform single-sign-on support processing for this request.

  Specified by:
    `invoke` in interface `Valve`
  Specified by:
    `invoke` in class `ValveBase`
  Parameters:
    `request` - The servlet request we are processing
    `response` - The servlet response we are creating
    `context` - The valve context used to invoke the next valve in the current processing pipeline
  Throws:
    `java.io.IOException` - if an input/output error occurs
    `javax.servlet.ServletException` - if a servlet error occurs

### toString

    public java.lang.String toString()

  Return a String rendering of this object.

### log

    protected void log(java.lang.String message)

  Log a message on the Logger associated with our Container (if any).

  Parameters:
    `message` - Message to be logged

### log

    protected void log(java.lang.String message,
                       java.lang.Throwable throwable)

  Log a message on the Logger associated with our Container (if any).

  Parameters:
    `message` - Message to be logged
    `throwable` - Associated exception

### lookup

    protected org.apache.catalina.authenticator.SingleSignOnEntry lookup(java.lang.String ssoId)

  Look up and return the cached SingleSignOn entry associated with this sso id value, if there is one; otherwise return `null`.

  Parameters:
    `ssoId` - Single sign on identifier to look up

Copyright ? 2000-2002 Apache Software Foundation. All Rights Reserved.