Manipulating cookies for HAT configuration in IAG

  • Article

Applies To: Intelligent Application Gateway (IAG)

When configure host address translation (HAT) In Whale Communications Intelligent Application Gateway (IAG) 2007, you can configure HAT settings in the Application Access Portal configuration file to manipulate the following types of cookie headers in responses:

  • Set-Cookie

  • Set-Cookie2

    Note

    In the following sections, references to Set-Cookie headers apply to both Set-Cookie and Set-Cookie2 header types.

You can remove cookies from these headers, and you can add, remove, or change any of the cookie attributes, thus changing the application’s behavior. You can implement the changes for a specific application or for an application type.

The following examples demonstrate a few of the possible changes enabled via cookie manipulation; you can use this capability to implement any other changes according to your needs:

  • Adding a Discard attribute to a cookie makes it non-persistent; you can add an Expires attribute to make the cookie persistent.

  • Adding a Secure attribute turns the cookie into a secure cookie, which will not be sent over an HTTP connection, only over HTTPS.

Cookie manipulation is defined in the AAP configuration file in the element <COOKIES_HANDLING>, described below.

Tip   

  • For information on troubleshooting cookies that contain a path or domain attribute, refer to Maintaining Original Cookie Names.

<COOKIES_HANDLING>

Description

Defines the handling of cookie in responses.

Usage

Only one <COOKIES_HANDLING> element can reside in the AAP configuration file.

Attributes & Attribute Values

None.

Child Elements

  • <COOKIES_HANDLING> can contain an unlimited number of <SERVER> elements.

  • <COOKIES_HANDLING> can contain an unlimited number of <APPLICATION> elements.

[<COOKIES_HANDLING>] > [<SERVER>]

<SERVER>

Description

Child element of <COOKIES_HANDLING>. Defines the manipulation of cookies sent by the defined server.

Usage

An unlimited number of <SERVER> elements can be nested under <COOKIES_HANDLING>.

Attributes & Attribute Values

None.

Child Elements

Each <SERVER> element must contain the following:

  • One <SERVER_NAME> element.

  • One or more <Set-Cookie> elements.

In addition, each <SERVER> element can optionally contain one of each of the following:

  • For each <SERVER_NAME> element, a <PORT> element.

  • <URL> element.

[<COOKIES_HANDLING>] > [<APPLICATION>]

<APPLICATION>

Description

Child element of <COOKIES_HANDLING>. Defines the manipulation of cookies sent by the defined application type.

Usage

An unlimited number of <APPLICATION> elements can be nested under <COOKIES_HANDLING>.

Attributes & Attribute Values

None.

Child Elements

Each <APPLICATION> element must contain the following:

  • One <APPLICATION_TYPE> element.

  • One or more <Set-Cookie> elements.

In addition, each <APPLICATION> element can optionally contain one <URL> element.

[<COOKIES_HANDLING>] > [<SERVER>] > [<SERVER_NAME>]

<SERVER_NAME>

Description

Child element of <SERVER>. Name of the server from which the manipulated cookie or cookies is sent.

Usage

  • Only one <SERVER_NAME> element must be nested under each <SERVER> element.

  • Can be defined using one of the following methods:

    • Server name or a range of names by using regular expressions.

    • Subnet by using the mask attribute. For example:

      For subnet class A:

      <SERVER_NAME mask="255.0.0.0">63.0.0.0</SERVER_NAME``>

      For subnet class B:

      <SERVER_NAME mask="255.255.0.0">160.12.0.0</SERVER_NAME>

      For subnet class C:

      <SERVER_NAME mask="255.255.255.0">192.168.1.0</SERVER_NAME>

      Note: In this syntax, enter the actual IP address, not regular expressions.

      Tip

      For examples of the use of both methods in a <SERVER_NAME> element, refer to "Sample Code: <HEADER_FILTER>" in Header Filtering.

Attributes & Attribute Values

Attribute Values Type or comments

mask

subnet mask

Optional. Used to define a subnet mask.

