SingleSignOn (Apache Tomcat 8.5.85 API Documentation)

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
    Modifier and Type | Field | Description
    --- | --- | ---
    `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
    Constructor | Description
    --- | ---
    `SingleSignOn()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `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