Package org.apache.catalina.authenticator

## Class SingleSignOn

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

All Implemented Interfaces:
  `javax.management.MBeanRegistration`, `Contained`, `JmxEnabled`, `Lifecycle`, `Valve`

Direct Known Subclasses:
  `ClusterSingleSignOn`

    public class SingleSignOn
    extends ValveBase

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

Author:
  Craig R. McClanahan

### Nested Class Summary

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

`Lifecycle.SingleUse`

### Field Summary

Fields
`protected java.util.Map<java.lang.String,​SingleSignOnEntry>` `cache` The cache of SingleSignOnEntry instances for authenticated Principals, keyed by the cookie value that is used to select them.

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

`asyncSupported, container, containerLog, next`

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

### Method Summary

All Methods Instance Methods Concrete Methods
`protected boolean` `associate​(java.lang.String ssoId, Session session)` Associate the specified single sign on identifier with the specified Session.
`protected void` `deregister​(java.lang.String ssoId)` Deregister the specified single sign on identifier, and invalidate any associated sessions.
`java.lang.String` `getCookieDomain()` Returns the optional cookie domain.
`java.lang.String` `getCookieName()`
`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`.
`protected SessionListener` `getSessionListener​(java.lang.String ssoId)`
`void` `invoke​(Request request, Response response)` Perform single-sign-on support processing for this request.
`protected boolean` `reauthenticate​(java.lang.String ssoId, Realm realm, Request request)` Attempts reauthentication to the given `Realm` using the credentials associated with the single sign-on session identified by argument `ssoId`.
`protected void` `register​(java.lang.String ssoId, java.security.Principal principal, java.lang.String authType, java.lang.String username, java.lang.String password)` Register the specified Principal as being associated with the specified value for the single sign on identifier.
`protected void` `removeSession​(java.lang.String ssoId, Session session)` Remove a single Session from a SingleSignOn.
`void` `sessionDestroyed​(java.lang.String ssoId, Session session)` Process a session destroyed event by removing references to that session from the caches and - if the session destruction is the result of a logout - destroy the associated SSO session.
`void` `setCookieDomain​(java.lang.String cookieDomain)` Sets the domain to be used for sso cookies.
`void` `setCookieName​(java.lang.String cookieName)` Set the cookie name that will be used for the SSO cookie.
`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`.
`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​(java.lang.String ssoId, java.security.Principal principal, java.lang.String authType, java.lang.String username, java.lang.String password)` Updates any `SingleSignOnEntry` found under key `ssoId` with the given authentication data.

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

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

#### cache

    protected java.util.Map<java.lang.String,​SingleSignOnEntry> cache

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

### Constructor Detail

#### SingleSignOn

    public SingleSignOn()

### Method Detail

#### getCookieDomain

    public java.lang.String getCookieDomain()

Returns the optional cookie domain. May return null.

Returns:
  The cookie domain

#### setCookieDomain

    public void setCookieDomain​(java.lang.String cookieDomain)

Sets the domain to be used for sso cookies.

Parameters:
  `cookieDomain` - cookie domain name

#### getCookieName

    public java.lang.String getCookieName()

Returns:
  the cookie name

#### setCookieName

    public void setCookieName​(java.lang.String cookieName)

Set the cookie name that will be used for the SSO cookie.

Parameters:
  `cookieName` - the cookieName to set

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

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

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.connector.Request)`

#### invoke

    public void invoke​(Request request,
                       Response response)
                throws java.io.IOException,
                       ServletException

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

Parameters:
  `request` - The servlet request we are processing
  `response` - The servlet response we are creating
Throws:
  `java.io.IOException` - if an input/output error occurs
  `ServletException` - if a servlet error occurs

#### sessionDestroyed

    public void sessionDestroyed​(java.lang.String ssoId,
                                 Session session)

Process a session destroyed event by removing references to that session from the caches and - if the session destruction is the result of a logout - destroy the associated SSO session.

Parameters:
  `ssoId` - The ID of the SSO session which which the destroyed session was associated
  `session` - The session that has been destroyed

#### associate

    protected boolean associate​(java.lang.String ssoId,
                                Session session)

Associate the specified single sign on identifier with the specified Session.

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`

#### deregister

    protected void deregister​(java.lang.String ssoId)

Deregister the specified single sign on identifier, and invalidate any associated sessions.

Parameters:
  `ssoId` - Single sign on identifier to deregister

#### reauthenticate

    protected boolean reauthenticate​(java.lang.String ssoId,
                                     Realm realm,
                                     Request request)

Attempts reauthentication to the given `Realm` using the credentials associated with the single sign-on session identified by argument `ssoId`.

If reauthentication is successful, the `Principal` and authorization type associated with the SSO session will be bound to the given `Request` object via calls to `Request.setAuthType()` and `Request.setUserPrincipal()`

Parameters:
  `ssoId` - identifier of SingleSignOn session with which the caller is associated
  `realm` - Realm implementation against which the caller is to be authenticated
  `request` - the request that needs to be authenticated
Returns:
  `true` if reauthentication was successful, `false` otherwise.

#### register

    protected void register​(java.lang.String ssoId,
                            java.security.Principal principal,
                            java.lang.String authType,
                            java.lang.String username,
                            java.lang.String password)

Register the specified Principal as being associated with the specified value for the single sign on identifier.

Parameters:
  `ssoId` - Single sign on identifier to register
  `principal` - Associated user principal that is identified
  `authType` - Authentication type used to authenticate this user principal
  `username` - Username used to authenticate this user
  `password` - Password used to authenticate this user

#### update

    protected boolean update​(java.lang.String ssoId,
                             java.security.Principal principal,
                             java.lang.String authType,
                             java.lang.String username,
                             java.lang.String password)

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.

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`

#### removeSession

    protected void removeSession​(java.lang.String ssoId,
                                 Session session)

Remove a single Session from a SingleSignOn. Called when a session is timed out and no longer active.

Parameters:
  `ssoId` - Single sign on identifier from which to remove the session.
  `session` - the session to be removed.

#### getSessionListener

    protected SessionListener getSessionListener​(java.lang.String ssoId)

#### startInternal

    protected void startInternal()
                          throws LifecycleException

Description copied from class: `ValveBase`
Start this component and implement the requirements of `LifecycleBase.startInternal()`.

Overrides:
  `startInternal` in class `ValveBase`
Throws:
  `LifecycleException` - if this component detects a fatal error that prevents this component from being used

#### stopInternal

    protected void stopInternal()
                         throws LifecycleException

Description copied from class: `ValveBase`
Stop this component and implement the requirements of `LifecycleBase.stopInternal()`.

Overrides:
  `stopInternal` in class `ValveBase`
Throws:
  `LifecycleException` - if this component detects a fatal error that prevents this component from being used