Different sites with unique domains must be able to share sessions. Session sharing generally requires a JSESSIONID cookie whose session identifier is shared among all sites within the same session.

If sites share a parent domain name—for example, www.baseball.sports.com and www.hockey.sports.com—the session cookie can bind to the parent domain name sports.com. The browser can use the same cookie for all hosts that share the parent domain name. However, sites with unique parent domain names—for example, baseball.com and hockey.com—rely on session recovery, where all Oracle ATG Web Commerce servers can access a common session ID that is maintained by a canonical session ID host, which is one of the Oracle ATG Web Commerce instances in the multisite environment.

In general, Oracle ATG Web Commerce supports two session recovery approaches:

The non-JavaScript approach is simpler. However, it requires several URL changes within the address bar that are visible to end users. It also exposes jsessionid in the address bar URL, which might be problematic from a security viewpoint. The JavaScript approach avoids changing the address bar URL and embedding jsessionid in the URL itself; however it might require extra requests, depending on the browser.

By default, session recovery with JavaScript is enabled. You configure the desired behavior through the component /atg/multisite/CanonicalSessionHostnameServlet by setting its Boolean property enableJavaScript.

Note: Session recovery uses cookies on the client Web browser. Session recovery will not affect site visitors who have chosen to block cookies, including third-party cookies.

General Requirements

Note: Session recovery tries to set the cookie for each host once per session, unless the cookie is already present. Because session recovery duplicates some application server cookie configuration, the overlapping settings must agree. As installed, session recovery supports standard J2EE settings. If you change application server settings, be sure also to change the corresponding session recovery settings.

WebSphere Application Server Requirements

Session recovery requires additional configuration on each WebSphere application server that is part of a multisite installation, as follows:

Session Recovery without JavaScript

Session recovery can avoid JavaScript through simple redirects to the canonical session ID host and back. The following example and graphic illustrate this approach:

Session Recovery with JavaScript

Session recovery can be implemented through JavaScript-enabled HTML pages. This approach encompasses two scenarios that apply to different browser capabilities:

Note: These approaches apply to browsers that do not support the property XMLHttpRequest.withCredentials, and therefore cannot issue JavaScript background requests.

The following example and graphic illustrate the first JavaScript scenario—set the JSESSIONID cookie in an IFRAME:

The following example and graphic illustrate the second JavaScript scenario: the IFRAME cannot set the session cookie and lacks postMessage() support:

Handling POST Requests

Form submissions whose method is set to POST are not redirected, in order to avoid loss of form data in the POST request. Instead, POST requests are processed as usual, and the session is marked for redirection to the canonical server on the next non-POST request.

JavaScript Page Templates and Configuration

The HTML pages that are used in the JavaScript approach are rendered from page templates instead of JSPs, as JSPs require a session and must have a given location in a web application. Page templates are also easy to modify or replace, depending on your application’s specific requirements.

The Oracle ATG Web Commerce installation provides two templates:

As installed, the two page templates provide limited functionality:

Both page templates define a number of JavaScript variables that correspond to properties in the CanonicalSessionHostnameServlet, and are set by those properties. Each template contains comments that describe the variables it uses.

The rendering of HTML pages is managed by two servlet components that implement atg.servlet.TemplateRendererServlet, and are referenced by two /atg/multisite/CanonicalSessionHostnameServlet properties as follows:

Page templates are loaded from the ClassLoader at the path specified in the TemplateRendererServlet property templateResourcePath. Use this property to specify your own templates or override those provided by the installation. Only complete replacement is allowed.

Each TemplateRendererServlet relies on a component that implements interface atg.servlet.TemplateRendererServlet.DynamicSubstitutionTextProvider. This component maps page template symbols to substitution strings and supplies this map to the appropriate TemplateRendererServlet. Two /atg/multisite/CanonicalSessionHostnameServlet properties reference DynamicSubstitutionTextProvider components:

At start-up, the CanonicalSessionHostnameServlet registers the appropriate DynamicSubstitutionTextProvider for each TemplateRendererServlet servlet.

The TemplateRendererServlet interface also provides the echoToStdout property, which can be helpful during development and debugging.

Session Recovery Configuration

