AppWrap file description

  • Article

Applies To: Unified Access Gateway

The application wrapper (AppWrap) templates used in Forefront Unified Access Gateway (UAG) follow these conventions:

  • Tag names are uppercase: <TAG>...</TAG>

  • Attribute names are lowercase: <TAG attribute=value>...</TAG>

  • Attribute values are case insensitive:

    <TAG attribute=value>...</TAG>

    is identical to:

    <TAG attribute=VALUE>...</TAG>

  • Some XML elements take regular expressions in the data. When regular expressions are used, this is indicated in the description of the element usage. When using regular expressions, note the following:

    • Use the syntax described in About Regex++ syntax. In order to use a character as is, make sure it is preceded by a slash. For example, to use the asterisk (*) wildcard in data that takes regular expressions, enter \*

  • The supported encoding is Base64. In order to edit encoded text, use the Editor to convert from and to Base64, as described in About the Editor console.

The AppWrap files contain the following elements:

  • The first element nested under the root element must be <MANIPULATION>

  • Two child elements exist under <MANIPULATION> to manipulate the application data: <MANIPULATION_PER_APPLICATION> and <HEADER_CHANGE>.

  • You can use as many <MANIPULATION_PER_APPLICATION> elements as required, but only one <HEADER_CHANGE> element.

<MANIPULATION_PER_APPLICATION>

A <MANIPULATION_PER_APPLICATION> section is required for each application that you want to customize. It contains the following elements:

  • <APPLICATION_TYPE>—Only one <APPLICATION_TYPE> tag is allowed in each <MANIPULATION_PER_APPLICATION> section.

  • <DATA_CHANGE>—An unlimited number of <ADD_HEADER> elements are allowed in each <MANIPULATION_PER_APPLICATION> section.

<APPLICATION_TYPE>

The <APPLICATION_TYPE> tag defines the application upon which Forefront UAG will perform customizations.

For each application that you want to create a customization, add the following: <APPLICATION_TYPE>[Application_Name]</APPLICATION_TYPE>.

Enter the application name as it is defined in the ...\Microsoft Forefront Unified Access Gateway\von\Conf\WizardDefaults\WizardDefaultParam.ini file.

<DATA_CHANGE>

Searches and replaces data string or strings in the data received from the application server before data is sent to the browser.

<DATA_CHANGE> must contain one of each of the following elements:

  • <URL>

  • <SAR>

<URL>

Child element of <DATA_CHANGE>. Defines the URL in which data is searched and replaced.

  • One (and only one) <URL> element must be nested under each <DATA_CHANGE> element.

  • Takes regular expressions.

The following table lists the attributes and attribute values applicable for the <URL> tag:

Attribute Values Default Type/Comments

case_sensitive

true, false

false

Optional

<SAR>

Child element of <DATA_CHANGE>. Defines a string to search and replace.

  • One <SAR> element must be nested under each <DATA_CHANGE> element.

  • An unlimited number of <SAR> elements can be nested under each <DATA_CHANGE> element.

<SAR> must contain one of each of the following elements:

  • <SEARCH>

  • <REPLACE>

    Note

    <SEARCH> and <REPLACE> elements always come in pairs. For every <SEARCH> element there must be a <REPLACE> element.

Child element of <SAR>. Defines the string that <SAR> searches.

  • One (and only one) <SEARCH> element must be nested under each <SAR> element.

  • Two <SEARCH> elements (nested under different <SAR> elements), where one is a sub-string of the other, would cause an error.

  • The search is case insensitive.

The following table lists the attributes and attribute values applicable for the <SEARCH> tag:

Attribute Values Type/Comments

encoding

base64

Optional

<REPLACE>

Child element of <SAR>. Defines the string with which <SAR> replaces the string defined in <SEARCH>.

  • One (and only one) <REPLACE> element must be nested under each <SAR> element.

  • Case is maintained.

  • The following variables can be used as placeholders in the data of <REPLACE>; note that variable names are case sensitive:

    • WhlSessionTimeout—The maximum time a session can be inactive before it expires. Configured on the Session tab of the Advanced Trunk Configuration dialog box, under “Inactive session timeout”.

    • WhlLogoffURL—URL to be recognized by the filter as the logoff URL. Configured on the Authentication tab of the Advanced Trunk Configuration dialog box, under “Logoff URL”.

    • WhlScheduledLogoffTimer—After the time defined in this variable elapses, the user is required to re-authenticate. Configured on the Session tab of the Advanced Trunk Configuration dialog box, under “Trigger logoff scheme after … minutes”.

    • WhlOwnURL—URL where the graphic files used by the internal Web site are located: /InternalSite/.