Child Elements

None.

[<COOKIES_HANDLING>] > [<SERVER>] > [<PORT>]

<PORT>

Description

Child element of <SERVER> that is applicable only if a <SERVER_NAME> element is used. Port number of the server from which the manipulated cookie or cookies is sent.

Usage

  • Optional.

  • Only one <PORT> element can be nested under each <SERVER> element.

Attributes & Attribute Values

None.

Child Elements

None.

[<COOKIES_HANDLING>] > [<APPLICATION>] > [<APPLICATION_TYPE>]

<APPLICATION_TYPE>

Description

Child element of <APPLICATION>. Type of application from which the manipulated cookie or cookies is sent.

Note

For instructions on where you can find the name of the application type, as it should be entered here, refer to "Finding an application type" in About the Editor console.

Usage

  • Only one <APPLICATION_TYPE> element must be nested under each <APPLICATION> element.

Attributes & Attribute Values

None.

Child Elements

None.

[<COOKIES_HANDLING>] > [<SERVER>]¦[<APPLICATION>] > [<URL>]

<URL>

Description

Child element of <SERVER> or of <APPLICATION>. URL of the server from which the manipulated cookie or cookies is sent.

Usage

  • Optional.

  • Only one <URL> element can be nested under each <SERVER> or <APPLICATION> element.

Attributes & Attribute Values

None.

Child Elements

None.

[<COOKIES_HANDLING>] > [<SERVER>]¦[<APPLICATION>] > [<Set-Cookie>]

Description

Child element of <SERVER> or of <APPLICATION>. Defines the Set-Cookie header that is manipulated and the manipulation.

Usage

  • At least one <Set-Cookie> element must be nested under each <SERVER> or <APPLICATION> element.

  • An unlimited number of <Set-Cookie> elements can be nested under each <SERVER> or <APPLICATION> element.

Attributes & Attribute Values

Attribute Values Type or comments

remove

true, false

Optional. Used to remove the entire header.

Child Elements

<Set-Cookie> must contain one <NAME> element.

The elements listed below define the actual manipulation on the cookie. <Set-Cookie> can contain a number of different elements, defining a number of manipulations on one cookie, as follows:

  • <Comment>

  • <CommentURL>

  • <Discard>

  • <Domain>

  • <Max-Age>

  • <Path>

  • <Port>

  • <Secure>

  • <Version>

  • <Expires>

Note

The element <VALUE> is not used at this time.

[<COOKIES_HANDLING>] > [<SERVER>] > [<Set-Cookie>] > [<NAME>]

<NAME>

Description

Child element of <Set-Cookie>. Defines the name of the cookie that is manipulated.

Usage

  • Only one <NAME> element must be nested under <Set-Cookie>.

  • Takes regular expressions.

Attributes & Attribute Values

None.

Child Elements

None.

[<COOKIES_HANDLING>] > [<SERVER>] > [<Set-Cookie>] > [<Comment>]

<Comment>

Description

Child element of <Set-Cookie>. Adds, removes, or changes a Comment attribute in the Set-Cookie header.

Usage

  • Optional.

  • Only one <Comment> element can be nested under <Set-Cookie>.

  • Characters in the value of this element must be in UTF-encoding (RFC2279).

  • To add a Comment attribute to the Set-Cookie header or to change the value of the existing attribute, enter the required value.

  • To remove an existing Comment attribute from the Set-Cookie header, use the optional “remove” attribute, described below.

Attributes & Attribute Values

Attribute Values Type or comments

remove

true, false

Optional. Used to remove an existing Comment attribute from the Set-Cookie header.

Child Elements

None.

[<COOKIES_HANDLING>] > [<SERVER>] > [<Set-Cookie>] > [<CommentURL>]

<CommentURL>

Description

Child element of <Set-Cookie>. Adds, removes, or changes a CommentURL attribute in the Set-Cookie header.