Most session recovery behavior is configured through /atg/multisite/CanonicalSessionHostnameServlet properties (class atg.servlet.pipeline.CanonicalSessionHostnameServlet).

Property

Description

browserTyper

The name of the BrowserTyper to determine whether the agent string of a given browser specifies a browser that appears to support HTML 5’s postMessage but actually does not.

canonicalHostname

Host name of the canonical session ID server. If this property is null, the CanonicalSessionHostnameServlet is disabled.

Default: null

canonicalPort

Port used by the canonical session id server.

Default: 80

canonicalRedirectProtocol

Protocol used for redirects to the canonical session ID server.

Default: http

canonicalSubPath

Represents any subpath needed when redirecting to the canonicalSubPath to trigger this servlet (typically triggered by an Oracle ATG Web Commerce web application using the PageFilter). If this property is null, the request’s requestURI is used instead.

Note: On WebSphere application servers, set this property to the full path of the web application’s default JSP. For example:

/myapp/index.jsp

cookieSetFailedParameterName

The name of the parameter that indicates failure to set the cookie on the canonical session ID server. This parameter is used when redirecting back from the JavaScript-enabled redirect page in the inner IFRAME.

Default: canonicalSessionCookieSetFailed

enableExternalSessionIdWorkarounds

Boolean, specifies whether to enable workarounds for application servers that use a different external/internal session ID. These workarounds may not function properly in all cases.

enableJavaScript

Boolean, specifies whether to enable Session Recovery with JavaScript.

Default: true

enableSettingSessionCookie

Boolean, specifies whether to enable setting the JSESSIONID cookie. This is done on application servers that assume that setting the cookie failed because we have an existing session, but jsessionid is in the URL.

excludedUrlRegexes

A list of URLs to exclude from session recovery—for example, URLs that implement REST web services.

fromIframeParameterName

The name of the parameter that is set to true when an IFRAME is used to fetch the session ID from the canonical host.

Default: fromIframe

hasDelayedRedirect

Boolean, specifies whether to delay the redirect that sends the session ID to the canonical session ID server.

iframeTimeout

Number of milliseconds to wait for notification from the hidden IFRAME when using IFRAMES for session recovery.

Default: http://pt-skua:8180/dyn/admin/nucleus/atg/multisite/CanonicalSessionHostnameServlet/?propertyName=iframeTimeout5000

jsessionIdName

The jsessionid attribute that is inserted into the URL.

Default: jsessionid

jsessionIdPlaceholderUrl

A string that is used as a placeholder for the session ID parameter in the rendered URL when the JSESSIONID cookie is not set. The installed page template jsRedirectPage.tmpl uses this setting to replace the session ID parameter.

localHostConfiguration

Set to a localHostConfiguration component used to calculate a list of local host names; used if allowLocalHost is set to true.

Default: http://pt-skua:8180/dyn/admin/nucleus/atg/multisite/CanonicalSessionHostnameServlet/?propertyName=localHostConfiguration/atg/dynamo/service/LocalHostConfiguration

noRedirectJavaScriptParameterName

The name of the parameter to use that specifies not to render JavaScript. This parameter is typically set in a <noscript> tag on the JavaScript redirect page template.

Default: noRedirectJavascript

noScriptURL

The redirect URL that is used by a JavaScript page template when JavaScript is disabled. This is the original request URL with an additional parameter to indicate that the JavaScript page should not be rendered. This URL is typically referenced in the template page’s <noscript> tag.

noSessionRecoveryBrowserTypes

An array of BrowserTyper types for which session recovery is not attempted.

redirectBackDynamicSubstitutionTextProvider

References the component /atg/multisite/JavaScriptRedirectBackPageTemplateRendererServlet, which renders the redirect back page for Session Recovery with JavaScript.

redirectBackJavaScriptRenderer

Sets the TemplateRendererServlet that is used to render the JavaScript-enabled redirect back page, from the page template specified in its templateResourcePath property.

Default: http://pt-skua:8180/dyn/admin/nucleus/atg/multisite/CanonicalSessionHostnameServlet/?propertyName=redirectBackJavaScriptRenderer/atg/multisite/JavaScriptRedirectBackPageTemplateRendererServlet

