Evaluate XACML Policy Assertion

gateway90
 
 
The 
Evaluate XACML Policy 
assertion evaluates a XACML policy and renders an authorization decision for a resource, which will be granted based on the set of attributes found in a XACML request. The XACML request can be created using the Create XACML Request Assertion.
The Evaluate XACML Policy assertion can retrieve the XACML request from a request or response message, or a context variable. After rendering the XACML request attributes against the XACML policy, the resulting decision can be placed either into the response message or a message context variable. The XACML policy can be configured in advance or the assertion can monitor a URL and download a new policy periodically.
The "XACML request" is also known as the "XACML decision request".
XACML Policy Validation
The Evaluate XACML Policy assertion will attempt to validate any XACML policy entered when the [
OK
] button is clicked. However, the assertion cannot validate a XACML policy under these circumstances:
  • The invalid policy is retrieved from a monitored URL.
  • The invalid policy (or policy fragment) is in a context variable that has been set prior to the Evaluate XACML Policy assertion.
In these cases, the invalid policy will be detected only during policy execution, with an error being logged.
Be aware that the Evaluate XACML Policy assertion will fail if you attempt to import a policy that contains an empty Description element, for example:
<Description/>
or
<Description></Description>
You should be familiar with the XACML policy language and what constitutes a valid policy before using this assertion to process a XACML request.
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 Policy Properties automatically appear; when modifying the assertion, right-click 
    Evaluate XACML Policy Properties 
    in the policy window and select 
    XACML Policy Properties
     or double-click the assertion in the policy window. The assertion properties are displayed. 
  3. Configure the properties as follows:
    Setting
    Description
     
    Message Source 
     
    Indicate where to get the XACML request: 
    Default Request
    Default Response
    , or from a 
    Context Variable
     that has been defined earlier in the policy (for example, using the Set Context Variable assertion). If using a context variable, it must be of type Message and its Content-Type should be 'text/xml'.
     
    SOAP Encapsulated?
    (for message)
    Select this check box if the XACML request is encapsulated in the Body element of a SOAP envelope.
    If this check box is selected, the XACML request must be a SOAP message, otherwise the assertion will fail.
     
    Response Target
     
    Indicate where to place the XACML PDP response: in the 
    Default Response
    ,
     Default Request
    , or in a 
    Message Variable
     (context variable of type Message). The variable does not need to exist beforehand—it will be created by this assertion. The 
    Message Variable
     field is enabled if 'Message Variable' is selected.
     
    SOAP Encapsulated?
    (for response)
    Select this check box to encapsulate the XACML PDP response in the Body element of a SOAP envelope.
     
    Message Variable 
     
    This field is used only if the 
    Response Target
     is 'Message Variable'.
    Enter the name of the variable to be created. You do not need to enclose the variable with the "${ }" characters.
     
    Policy Location
     
    From the drop-down list, specify the location of the XACML policy:
    •  
      Configure in advance:
       You are entering the policy in this assertion.
    •  
      Monitor URL for latest value:
       The 
      API Gateway
      will obtain a policy from a URL that is monitored periodically for changes.
     
    XACML Policy - Configure in advance 
     
    If you chose to configure the policy in advance, you have three different options:
    1. Type or copy/paste the XACML policy code directly into the code window. The policy code may contain context variables (see below).
    2. Click [
      Fetch from URL
      ] to enter an URL for the 
      API Gateway
      to retrieve the policy.
      To configure options for the URL (for example, to specify the credentials, SSL, or proxy options), click [
      HTTP Options
      ] to open the Manage HTTP Options dialog.
      Unlike the "Monitor URL" option, the "fetch" option does not monitor the URL and the policy is only downloaded once at policy design time.
    3. Click [
      Fetch from File
      ] to insert the policy code from a text file that you specify.
    You may edit a policy entered using the "fetch" options if necessary.
    The XACML policy maximum size is controlled by the 
    xacml.pdp.maxDownloadSize 
    cluster property.
     
    Using context variables in XACML policy code
     
    The XACML policy code may contain String values or context variables of type Message that contain XACML policy fragments or the entire XACML policy.
     
    Examples:
     
    •  
      ${variableContainingPolicy}
       is entered into the code window, where this previously defined context variable contains the entire XACML policy to use
    • A XACML policy is mostly configured in advance, with context variables representing policy fragments to be resolved at run time:
    <Policy...> <Target> ... </Target> <Rule...> ${stringVariable} </Rule> </Policy>
    Here is another example of simple text replacement:
    <Rule RuleId="ReadRule" Effect="${permitDecision}">
    where "${permitDecision}" was previously defined with a value of "Permit".
    Note the following when using context variables in a XACML policy:
    • If the context variable contains an entire SOAP envelope, you must use an XPath expression to extract the policy itself (i.e., extract the "<Policy>" element) to a second context variable. For more information, see the Evaluate Response XPath Assertion.
    • If a context variable of type Message contains the XACML policy as XML (either full policy or fragment), you must use the 
      ${variableName.mainpart}
       part of the context variable otherwise the assertion will fail.
    For context variables of types other than Message, the 
    mainpart
     part is not required. For more information on the various data types, see Context Variables.
     
    XACML Policy - Monitor URL for latest value
     
    If you chose to monitor a URL for the latest value, enter the URL here. The URL may contain context variables that will be resolved at run time.
    The time interval is set by the cluster property 
    xacml.pdp.policyCache.maxAge
    . The default value for this cluster property is 300000 milliseconds (5 minutes). When the Evaluate XACML Policy assertion is processed within the policy, the policy is re-downloaded if the cached policy is older than the value of this cluster property.
    To configure options for the URL (for example, to specify the credentials, SSL, or proxy options), click [
    HTTP Options
    ] to open the Manage HTTP Options dialog.
    The XACML policy maximum size is controlled by the 
    xacml.pdp.maxDownloadSize 
    cluster property.
     
    Fail Assertion if decision is not 'Permit'
     
    A PDP response can be any of the following:
    Permit
    Deny
    Indeterminate
     (an error occurred or some required value was missing, so a decision cannot be made)
    Not Applicable
     (the request can't be answered by this service)
    Select this check box to fail the assertion if the PDP response is anything other than 
    Permit
    . This is useful in scenarios where the policy acts as both a PEP (Policy Enforcement Point) and the PDP (Policy Decision Point). If the decision is not Permit, the policy can be configured to fail and you do not need to use an XPath expression to extract the result.
    Clear this check box to never fail the assertion, regardless of the PDP response.
  4. Click [
    OK
    ]
     
    when done.