Cookies

Cookies sent to FIT from a source server are automatically passed on to the client, unless explicitly disabled. To disable the automatic passing of cookies, use the setting fit-cookies in conf/config.xml.

The cookies are accessible for information or (DOM) manipulation at fit://request/cookies in the following format:

<cookies>
  <cookie name="cookieName" [ path="..." domain="..." expires="..." secure="true|false" httpOnly="true|false" ] transparent="true|false">cookieValue</cookie>
  <cookie name="..." [...] transparent="...">...</cookie>
  [...]
</cookies>

Encoded Cookies

By default, FIT renames and encodes the cookies that are sent downstream to include the domain and path of the source servers. This allows FIT to determine the appropriate sources for the incoming cookies in subsequent requests. This is due to the opaque URLs that FIT uses to allow aggregation of multiple sources.

The encoded cookies follow the naming scheme __fitS__NN, where the optional S denotes secure cookies and NN is an index starting with 0.

The value with all required information is encoded like this:

<OriginalName>#<OriginalDomain>/<expires?>/<secure?>/<httpOnly?>#<OriginalPath>#<OriginalValue>

Example:

SID#.example.com/1406020297/1/0#/shop#foobar

Transparent Cookies

In some cases it is useful to pass the cookies to the client in the “original” format, that is without the “envelope” format. This may be necessary to access the cookie from JavaScript or to share cookies with other non-FIT hosts.

You can enable the transparent mode for your main source in conf/sources.xml:

<sources>
  <source host="example.com">
    <cookies mode="transparent|force-transparent" />
  </source>
</sources>

To transfer a cookie in transparent mode, the cookie path must be empty or / for security reasons. Otherwise, the cookie is automatically passed on to the client in the encoded mode (see above). You can force transparent cookies with a path differing from / by setting the cookie mode to force-transparent (BETA). (This should be used together with trailing URL Marks).

FIT retains the domain attribute of cookies it receives, if it is valid for the request. For transparent cookies, it must be valid for the host name of the FIT server as well. Otherwise, FIT drops the domain attribute.

The transparent mode should be used with caution. We recommend activating the transparent mode only for a single source server per site.

If the transparent mode is enabled, all non-encoded incoming cookies are automatically passed on to all source servers of the current site for which transparent mode is enabled, since FIT cannot know which site the cookies originated from. This is a potential security and privacy risk.

For transparent cookies to function, the <fit-cookies/> option still has to be turned on.

Deleting cookies (client side)

To instruct a client to delete a cookie the expires date must be set in the past of the current UNIX timestamp. So it’s enough to set the UNIX timestamp in the expires attribute to 0 (or another timestamp that is in the past of the current UNIX timestamp).

Examples

Via flow.xml:

<flow>
  ...
  <set-attributes in="fit://request/cookies" out="fit://request/cookies" xpath="//cookie[@name='COOKIE-NAME']" expires="0" />
  ...
</flow>

Via XSLT:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  ...
  <xsl:template match="cookie[@name='COOKIE-NAME']/@expires">
    <!-- The UNIX timestamp "123456" is already in the past of the current UNIX timestamp -->
    <xsl:attribute name="expires">123456</xsl:attribute>
  </xsl:template>
  ...
</xsl:stylesheet>