redirectDynamicSubstitutionTextProvider

References the component /atg/multisite/JavaScriptRedirectPageTemplateRendererServlet, which renders the redirect page for Session Recovery with JavaScript.

redirectJavaScriptRenderer

Sets the TemplateRendererServlet that is used to render the JavaScript-enabled redirect page, from the page template specified in its templateResourcePath property

Default: http://pt-skua:8180/dyn/admin/nucleus/atg/multisite/CanonicalSessionHostnameServlet/?propertyName=redirectJavaScriptRenderer/atg/multisite/JavaScriptRedirectPageTemplateRendererServlet

sessionCookieDomain

The domain of the cookie that is used to carry the session ID. If null, then cookies are returned only to the host that saved them.

Default: null

sessionDataPath

The Nucleus path of the CanonicalSessionData component

sessionIdFromCookieParameterName

The name of the query parameter that represents an existing session ID, obtained from a cookie on the non-canonical host.

Default: http://pt-skua:8180/dyn/admin/nucleus/atg/multisite/CanonicalSessionHostnameServlet/?propertyName=sessionIdFromCookieParameterNamesessionIdFromCookie

sessionNotificationParameterName

The name of the query parameter that marks a request to the canonical session ID server that a session already exists.

Default: http://pt-skua:8180/dyn/admin/nucleus/atg/multisite/CanonicalSessionHostnameServlet/?propertyName=sessionNotificationParameterNamecannonicalSessionIsSessionNotification

URLPatternMatchingRuleFilter

Specifies the URLPatternMatchingRuleFilter that is used to obtain a site if allowAllSiteURLs is true.

Default: http://pt-skua:8180/dyn/admin/nucleus/atg/multisite/CanonicalSessionHostnameServlet/?propertyName=URLPatternMatchingRuleFilter/atg/multisite/URLPatternMatchingRuleFilter

useFoundSessionCookieParameter

Boolean, specifies whether to use the found session cookie parameter on the redirect back.

Default: false

useJsessionIdOnCookieMatch

Boolean, specifies whether to use a JSESSIONID in the URL after a cookie match; might be required by WebSphere application servers.

Default: false

The following properties should match those used by the Web application server. These are used to set the session cookie if the application server does not do so:

Property

Description

sessionCookieName

Name and attributes for the RFC2109 cookie storing the session, set with the following syntax:

SessionCookieName name attributes

Default: JSESSIONID

sessionCookiePath

Default: /

sessionCookieComment

The comment of the session cookie.

sessionCookieSecure

False

sessionCookieMaxAge

-1 (never expires)

Several CanonicalSessionHostnameServlet properties restrict which URLs are allowed for session recovery. These properties address a potential security risk where the CanonicalSessionHostnameServlet responds to requests for an unrelated domain. For example, a third party might generate a request and cause redirection back to its own server with a recovered jsessionid.

The following table describes properties that can help minimize this security risk:

Property

Description

allowAllSiteURLs

Boolean, specifies whether to allow all site URLs that are configured in the site repository, and the URLs generated from them via URL Transformation Rules.

Default: true

Caution: If you set this property to true, be sure that all URLs in the site repository are differentiated by unique domain names—that is, each URL contains a host name. If this property is set to true and any site URL omits a host name, that URL can be used by unknown hosts to obtain session IDs.

allowLocalHost

Boolean, specifies whether to allow known host names from the local host for session recovery, including addresses such as localhost and 127.0.0.1. You specify host names through the localHostNames property.

Default: true

allowedHostNames

A list of host names that are allowed to participate in session recovery. This list can be used on its own, or can supplement other ways of allowing session recovery.

localHostNames

Set to a list of host names that are explicitly allowed to obtain session IDs during session recovery. In order to make these host names available, allowLocalHost must be set to true.

Several properties configure the various URL parameter names that the servlet uses during session recovery. These are available in case there is a conflict with a parameter name. Typically, only two parameter names might need to be changed on the canonical session ID server, as they serve to trigger special processing on a request:

Property

Default parameter name

postSessionRedirectParameterName

postSessionRedirect

renderSessionIdParameterName

canonicalSessionRenderSessionId