Create XACML Request Assertion

The Create XACML Request assertion is used to build a valid XACML request and then place it in the specified target (request message, response message, or Message variable). The XACML request can then be used in the  or it may be routed to any other PDP (Policy Decision Point) for a decision.
gateway90
The 
Create XACML Request 
assertion is used to build a valid XACML request and then place it in the specified target (request message, response message, or Message variable). The XACML request can then be used in the Evaluate XACML Policy Assertion or it may be routed to any other PDP (Policy Decision Point) for a decision.
2
A XACML request is an XML fragment that conforms to the XACML (eXtensible Access Control Markup Language) specification.
A Request contains Attributes in each of the following four categories. By default, the Create XACML Request assertion will add each of these attributes under the root <Request> node. You may remove any that are not needed, provided that it's applicable to do so.
  • Subject:
     There can be one or more Subject elements, and each can be identified by a category URI.
  • Resource:
     XACML 1.0/1.1 must have exactly one Resource element in a request; XACML 2.0 may have more than one Resource element.
  • Action:
     There must be exactly one Action element in a request.
  • Environment:
     XACML 2.0 must have exactly one Environment element, while earlier versions can have 0 or 1 Environment element.
You should be familiar with the XACML specification before using this assertion to construct a XACML request. For more information, see www.oasis-open.org.
Using the Assertion
  1. 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.
  2. When adding the assertion, the XACML Request Properties automatically appear; when modifying the assertion, right-click 
    Create XACML Request 
    in the policy window and select 
    XACML Request Properties
     or double-click the assertion in the policy window. The assertion properties are displayed. 
  3. Complete the basic settings for the Request:
    • XACML Version:
       Choose the XACML version that the generated XACML request will use. The options are: 
      1.0
      1.1
      , and 
      2.0
      . (Note: The chosen version may affect the availability of certain options when building the request.)
    • SOAP Encapsulation:
       Choose the version of SOAP to use for encapsulation:
      • SOAP 1.1
        : The XACML <Request> element is contained in the Body element of a SOAP 1.1 envelope.
      • SOAP 1.2: 
        The XACML <Request> element is contained in the Body element of a SOAP 1.2 envelope.
      • None
        : The XACML request is not enclosed in a SOAP envelope. The Evaluate XACML Policy assertion will not need to remove the SOAP envelope in order to use it.
    • Message Output:
       Choose where to place the resulting XACML request: In the 
      Request
      Response
      , or a 
      Message Variable
       (context variable of type Message). If you choose to place it in a Message Variable, the variable does not need to exist beforehand—it will be created by this assertion. Do not enclose the variable with the "${ }" characters. 
  4. Configure each node as appropriate:
    Subject
    Resource
    Action
    Environment
    Context variables can be used in many settings when configuring a node. If during policy execution a referenced variable does not exist, the service policy will fail and a warning will be logged.
  5. Click [
    OK
    ]
     
    when done.
Configuring the Subject Node
XACML_Subject.PNG
The 
Subject
 node corresponds to the <Subject> element in a XACML request. Every XACML request must have at least one Subject node.
  • To add a new Subject node, right-click on the Request root node and then select 
    Add Subject
    .
  • To remove an existing Subject node, right-click on the Subject node and then select 
    Remove Subject
    . You cannot remove the last Subject node in a Request.
The Subject node has one setting:
  • Subject Category:
     This attribute describes the role that the Subject element plays in making the access request. If more than one Subject has the same Subject Category, then the Evaluate XACML Policy assertion will treat the contents of those Subject elements as if they were contained in the same Subject element.
Select the Subject Category from the drop-down list of standard attributes (as presented by OASIS). This field is optional.
The Subject node can contain the following nodes:
Attribute
Multiple Attributes
Configuring the Resource Node
XACML_Resource.PNG
The 
Resource
 node corresponds to the <
Resource
> element in a XACML request. A XACML 1.0 or 1.1 request has exactly one Resource node. A XACML 2.0 request may have more than one Resource nodes.
  • To add a new Resource node, right-click on the Request root node and then select 
    Add Resource
    .
  • To remove an existing Resource node, right-click on the Resource node and then select 
    Remove Resource
    . You cannot remove the last Resource node in a Request.
The Resource node has no settings.
The Resource node can contain the following nodes:
Resource Content
Attribute
Multiple Attributes
Configuring the Action Node
XACML_Action.PNG
The 
Action
 node corresponds to the <Action> element in a XACML request. Every XACML request has exactly one Action node.