The following table lists the attributes and attribute values applicable for the <REPLACE> tag:

Attribute Values Type/Comments

encoding

base64

Optional

<HEADER_CHANGE>

Adds and deletes headers, and replaces header values, in either requests or responses. Header manipulation can be configured for a single application, a range of applications, or an application-type.

  • <HEADER_CHANGE> is optional.

  • Only one <HEADER_CHANGE> element can be nested under <MANIPULATION>.

<HEADER_CHANGE> can contain one each of the following elements:

  • <REQUEST>

  • <RESPONSE>

<REQUEST>

Child element of <HEADER_CHANGE>. Manipulates headers in requests.

  • <REQUEST> is optional.

  • Only one <REQUEST> element can be nested under <HEADER_CHANGE>.

  • <REQUEST> must contain at least one <APPLICATION> element.

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

<RESPONSE>

Child element of <HEADER_CHANGE>. Manipulates headers in responses.

  • <RESPONSE> is optional.

  • Only one <RESPONSE> element can be nested under <HEADER_CHANGE>.

  • <RESPONSE> must contain at least one <APPLICATION> element.

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

<APPLICATION>

Child element of <REQUEST> and of <RESPONSE>. Defines header manipulations for an application or application-type.

An unlimited number of <APPLICATION> elements can be nested under <REQUEST> and under <RESPONSE>.

<APPLICATION> must contain:

  • One <SERVER_NAME> element, and optionally, one <PORT> element.

or

  • One <APPLICATION_TYPE> element.

  • One or more <URL> elements.

<SERVER_NAME>

Child element of <APPLICATION>. Defines the server or subnet where manipulated is required.

  • One (and only one) <SERVER_NAME> element can be nested under each <APPLICATION> element.

  • For each <SERVER_NAME> element, one <PORT> element can also be nested under <APPLICATION>.

  • Can be defined using one of the following methods:

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

    • Subnet, using the “mask” attribute. For example:

      For subnet class A: <SERVER_NAME mask="255.0.0.0">192.0.0.0</SERVER_NAME>.

      For subnet class B: <SERVER_NAME mask="255.255.0.0">192.168.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.

The following table lists the attributes and attribute values for the <SERVER_NAME> tag:

Attribute Values Type/Comments

mask

subnet mask

Optional. Used to define a subnet mask.

<PORT>

Child element of <APPLICATION>. Defines the port number on which the server, defined in <SERVER_NAME>, listens to incoming requests.

  • This tag is optional.

  • For each <SERVER_NAME> element, one (and only one) <PORT> element can be nested under <APPLICATION>.

<APPLICATION_TYPE>

Child element of <APPLICATION>. Defines the type of application where manipulated is required.

  • One (and only one) <APPLICATION_TYPE> element can nested under each <APPLICATION> element.

<URL>

Child element of <APPLICATION>. Defines the URL or range of URLs for which header manipulation is configured, and the required manipulations.

  • One <URL> element must be nested under each <APPLICATION> element.

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

<URL> must contain the following:

  • One <URL_NAME> element.

  • One of the following elements:

    • <ADD>

    • <DELETE>

    • <EDIT>

<URL_NAME>

Child element of <URL>. Defines the URL or range of URLs for which header manipulation is configured.

  • One (and only one) <URL_NAME> must be nested under <URL>.

  • Takes regular expressions.

The following table lists the attributes and attribute values for the <URL_NAME> tag:

Attribute Values Type/Comments

InternalScheme

http, https

Optional

ExternalScheme

http, https

Optional
<ADD>

Child element of <URL>. Defines headers to add to either requests or responses, for the application defined in <APPLICATION>.

Only one <ADD> element can be nested under <URL>.

<ADD> can contain an unlimited number of <HEADER> elements.

Child element of <ADD>. Defines the header that is added.

  • At least one <HEADER> element must be nested under <ADD>.

  • An unlimited number of <HEADER> elements can be nested under <ADD>.

<HEADER> must contain one each of the following elements:

  • <NAME>

  • <VALUE>

    Note

    When you define an <ADD> element, under <HEADER>, <NAME> and <VALUE> elements always come in pairs–for every <NAME> element there must be a <VALUE> element, defining the header value.

<NAME>

Child element of <HEADER>. Name of the header that is added.

  • One (and only one) <NAME> element must be nested under <HEADER>.
<VALUE>