Usage

  • Optional.

  • Only one <CommentURL> element can be nested under <Set-Cookie>.

  • Takes an HTTP URL.

  • To add a CommentURL attribute to the Set-Cookie header or to change the value of an existing attribute, enter the required value.

  • To remove an existing CommentURL attribute from the header, use the optional “remove” attribute, described below.

Attributes & Attribute Values

Attribute Values Type or comments

remove

true, false

Optional. Used to remove an existing CommentURL attribute from the Set-Cookie header.

Child Elements

None.

[<COOKIES_HANDLING>] > [<SERVER>] > [<Set-Cookie>] > [<Discard>]

<Discard>

Description

Child element of <Set-Cookie>. Adds or removes a Discard attribute to or from the Set-Cookie header.

Usage

  • Optional.

  • Only one <Discard> element can be nested under <Set-Cookie>.

  • If the <Discard> element contains any value, a Discard attribute is added to the Set-Cookie header.

  • To remove an existing Discard attribute from the header, use the optional “remove” attribute, described below.

Attributes & Attribute Values

Attribute Values Type or comments

remove

true, false

Optional. Used to remove an existing Discard attribute from the Set-Cookie header.

Child Elements

None.

[<COOKIES_HANDLING>] > [<SERVER>] > [<Set-Cookie>] > [<Domain>]

<Domain>

Description

Child element of <Set-Cookie>. Adds or removes a Domain attribute to or from the Set-Cookie header.

Tip

For an example of the use of the <Domain> element in the AAP configuration file, refer to Sample Code: <COOKIES_HANDLING>.

Usage

  • Optional.

  • Only one <Domain> element can be nested under <Set-Cookie>.

  • To add a Domain attribute to the Set-Cookie header or to change the value of an existing attribute, enter the required value.

  • If the specified value does not start with a dot, the user agent adds a leading dot to the domain name.

  • To remove an existing Domain attribute from the header, use the optional “remove” attribute, described below.

Attributes & Attribute Values

Attribute Values Type or comments

remove

true, false

Optional. Used to remove an existing Domain attribute from the Set-Cookie header.

None.

Child Elements

None.