The Action node has no settings.
The Action node can contain the following nodes:
Attribute
Multiple Attributes
Configuring the Environment Node
XACML_Environment.PNG
The 
Environment
 node corresponds to the <Environment> element in a XACML request. In XACML 1.0 or 1.1 requests, the Environment node is optional and may be deleted if not required. In a XACML 2.0 request, there must be exactly one Environment node.
  • To remove an Environment element from a XACML 1.0 or 1.1 request, right-click on the Environment node and then select 
    Remove Environment
    .
The Environment node has no settings.
The Environment node can contain the following nodes:
Attribute
Multiple Attributes
Configuring the Attribute Node
XACML_Subject_Attributes.PNG
The Attribute node corresponds to the <Attribute> element in a XACML request. This node can be created under all the major nodes:
Subject
Resource
Action
Environment
One or more Attribute nodes may be created under any of the major nodes.
  • To add an Attribute node, right-click a major node and then select 
    Add Attribute
    .
  • To remove an Attribute node, right-click the node and then select 
    Remove Attribute
    .
The Attribute node has the following settings:
Context variables may be entered in all fields in the Attribute node.
  • AttributeID:
     The AttributeId. Enter the value for the AttributeId or select from the drop-down list. This field is required. 
  • DataType:
     The data type of the contents of the <AttributeValue> element. Enter the Data Type or select from the drop-down list. This field is required. 
  • Issuer:
     This attribute specifies the Issuer. This field is optional. 
  • IssueInstant
     (XACML 1.0 and 1.1 only): The date and time at which the attribute was issued. The Issue Instant must be one of the following: 
    • blank
    • A context variable that resolves to a valid timestamp, either using one of the built-in variables 
      gateway.time.local, gateway.time.utc, request.time.local, request.time.utc,
       or a user-defined variable that contains a timestamp.
    • A manually entered date/time in the format: yyyy-MM-dd'T'HH:mm:ss[Z], where 'T' is a separator character and '[Z]' is the required time zone. 
The Attribute node can contain the following number of 
AttributeValue
 nodes depending on the version of XACML:
XACML 1.0:
 0 or 1
XACML 1.1:
 exactly 1
XACML 2.0:
 1 or more
Configuring the AttributeValues Node
XACML_AttributeValue.PNG
The AttributeValue node corresponds to the <AttributeValue> element. This node can only be created under the Attribute node.
There may be zero, one, or more AttributeValues for each Attribute node:
  • To add an AttributeValue node, right-click an Attribute node and then select 
    Add Attribute Value
    . Note that the number of AttributeValue nodes permitted depends on the version of XACML used (see above).
  • To remove an AttributeValue from an Attribute, right-click the AttributeValue node and then select 
    Remove Attribute Value.
XACML_AttributeValue_Settings.PNG
An AttributeValue node has the following settings:
Field
Description
Name
This is the name of an attribute to be placed into the <
AttributeValue
> Element, for example:
<AttributeValue ATTR1="value">
.
You may enter a context variable (of type String) that contains the name.
Value
This is the value of an attribute in the <
AttributeValue
> element; for example:
<AttributeValue att1="VALUE1">
You may enter a context variable (of type String) that contains the value.
AttributeValue Content
This is the text content of the <
AttributeValue
> element; for example:
<AttributeValue>Sample Content</AttributeValue>
Type the content directly into the text box. You may enter a mixture of static text and context variables of type String, Message, or Element. (Variables of type Element are created by the Evaluate Request XPath and Evaluate Response XPath assertions in the ".elements" context variable.)
Do not type XML code into the text box. If you do, the XML will not appear correctly in the XACML request. If you wish to use XML in the <
AttributeValue
>, add the XML fragment to a context variable first. For information on how to do this, see Set Context Variable Assertion.
Repeat for multivalued variables
(XACML 2.0 only)
Select this check box to have the assertion automatically create separate <AttributeValue> elements if multivalued context variables are present. This feature is available only in XACML 2.0.
For a detailed description of how this works, see
Working with Multivalued Context Variables in AttributeValues
below.
Editing actions
To add an AttributeValue Attribute:
  1. Click [
    Add
    ].
  2. Enter the
    Name
    and
    Value
    .
  3. Click [
    OK
    ].
To edit an AttributeValue Attribute:
  1. Select the row to edit.
  2. Click [
    Edit
    ].
  3. Modify the appropriate fields.
  4. Click [
    OK
    ].
