Tomcat 10.1.19 · org.apache.catalina.authenticator.SingleSignOn

Modifier and Type	Field and Description
protected Map<String, SingleSignOnEntry>	cache The cache of SingleSignOnEntry instances for authenticated Principals, keyed by the cookie value that is used to select them.
private String	cookieDomain Optional SSO cookie domain.
private String	cookieName SSO cookie name, the default value is `JSESSIONIDSSO`.
private Engine	engine
private boolean	requireReauthentication Indicates whether this valve should require a downstream Authenticator to reauthenticate each request, or if it itself can bind a UserPrincipal and AuthType object to the request.
private static final StringManager	sm Hides org.apache.catalina.valves.ValveBase.sm.

Access	Constructor and Description
public	SingleSignOn()

Method Summary

Modifier and Type	Method and Description
protected boolean	Returns: `true` if the session was associated to the given SSO session, otherwise `false` associate(String Single sign on identifier ssoId, Session Session to be associated session) Associate the specified single sign on identifier with the specified Session.
protected void	deregister(String Single sign on identifier to deregister ssoId) Deregister the specified single sign on identifier, and invalidate any associated sessions.
private void	expire(SingleSignOnSessionKey key)
public String	Returns: The cookie domain getCookieDomain() Returns the optional cookie domain.
public String	Returns: the cookie name getCookieName()
public boolean	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. 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(String ssoId)
public void	invoke(Request The servlet request we are processing request, Response The servlet response we are creating response) Implements org.apache.catalina.Valve.invoke. Perform single-sign-on support processing for this request.
protected boolean	Returns: `true` if reauthentication was successful, `false` otherwise. reauthenticate(String identifier of SingleSignOn session with which the caller is associated ssoId, Realm Realm implementation against which the caller is to be authenticated realm, Request the request that needs to be authenticated request) Attempts reauthentication to the given `Realm` using the credentials associated with the single sign-on session identified by argument `ssoId`.
protected void	register(String Single sign on identifier to register ssoId, Principal Associated user principal that is identified principal, String Authentication type used to authenticate this user principal authType, String Username used to authenticate this user username, String Password used to authenticate this user password) Register the specified Principal as being associated with the specified value for the single sign on identifier.
protected void	removeSession(String Single sign on identifier from which to remove the session. ssoId, Session the session to be removed. session) Remove a single Session from a SingleSignOn.
public void	sessionDestroyed(String The ID of the SSO session which which the destroyed session was associated ssoId, Session The session that has been destroyed 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.
public void	setCookieDomain(String cookie domain name cookieDomain) Sets the domain to be used for sso cookies.
public void	setCookieName(String the cookieName to set cookieName) Set the cookie name that will be used for the SSO cookie.
public void	setRequireReauthentication(boolean `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. 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() Overrides org.apache.catalina.valves.ValveBase.startInternal. Start this component and implement the requirements of `org.apache.catalina.util.LifecycleBase#startInternal()`.
protected void	stopInternal() Overrides org.apache.catalina.valves.ValveBase.stopInternal. Stop this component and implement the requirements of `org.apache.catalina.util.LifecycleBase#stopInternal()`.
protected boolean	Returns: `true` if the credentials were updated, otherwise `false` update(String identifier of Single sign to be updated ssoId, Principal the `Principal` returned by the latest call to `Realm.authenticate`. principal, String the type of authenticator used (BASIC, CLIENT_CERT, DIGEST or FORM) authType, String the username (if any) used for the authentication username, String the password (if any) used for the authentication password) Updates any `SingleSignOnEntry` found under key `ssoId` with the given authentication data.

Inherited from org.apache.catalina.valves.ValveBase:: backgroundProcess getContainer getDomainInternal getNext getObjectNameKeyProperties initInternal isAsyncSupported setAsyncSupported setContainer setNext toString

cache	back to summary
protected Map<String, SingleSignOnEntry> cache The cache of SingleSignOnEntry instances for authenticated Principals, keyed by the cookie value that is used to select them.

engine	back to summary
private Engine engine

requireReauthentication	back to summary
private boolean requireReauthentication Indicates whether this valve should require a downstream Authenticator to reauthenticate each request, or if it itself can bind a UserPrincipal and AuthType object to the request.

sm	back to summary
private static final StringManager sm Hides org.apache.catalina.valves.ValveBase.sm.

SingleSignOn	back to summary
public SingleSignOn()

Method Detail

associate back to summary

associate	back to summary
protected boolean associate(String ssoId, Session session) Associate the specified single sign on identifier with the specified Session. Parameters ssoId:String Single sign on identifier session:Session Session to be associated Returns:boolean `true` if the session was associated to the given SSO session, otherwise `false`

protected boolean associate(String ssoId, Session session)

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

Parameters

ssoId:String: Single sign on identifier
session:Session: Session to be associated

Returns:boolean

true if the session was associated to the given SSO session, otherwise false

deregister	back to summary
protected void deregister(String ssoId) Deregister the specified single sign on identifier, and invalidate any associated sessions. Parameters ssoId:String Single sign on identifier to deregister

deregister

back to summary

protected void deregister(String ssoId)

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

Parameters

ssoId:String: Single sign on identifier to deregister

expire	back to summary
private void expire(SingleSignOnSessionKey key)

getCookieDomain

back to summary

public String getCookieDomain()

Returns the optional cookie domain. May return null.

Returns:String: The cookie domain

getCookieName	back to summary
public String getCookieName() Returns:String the cookie name

getRequireReauthentication back to summary

getRequireReauthentication	back to summary
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:boolean `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`

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:boolean: 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

getSessionListener	back to summary
protected SessionListener getSessionListener(String ssoId)

invoke	back to summary
public void invoke(Request request, Response response) throws IOException, ServletException Implements org.apache.catalina.Valve.invoke. Perform single-sign-on support processing for this request. Parameters request:Request The servlet request we are processing response:Response The servlet response we are creating Annotations @Override Exceptions IOException: if an input/output error occurs ServletException: if a servlet error occurs

invoke

back to summary

public void invoke(Request request, Response response) throws IOException, ServletException

Implements org.apache.catalina.Valve.invoke.

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

Parameters

request:Request: The servlet request we are processing
response:Response: The servlet response we are creating

Annotations

@Override

Exceptions

IOException:: if an input/output error occurs
ServletException:: if a servlet error occurs

reauthenticate back to summary

reauthenticate	back to summary
protected boolean reauthenticate(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:String identifier of SingleSignOn session with which the caller is associated realm:Realm Realm implementation against which the caller is to be authenticated request:Request the request that needs to be authenticated Returns:boolean `true` if reauthentication was successful, `false` otherwise.

protected boolean reauthenticate(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:String: identifier of SingleSignOn session with which the caller is associated
realm:Realm: Realm implementation against which the caller is to be authenticated
request:Request: the request that needs to be authenticated

Returns:boolean

true if reauthentication was successful, false otherwise.

register	back to summary
protected void register(String ssoId, Principal principal, String authType, String username, String password) Register the specified Principal as being associated with the specified value for the single sign on identifier. Parameters ssoId:String Single sign on identifier to register principal:Principal Associated user principal that is identified authType:String Authentication type used to authenticate this user principal username:String Username used to authenticate this user password:String Password used to authenticate this user

back to summary

protected void register(String ssoId, Principal principal, String authType, String username, String password)

Parameters

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

removeSession	back to summary
protected void removeSession(String ssoId, Session session) Remove a single Session from a SingleSignOn. Called when a session is timed out and no longer active. Parameters ssoId:String Single sign on identifier from which to remove the session. session:Session the session to be removed.

removeSession

back to summary

protected void removeSession(String ssoId, Session session)

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

Parameters

ssoId:String: Single sign on identifier from which to remove the session.
session:Session: the session to be removed.

sessionDestroyed	back to summary
public void sessionDestroyed(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:String The ID of the SSO session which which the destroyed session was associated session:Session The session that has been destroyed

sessionDestroyed

back to summary

public void sessionDestroyed(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:String: The ID of the SSO session which which the destroyed session was associated
session:Session: The session that has been destroyed

setCookieDomain

back to summary

public void setCookieDomain(String cookieDomain)

Sets the domain to be used for sso cookies.

Parameters

cookieDomain:String: cookie domain name

setCookieName

back to summary

public void setCookieName(String cookieName)

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

Parameters

cookieName:String: the cookieName to set

setRequireReauthentication back to summary

setRequireReauthentication	back to summary
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:boolean `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`

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:boolean: 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.

startInternal back to summary

startInternal	back to summary
protected void startInternal() throws LifecycleException Overrides org.apache.catalina.valves.ValveBase.startInternal. Doc from org.apache.catalina.valves.ValveBase.startInternal. Start this component and implement the requirements of `org.apache.catalina.util.LifecycleBase#startInternal()`. Annotations @Override Exceptions LifecycleException: if this component detects a fatal error that prevents this component from being used

protected void startInternal() throws LifecycleException

Overrides org.apache.catalina.valves.ValveBase.startInternal.

Doc from org.apache.catalina.valves.ValveBase.startInternal.

Start this component and implement the requirements of org.apache.catalina.util.LifecycleBase#startInternal().

Annotations

@Override

Exceptions

LifecycleException:: if this component detects a fatal error that prevents this component from being used

stopInternal back to summary

stopInternal	back to summary
protected void stopInternal() throws LifecycleException Overrides org.apache.catalina.valves.ValveBase.stopInternal. Doc from org.apache.catalina.valves.ValveBase.stopInternal. Stop this component and implement the requirements of `org.apache.catalina.util.LifecycleBase#stopInternal()`. Annotations @Override Exceptions LifecycleException: if this component detects a fatal error that prevents this component from being used

protected void stopInternal() throws LifecycleException

Overrides org.apache.catalina.valves.ValveBase.stopInternal.

Doc from org.apache.catalina.valves.ValveBase.stopInternal.

Stop this component and implement the requirements of org.apache.catalina.util.LifecycleBase#stopInternal().

Annotations

@Override

Exceptions

LifecycleException:: if this component detects a fatal error that prevents this component from being used

update back to summary

update	back to summary
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. 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:String identifier of Single sign to be updated principal:Principal the `Principal` returned by the latest call to `Realm.authenticate`. authType:String the type of authenticator used (BASIC, CLIENT_CERT, DIGEST or FORM) username:String the username (if any) used for the authentication password:String the password (if any) used for the authentication Returns:boolean `true` if the credentials were updated, otherwise `false`

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.

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:String: identifier of Single sign to be updated
principal:Principal: the Principal returned by the latest call to Realm.authenticate.
authType:String: the type of authenticator used (BASIC, CLIENT_CERT, DIGEST or FORM)
username:String: the username (if any) used for the authentication
password:String: the password (if any) used for the authentication

Returns:boolean

true if the credentials were updated, otherwise false

public Class SingleSignOn

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail