## 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.9 $ $Date: 2001/08/03 22:39:33 $
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
`START_EVENT, STOP_EVENT`

Constructor Summary
`SingleSignOn()`

Method Summary
`void` `addLifecycleListener(LifecycleListener listener)` Add a lifecycle event listener to this component.
`int` `getDebug()` Return the debugging detail level.
`java.lang.String` `getInfo()` Return descriptive information about this Valve implementation.
`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` `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.

### setDebug

    public void setDebug(int debug)

  Set the debugging detail level.

  Parameters:
    `debug` - The new debugging detail level

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

### 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:
    `java.lang.IllegalStateException` - if this component has already been started
    `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:
    `java.lang.IllegalStateException` - if this component has not been started
    `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.

  Overrides:
    `toString` in class `java.lang.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-2001 Apache Software Foundation. All Rights Reserved.