To remove an AttributeValue Attribute:
  1. Select the row to delete.
  2. Click [
    Remove
    ].
Working with Multivalue Context Variables in the AttributeValues Node
Context variables can be used in any of the AttributeValue node settings: Name, Value, Content. These variables may be either single-value or multivalued variables. How the system responds depends on the XACML version and whether the 
Repeat for multivalued variables
 check box is selected. The various outcomes are described in the following table:
Effects of multivalued variables in AttributeValues
XACML Version
"Repeat" check box
Context variable encountered
Result
1.0 or 1.1
<not applicable>
Single-value
Creates a single <AttributeValue> element
1.0 or 1.1
<not applicable>
Multivalued
Concatenates the multiple values into a single value and then creates a single <AttributeValue> element. See
Concatenated Values
below for more details.
2.0
Not selected
Single-value
Creates a single <AttributeValue> element
2.0
Not selected
Multivalued
Concatenates the multiple values into a single value and then creates a single <AttributeValue> element. See
Concatenated Values
below for more details.
2.0
Selected
Single-value
Creates a single <AttributeValue> element
2.0
Selected
Multivalued
Creates a series of <AttributeValue> elements for the XACML request. The number of elements created is equal to the context variable with the
fewest
values. See
Multiple <AttributeValue> Elements
below for a detailed description.
Indexed Single Value
When indexing is used to reference a single value within a multivalued context variable (for example, 'variable[0]' for the first value, 'variable[1]' for the second value, etc.), the resulting single value is treated the same as a static value or a single-value context variable (in other words, it will be repeated for each <AttributeValue> element generated).
For more information on indexing, see 
Indexing Options
 under Working with Multivalued Context Variables.
Concatenated Value
s
When concatenation occurs, the values from a multivalued context variable are combined into a single value, separated by a comma and a space. For example, the variable "${multiVar}" contains the values 
red
green
, and 
blue
. The concatenated value, which is treated as a single value, will be:
red, green, blue
For more information, see 
Concatenation Options
 under Working with Multivalued Context Variables.
Multiple <AttributeValue> Elements
When the 
Repeat for multivalued variables
 check box is selected and a multivalued variable is encountered, a series of <AttributeValue> elements for the XACML request will be created. The number of elements created is equal to the multivalued context variable with the 
fewest
 values. For example, consider this example:
Name:
 ${ATTR1} contains the values ID1, ID2, ID3
Value:
 ${VALUE1} contains the values VALUE1, VALUE2, VALUE3
Content:
 ${CONTENT} contains the values CONTENT1, CONTENT2
Based on this example, two <AttributeValue> elements will be created because ${CONTENT} only has two values and this becomes the limiting factor:
<AttributeValue ID1="VALUE1">CONTENT1</AttributeValue> <AttributeValue ID2="VALUE2">CONTENT2</AttributeValue>
In this example, the values ID3 and VALUE3 will not appear in any <AttributeValue> element. The audit log will record the fact that not all values were used in the building of the XACML request.
If the AttributeValue node's dialog references more than one multi valued context variable, the context variable referenced with the fewest values from
all
the referenced variables becomes the limiting factor. For example:
${name1}
has 5 values,
${value1}
has 4 values, and
${content}
has 2 values. This will result in only two <AttributeValue> elements being created.
Single-value variables vs. multivalued variables with one value
It is important to note the differences between a 
single-value context variable 
vs.
 a multivalued context variable that contains only a single value
.
  • single-value variable
     will be treated the same as static text: it will be repeated for each <AttributeValue> generated. For example:
Name: ${attr1} contains the values ID1, ID2, ID3
Value: STATIC_VALUE
Content: ${content} contains the values CONTENT1, CONTENT2
Based on this example, two <AttributeValue> elements will be created (note the repetition of "STATIC_VALUE"):
<AttributeValue ID1="STATIC_VALUE">CONTENT1</AttributeValue> <AttributeValue ID2="STATIC_VALUE">CONTENT2</AttributeValue>
Note that ID3 is unused in this example.
  • multivalued context variable containing a single value
     will behave as expected: its single value becomes the limiting factor in the number of <AttributeValue> elements created.
For more information, see Working with Multivalued Context Variables.
Configuring the Multiple Attributes Node
XACML_XPath_Multiple_Attribute.png
Multiple Attributes is a special node that is designed to generate multiple <Attribute> elements in the XACML request, either by evaluating XPath expressions and/or multivalued context variables. For details on how multiple <Attribute> elements are dynamically generated, see 
How <Attribute> Elements are Dynamically Generated 
below.
One or more Multiple Attributes nodes may be created under any of the major nodes.
  • To add an Multiple Attribute node, right-click a major node and then select 
    Add Multiple Attributes
    .
  • To remove an Multiple Attribute node, right-click the node and then select 
    Remove Multiple Attributes
    .
