XSL transformation rules

A valid XSLT document can be used to transform the contents of the HTTP requests and responses.

The XSL transformation must output an XML document that defines the required changes. The output document contains a series of XML elements describing changes that must be made to the HTTP request or HTTP response.

Important: Author the XSLT documents carefully. Review and test the XSL transformation rules thoroughly before you implement it in a production environment. Incorrect syntax or badly formed XSLT might cause errors, or unexpected behavior.

The following table describes the base XML elements that WebSEAL requires in the transformed document:

Table 1. Base elements
Source document Base XML element
HTTP Request <HTTPRequestChange>
HTTP Response <HTTPResponseChange>

The XSL transformation rules must handle the contents of the HTTP input. The content includes:

  • The ResponseLine/RequestLine element.
  • The Headers element.
  • The Cookies element.
  • The Body element. (HTTPResponseChange only)

If elements of the RequestLine/ResponseLine are included in the transformed XML document, WebSEAL applies the corresponding changes to the HTTP request/response.

Header elements require an action attribute in the XSLT document to determine how WebSEAL transforms the header. The available actions are:

  1. add - adds a new header with a specific name and value.
  2. update - updates the value of an existing header (if the header does not exist, it is added).
  3. remove - removes the header with a specific name and value.

The Cookie elements require an action attribute in the XSLT document to determine how WebSEAL transforms the cookie. The available actions are:

  1. add - adds a new cookie with the specified name and values.
  2. update - updates the value of an existing cookie. (If the cookie does not exist, it is added).
  3. remove - removes the cookie with a specific name.
Note: Cookies are represented differently in requests and responses. Only the response contains the attributes beyond name and value. When updating a cookie, specify the cookie name and the fields that you want to update. When adding a cookie, the minimum fields that you must specify are cookie name and value.

You can optionally include the Body element to insert a body into an HTTP response. The content of the Body must be URL encoded. WebSEAL decodes the content when it creates the response. WebSEAL replaces any existing body in the HTTP response with the new content that is provided in this Body element. This element does not require an action.

Note: It is not possible to replace the body content in requests.

The authorization object name can be customized based on an incoming request. But the object name can be changed only once. A subsequent change of the object name within the same request does not generate a new authorization decision. The ObjectName element value can be either a relative value or an absolute value. For standard junctions, the relative value format is junction-name/resource. For virtual junctions, the relative value format is resource. For standard junctions, the absolute value format is /host_name-instance_name/junction-name/resource. For virtual junctions, the absolute value format is /host_name-instance_name/@virtual-junction-name/resource. An absolute object name must begin with /. The customized authorization object names do not undergo dynamic URL processing.

The ACL bits which are used in the authorization decision for an incoming request can be customized using the AclBits element. This only takes affect if the HTTP transformation rule is invoked as a result of a match on the request line of the request. It does not have any impact if a POP was used to trigger the HTTP transformation rule.

XSLT Extensions

The HTTP transformation rules XSLT parser contains extensions that can be used when you are authoring HTTP transformation rules.
Name Description Usage
matches Allows regular expressions to be used to match strings. matches (input, pattern)
replaces Allows regular expressions to be used to replace strings. replaces (input, pattern, format)
  • To use the XSLT extensions, the http://xsltfunctions.isam.ibm.com namespace must be defined.

    For example, <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" xmlns:external="http://xsltfunctions.isam.ibm.com">

  • The new extension functions, when qualified by the xslt functions namespace, can then be used in the XSLT rule.
    For example,
    To perform a regular expression match on the request URI:
    
<xsl:template match="//HTTPRequest/RequestLine">
    <xsl:choose>
        <xsl:when test="external:matches(URI, '/index[12].html')">
            <URI>/index.html</URI>
        </xsl:when>
    </xsl:choose>
</xsl:template>
    To perform a replace of the URI with a regular expression:
    
<xsl:template match="//HTTPRequest/RequestLine">
    <xsl:choose>
        <xsl:when test="external:matches(URI, '^/scim/Users/.*')">
            <URI><xsl:value-of select="external:replace(URI, '/scim/Users/(.*)', 
            '/v1/scim/Users/$1')"/></URI>
        </xsl:when>
    </xsl:choose>
</xsl:template>