Child element of <HEADER>. Value of the header that is added.

  • One (and only one) <VALUE> element must be nested under <HEADER>.

The following table lists the attributes and attribute values for the <VALUE> tag:

Attribute Values Type/Comments

encoding

base64

Optional
<DELETE>

Child element of <URL>. Defines headers to delete from either requests or responses, for the application defined in <APPLICATION>.

Note

In requests, you cannot delete “host” headers.

You can delete all cookies–in either requests or responses–using one element; for details, refer to <NAME>.

Only one <DELETE> element can be nested under <URL>.

  • <DELETE> must contain at least one <HEADER> element.

  • <DELETE> can contain an unlimited number of <HEADER> elements.

<HEADER>

Child element of <DELETE>. Defines the header that is deleted.

  • At least one <HEADER> element must be nested under <DELETE>.

  • An unlimited number of <HEADER> elements can be nested under <DELETE>.

  • <HEADER> must contain only one <NAME> element.
<NAME>

Child element of <HEADER>. Defines the name of the header that is deleted.

Note

In order to delete a “Cookie” or “Set-Cookie” header, you must include the cookie name in the <NAME> element, in addition to the header name.

For example: to delete a “Set-Cookie” header where the name of the cookie is “a”, enter <NAME>Set-Cookie:a</NAME>.

Note that the cookie name is separated from the header name by a colon.

Tip

You can delete all cookies by entering the following:

In requests: <NAME>Cookie</NAME>

In responses: <NAME>Set-Cookie</NAME>

  • One (and only one) <NAME> element must be nested under <HEADER>.

  • In “Cookie” and “Set-Cookie” headers only: takes regular expressions in the cookie name.

<EDIT>

Child element of <URL>. Defines the replacement of header values in either requests or responses, for the application defined in <APPLICATION>.

Only one <EDIT> element can be nested under <URL>.

  • <EDIT> must contain at least one <HEADER> element.

  • <EDIT> can contain an unlimited number of <HEADER> elements.

<HEADER>

Child element of <EDIT>. Defines the header that is edited.

An unlimited number of <HEADER> elements can be nested under <EDIT>.

<HEADER> must contain one each of the following elements:

  • <NAME>

  • <SAR>

<NAME>

Child element of <HEADER>. Defines the name of the header whose value is replaced.

Note

In order to edit a “Cookie” or “Set-Cookie” header, you must include the cookie name in the <NAME> element, in addition to the header name.

For example: to edit a “Set-Cookie” header where the name of the cookie is “a”, enter <NAME>Set-Cookie:a</NAME>.

Note that the cookie name is separated from the header name by a colon.

  • One (and only one) <NAME> element must be nested under <HEADER>.

  • In “Cookie” and “Set-Cookie” headers only: takes regular expressions in the cookie name.

The following table lists the attributes and attribute values for the <NAME> tag:

Attribute Values Default Type/Comments

method

Name, Value, All

Value

Optional; applicable for cookies only (“Cookie” and “Set-Cookie” headers). Defines where the replacement takes place:

  • Name: cookie name

  • Value: cookie value

  • All: both cookie name and value

    > [!NOTE] > Attribute values are case insensitive >

<SAR>

Child element of <HEADER>. Defines header value that is replaced, and the replacement value.

An unlimited number of <SAR> elements can be nested under <HEADER>.

<SAR> must contain one each of the following elements:

  • <SEARCH>

  • <REPLACE>

    Note

    <SEARCH> and <REPLACE> elements usually come in pairs–for every <SEARCH> element there must be a <REPLACE> element. An exception to this rule is when you replace a cookie name in “Cookie” and “Set-Cookie” headers (value of the “method” attribute is “Name”). For this type of replacement, there is no need for a <SEARCH> element.

    For example:

    <HEADER>

    <NAME method="Name">cookie:abc.*</NAME>

    <SAR>

    <REPLACE encoding="">ddd</REPLACE>

    </SAR>

    </HEADER>

<SEARCH>

Child element of <SAR>. Defines the header value that is replaced.

  • One (and only one) <SEARCH> element must be nested under <SAR>.

The following table lists the attributes and attribute values for the <SEARCH> tag:

Attribute Values Type/Comments

encoding

base64

Optional
<REPLACE>

Child element of <SAR>. Defines the replacement header value.

  • One (and only one) <REPLACE> element must be nested under <SAR>.

The following table lists the attributes and attribute values for the <REPLACE> tag:

Attribute Values Type/Comments

encoding

base64

Optional