Compare Expression Assertion

The Compare Expression assertion is used to compare the result of evaluating of a single context variable or an expression against a series of rules during the runtime processing of a policy. This assertion succeeds only if all the rules are satisfied.

gateway83

For brevity, the term "result" is used throughout the rest of this topic to denote the result of evaluating an expression.

The Compare Expression assertion can do the following:

Ensure that the result is, or can be converted to, a specific data type.

Perform simple comparisons against the result of another expression using standard operators such as "equals", "less than", and "contains".

Verify that the number of values in the result falls between a designated minimum and maximum.

Verify that the result matches a Regular Expression.

Verify that the length of the result, expressed as a string, falls between a designated minimum and maximum number of characters.

Example 1:

The Compare Expression assertion is used with two XPath assertions (for example, the Evaluate Request XPath and/or the Evaluate Response XPath assertions) to evaluate the result of a particular attribute in a Require SAML Token Profile assertion attribute statement matches a value found in the message body. In this scenario, at least one of the XPath assertions may have a non-default variable prefix so that the second XPath assertion does not overwrite the variables set by the first.

Example 2:

The Compare Expression assertion is used to verify that exactly one node has been found by a previous Evaluate Request XPath assertion by testing that ${requestXpath.count} = 1 (use a Simple Comparison rule with the "equals" operator).

1) If you have difficulties getting the comparisons to work, ensure that the variable names are entered correctly—for example, verify that the curly braces "{ }" are used, not parenthesis "( )". To reference a variable that variable syntax ${} must be used. (2) If your policy logic requires determining whether a context variable exists, see Checking Existence of Context Variables under Context Variables.

Using the Assertion

Do one of the following:

To add the assertion to the Policy Development window, see Add an Assertion.

To change the configuration of an existing assertion, proceed to step 2 below.

When adding the assertion, the Compare Expression Properties automatically appear; when modifying the assertion, right-click Compare Expression in the policy window and select Compare Expression Properties or double-click the assertion in the policy window. The assertion properties are displayed.

Select either Variable
or Expression
from the drop-down list.

If you select Variable
, enter a single variable to be evaluated. It can reference context variables, in the format ${contextVariable}. If you enter a multivalued variable, then all values of the variable will be tested against the "Rules" list and depending on what was selected for the "If Multivalued" drop-down list.

If you select Expression
, enter the expression to be evaluated. The expression can contain either a string, a single variable, multiple variables, or a string containing one or more variables. It can reference context variables, in the format ${contextVariable.name}. This expression will be tested against the "Rules" list.

You can include constant values in the expression. For example, the variable ${requestXpath.result} contains the value "B". If you enter the expression "A${requestXpath.result}C", the resulting value that will be compared is "ABC". However, if the Expression field contains anything but a single context variable reference (such as ${var}), selecting a data type other than String is unlikely to yield useful results.

Select the Data Type
for the expression. This verifies that the result is, or can be converted to a value of the selected type.

Data Type	Description
Unknown/Other	The result can be in any data type. The assertion will not attempt to convert. For comparison purposes, "Unknown/Other" data types are treated as strings.
String	The result can be any string of characters. If the result is an integer, decimal, or Boolean value, it will be converted to a character string for the purposes of comparison.
Integer	The result must contain only numeric characters. The assertion will fail if non-numeric characters appear in the result.
Decimal	The result must contain only numeric characters, optionally with a decimal point. The assertion will fail if non-numeric characters other than a decimal point appear in the result.
Boolean	The result must be equal to "true" (not case sensitive by default) when the rule is equal to True for the assertion to succeed. If the result contains anything else—or is empty—then the assertion is falsified. Examples If the assertion is configured: "Proceed if ${var.result} is equal to false": The assertion will succeed if the result for ${var.result} is false, 123, abc, etc. The assertion will fail if the result for ${var.result} is true. If the assertion is configured: "Proceed if ${var.result} is equal to true": The assertion will succeed if the result for ${var.result} is true. The assertion will fail if the result for ${var.result} is anything but true.
Date/Time	The expression must either be a date/time variable or the result is a timestamp or a string that can be recognized by the Gateway. If the expression cannot be converted, this assertion will fail. If a date/time variable is specified in the expression and Date/Time is not selected as the Data Type, the Policy Manager will convert the variable into a string for comparison purposes. The variable will contain date/time information. These variables will behave similar to the built-in variables described in Date/Time Variables.

If using a multivalued context variable, select how you would like the variable handled.

Rule	Description
All values must pass	The Comparison assertion will succeed only if every value in the multivalued variable satisfies the conditions defined in the assertion. This setting is the default.
Any value must pass	The assertion will be successful if any of the multiple values meets the condition(s).
Compare first value only	The assertion will be successful if the first value meets the condition(s).
Compare last value only	The assertion will be successful if the last value meets the condition(s).
Fail assertion	The assertion will fail if a multivalued context variable is encountered. This setting should be used when multiple values are not expected.

Click [Add
] to add a new rule. You are prompted to select the type of rule:

Rule	Description
Simple Comparison	Compares the result against another value using basic operators (such as "less than", "greater than"). The value being compared to can be a number, string, or another context variable. If it is a string, you can enforce an exact case match by selecting the [Case Sensitive] check box. If the expression contains multiple values, then every value must satisfy the comparison. When using the Integer data type, it is best to perform the simple comparison against other integers. If comparing against a decimal value, be aware that the decimal value will be truncated into an integer for comparison purposes. For example, consider the following configurations for the assertion: "Proceed if ${var.result} is a Decimal Number and is less than 45.7", and ${var.result} returns 45. The assertion succeeds because 45 is less than 45.7. "Proceed if ${var.result} is an Integer and is less than 45.7", and ${var.result} returns 45. The assertion fails because 45 is not less than 45 (the decimal '45.7' is truncated to '45' as the data type is Integer and the comparison is between integers).
Number of Values	Verifies that the number of values in the result falls between the stated minimum and maximum. For expressions containing a single value, you can use Min=1, Max=1 to indicate that a value is "required", or Min=0, Max=1 to indicate that a value is "optional". Check the "Unlimited" box to set no limit to the maximum value.
Regular Expression	Matches the result against a constant regular expression. If the expression contains multiple values, then every value must match the regular expression. For a more powerful application of regular expressions in a policy, use the Evaluate Regular Expression Assertion.
String Length	Verifies that the length of the result, expressed as a string, falls between the stated minimum and maximum. If the expression contains multiple values, then every value must satisfy the length constraint. For example, if the expression result is "abcd" and a String Length rule stipulates that the minimum length is 5, then the assertion is falsified.

Click [OK
] when done.

Content feedback and comments

CA API Gateway 9.1

Compare Expression Assertion