Format and constraints of rules

An authorization rule is defined as an XSL template in an XSL style sheet with the style sheet prolog specified in the configuration file. The rule must be written in a valid XSL template rule format and must return a text document that contains one of the following string identifiers:

• !TRUE!
• !FALSE!
• !INDIFFERENT!

The identifiers must be the only text in the output document but they can be surrounded by white space. The identifiers are not case-sensitive. A value other than one of the identifiers listed or an empty document might be returned. The access decision fails and an error code is returned to the resource manager to indicate the rule is not compliant. See Authorization rules evaluator.

For authorization decisions, the rule must return the expected decision data to the rules evaluator. The data that is returned from the rules-driven entitlements interface must be able to be expressed as a text name-value attribute pair in the entitlements output parameter of the azn_entitlement_get_entitlements() method. Many data providers return entitlements data in XML format. No additional transformation is required to pass these entitlements into the rules evaluator as ADI.

All ADI passed to the rules evaluator is specified in XML. Non-XML ADI that is passed to the access decision or retrieved from the credential is formatted into XML by the evaluator before an authorization rule can be evaluated.

The result of the XSL transformation done by an XSL authorization rule must be a text output document that contains only one of the supported string identifiers. The following example references the XML data item defined in JohnSmith. The condition the following example rule evaluates is expressed, as follows:

if ((AmountReqd + Credit Card Balance) < Credit Card Limit && MileagePlus Status is "100k")

The corresponding authorization rule is:

<xsl:if test="(AmountReqd + JohnSmith/CreditCard/Balance)
  &lt; JohnSmith/CreditCard/Limit
    and JohnSmith/MileagePlus/MemberStatus = '100k'">
  !TRUE!
</xsl:if>

This example rule is the simplest form for specifying an authorization rule. It does not include its own template match statement and it accepts the default template match statement, which is set to /XMLADI. Template match statements are an XSL language construct used to select the point in the hierarchy of an XML document at which the XSL rules, which are contained within the template match statement, are applied. The default template match statement of the ADI XML model matches from the top of the XMLADI document by specifying the XPath /XMLADI. To add our own template match statement to a rule definition, only two additional lines are needed. For example, we might rewrite the example to include our own explicit template match statement matching from the root of the XMLADI document. Modify the rule as follows:

<xsl:template match="/XMLADI">
<xsl:if test="(AmountReqd + JohnSmith/CreditCard/Balance)
  &lt; JohnSmith/CreditCard/Limit
    and JohnSmith/MileagePlus/MemberStatus = '100k')
  !TRUE!
</xsl:if>
</xsl:template>

To reference any data item in the document, the XPath to each node must include the XMLADI node. For example, to access the credit card balance, the full path would be /XMLADI/JohnSmith/CreditCard/Balance. When a rule is built, the rule writer must understand what the correct XPath is from the current point in the tree. The XPath accesses the XML data nodes and subnodes. The current point in the tree is selected with the template match statement. The template match statement allows an XSL programmer to shorten the XPath to each data element by specifying the XPath processing occur further down the XML document tree.

The <xsl:template match="/XMLADI"> statement tells the XSL processor that all relative XPaths within the bounds of the template statement must be assumed to be relative to the node XMLADI. To shorten the XPaths even further, the template match statement can be set at /XMLADI/JohnSmith. In this case, the credit card balance might be termed CreditCard/Balance. Policy administrators must also make the following assumptions about the XSL style sheet document that is created by the rules evaluator to contain the rule they devise:

• If a style sheet prolog is specified in the azn client configuration file, that prolog is imported into the empty style sheet. If no prolog is specified, the following default prolog is used instead:

  <!-- Required for XSLT language -->
  <?xml version="1.0" encoding='UTF-8'?>
  <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
            version="1.0">
  
  <!-- Required to constrain output of rule evaluation -->
  <xsl:output method="text" omit-xml-declaration="yes"
            encoding='UTF=8' indent="no"/>
  
  <!-- Need this to ensure default text node printing is off -->
  <xsl:template match="text()"></xsl:template>

• Among other things, this prolog sets the XSL style sheet syntax to version 1.0, which is supported by the embedded XSL processor. The prolog sets the namespace for XSL documents to xsl, which requires that all XSL language-specific identities be prefixed by xsl:. This prefix is the standard mode of operation for XSL style sheets. Most attributes in this prolog must be in the style sheet. If not, the results that are returned from the rules evaluator do not conform to the expected results.

• All authorization rules must be enclosed in an xsl:template match statement. If the rule is defined with its own xsl:template match statement, the rule is accepted as is. This acceptance allows the rule creator to specify the level within the ADI XML document at which the rule matches data items. In this case, the match statement must be the first statement encountered by the evaluator when validating the rule. Otherwise, it is assumed there is no template match statement. If there is a match statement but the match statement does not begin with the /XMLADI absolute path, the rule is returned as not valid. Relative match statements are not accepted at this level.

• If no match statement is specified in the rule, the rule is automatically enclosed in the following match statement:

  <xsl:template match="/XMLADI">
  			...
  <xsl:template>

• Therefore, all rules devised without an explicit template match statement must use XPath expressions that assume the XML context node is /XMLADI. The XPath expression for any ADI item must begin with the container name of the item and must be fully qualified.

Authorization rules are processed internally with a recursive algorithm. Avoid creating very long logical expressions that can exhaust the system stack. Long expressions are problematic on systems that have a small stack by default.

For example, this rule might exhaust the system stack:

<xsl:choose><xsl:when test="(((azn_cred_principal_name='9410431')) \
 or ((azn_cred_principal_name='user1')) \
 or ((azn_cred_principal_name='user2')) \
 ...
 or ((azn_cred_principal_name='user500'))\
 )">!TRUE!</xsl:when><xsl:otherwise>!FALSE!</xsl:otherwise></xsl:choose>

A better option is to add the users to a group and write a rule to check group membership. As a preventive measure two new options are added:

• xsl-max-logical-expressions
• xsl-eval-expressions-check

The xsl-max-logical-expressions option limits the number of logical 'or' and 'and' operators in a logical expression when a rule is created. The xsl-eval-expressions-check option uses the value from the xsl-max-logical-expressions option to limit the same logical operators when a rule is evaluated.

See the [aznapi-configuration] stanza in IBM Security Verify Access for Web: Plug-in for Web Servers Administration Guide.

Parent topic: Authorization rules evaluator