XACML_XPath_Multiple_Attribute_Settings.png
The Multiple Attribute node has the following settings:
Field
Description
Message Source
Choose the message against which the XPath expressions will be evaluated.
Namespace Prefix /URI
These are the namespaces and prefixes that are used in any XPath expression.
XPath Base
If any text field is set to 'Relative XPath', enter the base XPath expression here. When the XPath Base is referenced from a text field set to 'Relative XPath', the expression is evaluated and the number of results found is considered when determining how many <Attribute> elements to create.
The Base XPath expression is executed if any field references it, including the AttributeValue field (except this field cannot define iteration).
Absolute XPaths are evaluated against the Document and are independent of the base XPath.
[Input type drop-down list]
The drop-down list next to the
AttributeID
,
DataType
,
Issuer
,
IssueInstant
, and
AttributeValue
fields dictates how the input in each field will be interpreted. It is important to select the correct option so that your input is processed correctly:
  • Regular:
    The input is interpreted as regular text. Context variables may be embedded within regular text and will be processed correctly. These context variables may be single value or multiple value. Fields of type 'Regular' will not be considered part of the logic for determining how many <Attribute> elements to create.
    (1) For XPath expressions, be sure to select one of the 'XPath' settings. If left on the 'Regular' setting, an XPath expression will be interpreted as text, not as an XPath expression. (2) If you are attempting to access the main/root MIME part of a message using ${
    variableName
    .mainpart}, be sure to select the 'Regular' setting. Other settings will not interpret the mainpart correctly. (3) Using ".mainpart" results in the variable being evaluated as a String, which will then be included as a text node in the XACML request. By comparison, if the variable is evaluated as a Message or an Element, it will be included as a XML fragment instead.
  • Absolute XPath:
    The input is interpreted as an absolute XPath expression, which will be evaluated directly against the Message Source document.
    (1) When entering an absolute XPath expression in any field other than
    AttributeValue
    , you must append "/text( )" to the end of the expression. (2) If the XPath expression evaluates to more than one node, only the first one is used. This event will be logged and audited at the INFO level.
  • Relative XPath:
    The input is interpreted as an XPath expression that is relative to the
    XPath Base
    expression specified above. If the XPath expression evaluates to more than one node, only the first one is used.
    When entering a relative XPath expression in any field other than
    AttributeValue
    , you must append "/text( )" to the end of the expression.
  • Context Variable:
    The input is a single context variable, with no surrounding text. The context variable may be either a single value or multivalued variable. If the variable is multivalued, then it will become part of the logic for determining how many <Attribute> elements are created. If the value is a single-value variable then it is the same as selecting 'Regular'. All fields accept context variables of type String. The
    AttributeValue
    field also accepts variables of type Message and Element. (Variables of type Element are created by the Evaluate Request XPath and Evaluate Response XPath assertions in the ".elements" context variable.)
    Multivalued context variables will generate multiple XACML elements.
    If you are attempting to access the main/root MIME part of a message using ${
    variableName
    .mainpart},
    do not
    use the 'Context Variable' setting. Use the 'Regular' setting instead
AttributeID
The expression to use to find the value for the
AttributeID
attribute of the <Attribute> element. Either select an expression from the drop-down list or enter an expression in the field.
DataType
The expression to use to find the values for the
DataType
attribute of the <Attribute> element. Either select a value from the drop-down list or enter a value in the field.
Issuer
Enter the expression to use to find the values for the
Issuer
attribute of the <Attribute> element.
IssueInstant
(XACML 1.0 and 1.1 only)
Enter the expression to use to find the values for the
IssueInstant
attribute of the <Attribute> element. This attribute specifies when the issuer issued this attribute. The Issue Instant may be one of the following:
  • blank
  • A context variable that resolves to a valid timestamp, either using one of the built-in variables
    gateway.time.local, gateway.time.utc, request.time.local, request.time.utc,
    or a user-defined variable that contains a timestamp.
  • A manually entered date/time in the format: yyyy-MM-dd'T'HH:mm:ss[Z], where 'T' is a separator character and '[Z]' is the optional time zone.
  • An XPath expression that returns the date/time in the above format.
