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
- 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 XACML Request Properties automatically appear; when modifying the assertion, right-clickCreate XACML Requestin the policy window and selectXACML Request Propertiesor double-click the assertion in the policy window. The assertion properties are displayed.
- 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, and2.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 theRequest,Response, or aMessage 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.
- Configure each node as appropriate:SubjectResourceActionEnvironmentContext 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.
- Click [OK]
Configuring the Subject Node

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 selectAdd Subject.
- To remove an existing Subject node, right-click on the Subject node and then selectRemove 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

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 selectAdd Resource.
- To remove an existing Resource node, right-click on the Resource node and then selectRemove 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

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

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 selectRemove Environment.
The Environment node has no settings.
The Environment node can contain the following nodes:
Attribute
Multiple Attributes
Configuring the Attribute Node

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 selectAdd Attribute.
- To remove an Attribute node, right-click the node and then selectRemove 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 variablesgateway.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 1XACML 1.1:
exactly 1XACML 2.0:
1 or moreConfiguring the AttributeValues Node

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 selectAdd 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 selectRemove Attribute Value.

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:
To edit an AttributeValue Attribute:
To remove an AttributeValue Attribute:
|
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
sWhen 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, ID3Value:
${VALUE1} contains the values VALUE1, VALUE2, VALUE3Content:
${CONTENT} contains the values CONTENT1, CONTENT2Based 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
.- Asingle-value variablewill 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.
- Amultivalued context variable containing a single valuewill 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

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 selectAdd Multiple Attributes.
- To remove an Multiple Attribute node, right-click the node and then selectRemove Multiple Attributes.

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:
|
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:
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:
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:
To edit a Namespace:
To remove a Namespace:
|
How <Attribute> Elements are Dynamically Generated
The Multiple Attributes node will generate multiple <Attribute> elements under either of these conditions:
- If any of theAttributeID,DataType,IssueInstant, orIssuerfields is of type 'Context Variable'anda multivalued context variable is entered.
- If any of theAttributeID,DataType,IssueInstant,Issuer, orAttributeValuefields is of type 'Relative XPath'andtheXPath Baseevaluates 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

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 selectAdd Resource Content.
- To remove the ResourceContent node, right-click the node and then selectRemove 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:
To edit a ResourceContent Attribute:
To remove a ResourceContent Attribute:
|