[<COOKIES_HANDLING>] > [<SERVER>] > [<Set-Cookie>] > [<Max-Age>

<Max-Age>

Description

Child element of <Set-Cookie>. Adds, removes, or changes a Max-Age attribute in the Set-Cookie header.

Usage

  • Optional.

  • Only one <Max-Age> element can be nested under <Set-Cookie>.

  • To add a Max-Age attribute to the Set-Cookie header or to change the value of the existing attribute, enter the required value. The value is delta-seconds, and must be a positive decimal integer.

  • To remove an existing Max-Age attribute from the Set-Cookie header, use the optional “remove” attribute, described below.

Attributes & Attribute Values

Attribute Values Type or comments

remove

true, false

Optional. Used to remove an existing Max-Age attribute from the Set-Cookie header.

Child Elements

None.

[<COOKIES_HANDLING>] > [<SERVER>] > [<Set-Cookie>] > [<Path>]

<Path>

Description

Child element of <Set-Cookie>. Adds, removes, or changes a Path attribute in the Set-Cookie header.

Usage

  • Optional.

  • Only one <Path> element can be nested under <Set-Cookie>.

  • To add a Path attribute to the Set-Cookie header or to change the value of the existing attribute, enter the required value.

  • To remove an existing Path attribute from the Set-Cookie header, use the optional “remove” attribute, described below.

Attributes & Attribute Values

Attribute Values Type or comments

remove

true, false

Optional. Used to remove an existing Path attribute from the Set-Cookie header.

Child Elements

None.

[<COOKIES_HANDLING>] > [<SERVER>] > [<Set-Cookie>] > [<Port>]

<Port>

Description

Child element of <Set-Cookie>. Adds, removes, or changes a Port attribute in the Set-Cookie header.

Usage

  • Optional.

  • Only one <Port> element can be nested under <Set-Cookie>.

  • To add a Port attribute to the Set-Cookie header or to change the value of the existing attribute, enter the required value.

  • Takes a list of one or more ports. The port list must be in quotation marks, even if there is only one port number in the list:

    Port[="portlist``"]

  • To remove an existing Port attribute from the Set-Cookie header, use the optional “remove” attribute, described below.

Attributes & Attribute Values

Attribute Values Type or comments

remove

true, false

Optional. Used to remove an existing Port attribute from the Set-Cookie header.

Child Elements

None.

[<COOKIES_HANDLING>] > [<SERVER>] > [<Set-Cookie>] > [<Secure>]

<Secure>

Description

Child element of <Set-Cookie>. Adds or removes a Secure attribute to or from the Set-Cookie header.

Tip

For an example of the use of the <Secure> element in the AAP configuration file, refer to Sample Code: <COOKIES_HANDLING>.

Usage

  • Optional.

  • Only one <Secure> element can be nested under <Set-Cookie>.

  • If the <Secure> element contains any value, a Secure attribute is added to the Set-Cookie header.

  • To remove an existing Secure attribute from the header, use the optional “remove” attribute, described below.

Attributes & Attribute Values

Attribute Values Type or comments

remove

true, false

Optional. Used to remove an existing Secure attribute from the Set-Cookie header.

Child Elements

None.

[<COOKIES_HANDLING>] > [<SERVER>] > [<Set-Cookie>] > [<Version>]

<Version>

Description

Child element of <Set-Cookie>. Adds, removes, or changes a Version attribute in the Set-Cookie header.

Usage

  • Optional.

  • Only one <Version> element can be nested under <Set-Cookie>.

  • To add a Version attribute to the Set-Cookie header, or to change the value of the existing attribute, enter the required value. The value must be a decimal integer.

Attributes & Attribute Values

Attribute Values Type or comments

remove

true, false

Optional. Used to remove an existing Version attribute from the Set-Cookie header.

Child Elements

None.

[<COOKIES_HANDLING>] > [<SERVER>] > [<Set-Cookie>] > [<Expires>]

<Expires>

Description

Child element of <Set-Cookie>. Adds, removes, or changes an Expires attribute in the Set-Cookie header.

Usage

  • Optional.

  • Only one <Expires> element can be nested under <Set-Cookie>.

  • To add an Expires attribute to the Set-Cookie header or to change the value of an existing Expires attribute, configure the value of the <Expires> element in one of the following by using one of the following syntax options:

    • A date in the following format:

      <Expires>Sun, 15-Feb-2003 10:50:00 GMT</Expires>

      This element sets the value of the Expires attribute and sets the cookie expiration time to the following:

      Sun, 15-Feb-2003 10:50:00 GMT

    • Number of seconds after which the cookie will expire.

      For example, to set the value of the Expires attribute to one hour, set the value of the Expires attribute to 3,600 seconds:

      <Expires>3600<Expires>

  • To remove an existing Expires attribute from the header, use the optional “remove” attribute, described below.

Attributes & Attribute Values

Attribute Values Type or comments

remove

true, false

Optional. Used to remove an existing Expires attribute from the Set-Cookie header.

Child Elements

None.

Sample Code: <COOKIES_HANDLING>

// The following sample demonstrates how you can turn a domain

// cookie into a regular cookie. In this example, the filter will

// remove the Domain attribute from the cookie my_cookie, which

// can arrive from any server in the domain .whalecom.com, and the

// cookie will be sent to the browser without this attribute. When

// the browser sends this cookie to the filter, the filter will use

// the value of the <Domain> element defined here to determine

// which domain should receive the cookie.

// This example also uses the <Secure> element to add a Secure

// attribute to my_cookie, making it a secure cookie.

<COOKIES_HANDLING>

<SERVER>

<SERVER_NAME mask=””>.*\.whalecom\.com</SERVER_NAME>

<Set-Cookie>

<NAME>my_cookie</NAME>

<Domain remove="true">.whalecom.com</Domain>

<Secure remove="">true</Secure>

</Set-Cookie>

</SERVER>

</COOKIES_HANDLING>