A context variable or XPath expression is not evaluated until run time, thus the policy validator will not warn you during design time about incorrect date formats. If a value for IssueInstant is provided and it is invalid, it will cause the assertion to fail.
AttributeValue
Enter the expression to use to find the values for the <AttributeValue> element. Unlike the preceding three fields, this field can also accept context variables of type Message and Element.
Context variables of type Element are created by the XPath assertion in the .elements variable
For XACML 1.0 or 1.1, only one <AttributeValue> element will be created. For XACML 2.0, multiple <AttributeValue> elements will be generated under either of these conditions:
  • The 'AttributeValue' field is of type 'Context Variable' and a multivalued variable is specified.
  • The 'AttributeValue' field is of type 'Absolute XPath' or 'Relative XPath' that evaluates to a multi-node results.
If the AttributeValue could not be found, the <Attribute> element will be created with an empty <AttributeValue> element.
Fail assertion if evaluating any required fields results in not found
Select this check box if you want the assertion to fail if any of the following required elements could not be found during policy execution:
AttributeID
DataType
IssueInstant
(if applicable and supplied)
Clear this check box to ignore required elements that could not be found and continue generating <Attribute> elements. The assertion does not fail and the unfound elements are logged and audited at the INFO level and no <Attribute> element will be created for the current iteration.
Editing actions
To add a Namespace:
  1. Click [
    Add
    ].
  2. Enter the
    Prefix
    and
    URI
    .
  3. Click [
    OK
    ].
To edit a Namespace:
  1. Select the row to edit.
  2. Click [
    Modify
    ].
  3. Modify the appropriate fields.
  4. Click [
    OK
    ].
To remove a Namespace:
  1. Select the row to delete.
  2. Click [
    Remove
    ]. The row is deleted without further confirmation.
How <Attribute> Elements are Dynamically Generated
The Multiple Attributes node will generate multiple <Attribute> elements under either of these conditions:
  • If any of the 
    AttributeID
    DataType
    IssueInstant
    , or 
    Issuer
     fields is of type 'Context Variable' 
    and
     a multivalued context variable is entered.
  • If any of the 
    AttributeID
    DataType
    IssueInstant
    Issuer
    , or 
    AttributeValue
     fields is of type 'Relative XPath' 
    and
     the 
    XPath Base
     evaluates to a multi-node result.
The number of <Attribute> elements created is based on the multivalued context variable with the 
fewest
 values and the number of XPath multi-node results (whichever is lower). To see an example of how multivalued context variables can be the constraining factor, see "Multiple <AttributeValue> Elements" under 
Working with Multivalued Context Variables in the AttributeValues Node
 above. Just remember that for the <Attribute> element, the XPath node results is an additional constraining factor.
It is possible to reference a single value within a multivalued context variable. For more information, see "Indexed Single Value" under 
Working with Multivalued Context Variables in the AttributeValues Node 
above.
To learn more about the differences between a single-value context variable and a multivalued variable that just happens to contain one value, see "Single-value variables vs. multivalued variables with one value" under 
Working with Multivalued Context Variables in the AttributeValues Node
 above.
Configuring the Resource Content Node
XACML_ResourceContent.png
The Resource Content node corresponds to the <ResourceContent> element in the XACML request. This node may be optionally created under the <Resource> node.
  • To add a ResourceContent node, right-click the Resource node and then select 
    Add Resource Content
    .
  • To remove the ResourceContent node, right-click the node and then select 
    Remove Resource Content
    .
Resource Content node
The 
Resource Content
 node has the following settings:
Resource Content node settings
Field
Description
Name
This is the name of an attribute to be placed into the <ResourceContent> Element, for example:
<ResourceContent att1="value">
.
Value
This is the value of an attribute in the <ResourceContent> element; for example:
<ResourceContent att1="value1">
ResourceContent Content
This is the text content of the <ResourceContent> element; for example:
<ResourceContent>Sample text content</ResourceContent>
Type the content directly into the text box. This text field supports single or multi valued variables of type String, Message, or Element.
Editing actions
To add a ResourceContent Attribute:
  1. Click [
    Add
    ].
  2. Enter the
    Name
    and
    Value
    .
  3. Click [
    OK
    ].
To edit a ResourceContent Attribute:
  1. Select the row to edit.
  2. Click [
    Modify
    ].
  3. Modify the appropriate fields.
  4. Click [
    OK
    ].
To remove a ResourceContent Attribute:
  1. Select the row to delete.
  2. Click [
    Remove
    ].