Commit 1a64b68e authored by Raj Shah's avatar Raj Shah
Browse files

Release 3.2.65

parent fbb2a21c
<?xml version="1.0" encoding="UTF-8"?><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>de.fraunhofer.iese.ind2uce</groupId>
<artifactId>parent</artifactId>
<version>3.2.51</version>
</parent>
<version>3.2.65</version>
</parent>
<artifactId>core</artifactId>
<packaging>jar</packaging>
<version>3.2.51</version>
<name>IND2UCE :: Core</name>
<description>IND2UCE :: Core</description>
<url>https://git.iese.fraunhofer.de/ind2uce/core</url>
......@@ -23,51 +23,79 @@
<artifactId>slf4j-api</artifactId>
</dependency>
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-core</artifactId>
<groupId>org.slf4j</groupId>
<artifactId>jcl-over-slf4j</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
</dependency>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.5</version>
<groupId>com.jayway.jsonpath</groupId>
<artifactId>json-path</artifactId>
</dependency>
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
</dependency>
<dependency>
<groupId>org.reflections</groupId>
<artifactId>reflections</artifactId>
<version>0.9.10</version>
</dependency>
<dependency>
<groupId>org.hamcrest</groupId>
<artifactId>hamcrest-all</artifactId>
<scope>test</scope>
<version>${hamcrest.version}</version>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-entitymanager</artifactId>
<version>5.3.1.Final</version>
</dependency>
<dependency>
<groupId>commons-codec</groupId>
<artifactId>commons-codec</artifactId>
</dependency>
<dependency>
<groupId>com.rabbitmq</groupId>
<artifactId>amqp-client</artifactId>
</dependency>
<dependency>
<groupId>xerces</groupId>
<artifactId>xercesImpl</artifactId>
<version>2.11.0</version>
</dependency>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
</dependency>
<dependency>
<groupId>com.google.code.findbugs</groupId>
<artifactId>jsr305</artifactId>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>24.0-jre</version>
</dependency>
<dependency>
<groupId>xerces</groupId>
<artifactId>xercesImpl</artifactId>
<version>2.11.0</version>
</dependency>
</dependencies>
......@@ -83,7 +111,11 @@
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.2</version>
<configuration>
<attributes>
<project-version>${project.version}</project-version>
</attributes>
</configuration>
<executions>
<execution>
<id>generate-docs</id>
......@@ -130,7 +162,17 @@
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>cobertura-maven-plugin</artifactId>
<configuration>
<instrumentation>
<ignoreTrivial>true</ignoreTrivial>
</instrumentation>
</configuration>
</plugin>
</plugins>
</build>
......@@ -154,9 +196,9 @@
<scm>
<connection>scm:git:http://ind2uce-git.iese.de/ind2uce/dev/core.git</connection>
<developerConnection>scm:git:http://ind2uce-git.iese.de/ind2uce/dev/core.git</developerConnection>
<tag>3.2.51-RELEASE</tag>
<connection>scm:git:http://ind2uce-git.iese.de/ind2uce/dev/ind2uce.git</connection>
<developerConnection>scm:git:http://ind2uce-git.iese.de/ind2uce/dev/ind2uce.git</developerConnection>
<tag>3.2.65</tag>
</scm>
......@@ -187,4 +229,4 @@
<organizationUrl>https://www.iese.fraunhofer.de/</organizationUrl>
</developer>
</developers>
</project>
</project>
\ No newline at end of file
<div id="footer-text">
<a href="https://ind2uce.de/imprint.html" style="color:rgba(255,255,255,.8)">Imprint</a>
<br/>
<a href="https://www.iese.fraunhofer.de/en/data_protection.html" style="color:rgba(255,255,255,.8)">Privacy Policy</a>
</div>
\ No newline at end of file
= IND^2^UCE Policy Language Documentation - Version 3.2.46
= IND^2^UCE Policy Language Documentation
Fraunhofer IESE
:revnumber: {project-version}
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 4
:toclevels: 2
:sectlinks:
:stylesdir: ./css
:imagesdir: ./images
:stylesdir: ../css
:stylesheet: ind2uce.css
:linkcss:
:docinfo2:
[discrete]
== Short Links
++++
<script src="../js/jquery-1.11.3.min.js"> </script>
<script>$('#toc').prepend('<p><a href=".."><span class="fa fa-home"/> Home</a></p>')</script>
<p style="cursor:pointer;" onclick="$('#short-links').toggle()">Click here to show or hide short links that help you to directly jump to the element you are looking for.</p>
<div id='short-links' name='short-links'>
++++
* Policy: <<policy,<policy>>>, <<mechanism,<mechanism>>>, <<working-with-variables,<variableDeclaration>>>
* Conditions: <<if_elseif,<if>>>, <<if_elseif,<elseif>>>
* Decisions: <<then_else,<then>>>, <<then_else,<else>>>, <<allow,<allow>>>, <<inhibit,<allow>>>, <<modify,<modify>>>, <<execute,<execute>>>
* Variables: <<working-with-variables,<variable:boolean>>>, <<working-with-variables,<variable:number>>>, <<working-with-variables,<variable:string>>>, <<working-with-variables,<variable:object>>>, <<working-with-variables,<variable:list>>>
* Parameters: <<parameter-group,<parameter:boolean>>>, <<parameter-group,<parameter:number>>>, <<parameter-group,<parameter:string>>>, <<parameter-group,<parameter:object>>>, <<parameter-group,<parameter:list>>>
* Event References: <<event-group,<event:boolean>>>, <<event-group,<event:number>>>, <<event-group,<event:string>>>, <<event-group,<event:object>>>, <<pevent-group,<event:list>>>, <<eventHasParameter, <eventHasParameter>>>
* Constants: <<constant-group,<constant:boolean>>>, <<constant-group,<constant:number>>>, <<constant-group,<constant:string>>>, <<constant-group,<constant:object>>>, <<constant-group,<constant:list>>>
* PIPs: <<constant-group,<pip:boolean>>>, <<constant-group,<pip:number>>>, <<constant-group,<pip:string>>>, <<constant-group,<pip:object>>>, <<constant-group,<pip:list>>>
* Arithmetic Functions: <<arithmetic-functions,<plus>>>, <<arithmetic-functions,<minus>>>, <<arithmetic-functions,<multiply>>>, <<arithmetic-functions,<divide>>>, <<arithmetic-functions,<size>>>
* Boolean Functions: <<basic-boolean-functions,<and>>>, <<basic-boolean-functions,<or>>>, <<basic-boolean-functions,<xor>>>, <<basic-boolean-functions,<not>>>, <<basic-boolean-functions,<implies>>>, <<contains, <contains>>>, <<regex,<regex>>>
* Comparison Functions: <<comparison-functions,<less>>>, <<comparison-functions,<lessEqual>>>, <<comparison-functions,<equals>>>, <<comparison-functions,<greaterEqual>>>, <<comparison-functions,<greater>>>
* Date Functions: <<date-functions,<date>>>, <<date-functions,<day>>>, <<date-functions,<time>>>
* Event History: <<count, <count>>>, <<valueChanged, <valueChanged>>>, <<continuousOccurrence, <continuousOccurrence>>>, <<eventOccurrence, <eventOccurrence>>>, <<when,<when>>>
* Concatenation: <<concat, <concat>>>
* Cron Jobs / Time Triggered Events: <<timer,<timer>>>, <<timer,<event>>>
++++
</div>
<script>
$('#short-links').toggle()
</script>
++++
[[introduction]]
= Introduction
== Introduction
This documentation is about the definition of *privacy policies* regulating security-relevant system events.
This documentation is about the specification of *privacy policies with the IND^2^UCE policy language* regulating security-relevant system events.
The IND^2^UCE policy language is designed to express restrictions on data usage.
It is an XML-based language, based on *boolean logic, arithmetics, temporal information based on an event history*.
Furthermore, it allows for evaluations based on push (event-triggered) or pull (timer-triggered).
Connection to external systems for information retrieval is fully supported.
Enforcement decisions can be specified by means of *event inhibition, data modification using JsonPath (via PEP modifier plugins) and via the execution of actions (via PXP plugins)*.
Currently, our policy language supports the declaration of the following features:
[[eca]]
== The Event-Condition-Action Schema
* Inhibition of system events
* Modification of system events
* Execution of compensating actions
* Time interval based executions of mechanisms (cron jobs)
IND^2^UCE defines policies based security-relevant link:../api-core/de/fraunhofer/iese/ind2uce/api/policy/Event.html[*events*] that are occurring at a certain time in a system and are intercepted by *"Policy Enforcement Point" (PEP)*.
These events are sent to a *"Policy Decision Point" (PDP)*, which evaluates the policies and returns an link:../api-core/de/fraunhofer/iese/ind2uce/api/policy/AuthorizationDecision.html[*Authorization Decision*] based on the policies.
This decision is then enforced by the PEP.
Policies are based on Boolean logic and can make use of:
.Basic IND^2^UCE flow
image::PEP.png[cwidth="75%"]
* Data contained in the monitored event
* External data sources (e.g. LDAP)
* The history of events
Depending on the system and PEP type, events can highly differ.
In general, events contain:
A *policy* consists of one or more *mechanisms*.
Mechanisms are based on the *Event-Condition-Action* (ECA) schema:
If a system *event E* (<<<mechanism>>>) is fetched and *condition C* (<<if_elseif,<if> , <elseif>>>) is satisfied, then *action A* (<<then_else, <then>, <else>>>) is performed. The IND^2^UCE framework follows a blacklisting approach.
* An action name that defines the type of the event
* The time the event occurred
* A key-value list with event parameters
The following example shows an event we will refer to multiple times in this documentation.
It shows an event that is executed when someone reads bank transactions in a web service.
.Example Event for Banking
----
Event ID: "urn:action:banking-demo:get-transactions"
Time: 1533545200
Parameters:
- "customerID" (Number)
- "psd2Id" (Number)
- "transactions" (List of Transaction Objects)
----
IND^2^UCE policies are based on the *Event-Condition-Action* (ECA).
If a system *event E* (see above) is fetched and a *condition C* is satisfied, then *action A* (authorization decision) is performed.
IND^2^UCE follows a blacklisting approach.
Events that are not covered by policies are allowed by default.
.Example IND^2^UCE security policy: The following policy translates to "Inhibit event getTransactions if the external information source getCurrentHour returns a value below or equal to 15"
The following policy shows a simple example.
It translates to: "*Inhibit* the event *urn:action:banking-demo:get-transactions* if it is *after 3pm* (i.e., if the external information source getCurrentHour returns a value below or equal to 15)"
.Example IND^2^UCE security policy
[source,xml]
----
<policy id='urn:policy:banking-demo:getTransactions'>
<mechanism event='urn:action:banking-demo:get-transactions'>
<if>
<lessEqual>
<constant:number value='15'/>
<mechanism event='urn:action:banking-demo:get-transactions'> <!-- Event -->
<if> <!-- Condition -->
<less>
<pip:number method='urn:info:banking-demo:getCurrentHour' default='0'/>
</lessEqual>
<constant:number value='15'/>
</less>
<then>
<inhibit/>
<inhibit/> <!-- Action -->
</then>
</if>
</mechanism>
......@@ -52,65 +114,55 @@ Events that are not covered by policies are allowed by default.
----
[[language-elements]]
= Language Elements
== Policy Structure
A *<<policy,policy>>* consists of one or more *<<mechanism,mechanisms>>* that are based on the *Event-Condition-Action* (ECA) schema.
IND^2^UCE follows a blacklisting approach.
Events that are not covered by policies are allowed by default.
[[policy]]
== policy
=== Policy
The *<policy>* tag is the root element of an IND²UCE security policy. It has the following attributes:
The *<policy>* tag is the root element of an IND^2^UCE security policy. It has the following attributes:
[options='header']
.Policy attributes
[width="100%",cols="2,2,2,10",options="header"]
|======================================================================================================================================
|Attribute |Type |Required |Meaning
|id |URN |yes |The id of the policy, which must be unique. The id syntax is urn:policy:<scope>:<identifier>. The <scope> matches your solution ID and defines the range of effect. The <identifier> uniquely identifies the policy within the scope.
|name |String |no |A short name for the policy.
|description |String |no |A natural language description of the security policy.
|Attribute |Type |Required |Meaning
|id |URN |required |The unique id of the policy. The id syntax is urn:policy:<solution>:<identifier>. The <solution> matches your solution ID and defines the range of effect. The <identifier> uniquely identifies the policy within the scope.
|name |String |optional |A human readable (short) name for the policy.
|description |String |optional |A more detailed natural language description of the security policy.
|======================================================================================================================================
The *<policy>* tag must have at least one <<mechanism,<mechanism>>> child and can optionally contain <<variableDeclaration-group,variableDeclaration>> children.
.Example: The following policy describes the basic policy structure
[source,xml]
----
<policy id='urn:policy:banking-demo:notifyUser'>
<!-- optional -->
<variableDeclaration:string name='variableExample'>
...
</variableDeclaration:string>
<!-- at least one -->
<mechanism event='urn:action:banking-demo:notify-user'>
...
</mechanism>
</policy>
----
The *<policy>* tag must have at least one *<<mechanism,mechanism>>* child and can optionally contain *<<variableDeclaration-group,variableDeclarations>>*.
[[mechanism]]
== mechanism
=== Mechanisms
The *<mechanism>* describes a rule of a policy based on a monitored or intercepted event.
Depending on the policy specification and evaluation, the intercepted event can be allowed (event is released and executed normally),
A *<mechanism>* tag describes a rule of a policy based on a monitored, intercepted or <<timer,time triggered>> event.
An intercepted event can be allowed (event is released and executed normally),
modified (the event is changed according to the modifiers specified in the mechanism before it is executed) or
inhibited (the event is dropped and will not be executed).
If an event that is matching the event declaration is intercepted by a PEP, the event is sent to the PDP. The PDP checks whether the condition is satisfied.
If it is satisfied, the specified action is the decision of the PDP and will be enforced by the corresponding PEP.
An action of a non-satisfied condition will never be executed.
inhibited (the event is dropped and will not be executed). A time triggered or monitored event cannot be inhibited or modified - thus, are always allowed.
You can use <<execute, PXPs>> to react on these events.
The *<mechanism>* element has the following attributes:
[options='header']
.Mechanism attributes
[width="100%",cols="2,2,2,10",options="header"]
|======================================================================================================================================
|Attribute |Type |Required |Meaning
|event |PepEvent |Yes |Specifies the event by which the mechanism is triggered and for which the mechanism provides a security rule. The event id follows this pattern: urn:action:<scope>:<identifier>
|id |String |no |A unique id for the mechanism, used for logging purposes only.
|description |String |no |A natural language description of the mechanism.
|Attribute |Type |Required |Meaning
|event |URN |required |Specifies the event by which the mechanism is triggered and for which the mechanism provides a security rule. The event follows this pattern: urn:action:<solution>:<identifier>
|id |String |optional |A unique id for the mechanism, used for logging purposes only.
|description |String |optional |A natural language description of the mechanism.
|======================================================================================================================================
A *<mechanism>* can have the following child elements:
Mechanisms follow the *if-then-else* schema.
Thus, a *<mechanism>* tag can have the following children:
* <<if_elseif,<if>>>: A condition that leads to an authorization decision if it matches
* <<if_elseif,<elseif>>>: A condition that leads to an authorization decision if it matches and the previous if's did not match
* <<then_else,<else>>>: A condition that leads to an authorization decision if none of the previous if's matched
* <<if_elseif,<elseif>>>: A condition that leads to an authorization decision if it matches and the previous if or else-ifs did not match
* <<then_else,<else>>>: A condition that leads to an authorization decision if none of the previous if or else-ifs matched
* <<execute,<execute>>>: The unconditional execution of an action
.Policy Specification Rules
......@@ -124,20 +176,32 @@ A *<mechanism>* can have the following child elements:
.Policy Evaluation Rules
[IMPORTANT]
===============================
* A specified <<execute,<execute>>> inside the <<mechanism,<mechanism>>> tag is triggered by the event, independently from the satisfaction of a condition.
* A specified <<execute,<execute>>> as a direct child of <mechanism> the <<mechanism,<mechanism>>> tag is triggered independently of the satisfaction of a condition.
===============================
.Example: The following policy inhibits access to accounts and loggs the action
.Example: Inhibits access to transactions after 3pm and log the event
[source,xml]
----
<policy id='urn:policy:banking-demo:getAccounts' description='Inhibits access to accounts and loggs the action'>
<mechanism event='urn:action:banking-demo:get-accounts'>
<policy id='urn:policy:banking-demo:getAccounts' description='Inhibits access to transactions and loggs the action'>
<mechanism event='urn:action:banking-demo:get-transactions'>
<if>
<constant:true/>
<less>
<pip:number method='urn:info:banking-demo:getCurrentHour' default='0'/>
<constant:number value='15'/>
</less>
<then>
<inhibit/>
<execute action='urn:action:banking-demo:logNotification'>
<parameter:string name='message' value='Access attempt to account data after 3pm'/>
</execute>
</then>
</if>
<else>
<allow/>
<execute action='urn:action:banking-demo:logNotification'>
<parameter:string name='message' value='Access attempt to account data before 3pm'/>
</execute>
</else>
<execute action='urn:action:banking-demo:logNotification'>
<parameter:string name='message' value='Access attempt to account data'/>
</execute>
......@@ -146,32 +210,32 @@ A *<mechanism>* can have the following child elements:
----
[[if_elseif]]
== if, elseif
=== Conditions
The *<if>* and the *<elseif>* elements declare the condition that is evaluated each time the mechanism fires.
A condition can have the following child elements:
A condition must have the following child elements:
* A boolean-function (e.g. <<constant:true,<constant:true>>>, <<pip:boolean,<pip:boolean>>>)
* <<then,<then>>>: An authorization decision that the mechanism evaluates to if the condition matches
* A <<boolean-functions,boolean-function>> that defines the condition
* A <<decision, <then>>> that defines an authorization decision that the mechanism enforces if the condition matches
.Policy Specification Rules
[CAUTION]
===============================
* The <if> and the <elseif> must have exactly two child elements. One of these is the <<then,<then>>>. For more complex conditions, the Boolean operators (<<and,<and>>>, <<or,<or>>>, etc.) need to be used.
* The <if> and the <elseif> must have exactly one boolean function and one <then> child
===============================
.Policy Evaluation Rules
[IMPORTANT]
===============================
* If the <if> condition is not satisfied, then the first <elseif> condition will be evaluated.
* Only the one action specified in the <then> element of the *first* satisfied <if> or <elseif> condition will be executed.
* Only the <then> element of the *first* satisfied <if> or <elseif> condition will be enforced.
* If no condition is satisfied, then the action defined in the <else> element will be executed.
* If no condition is satisfied and no <else> element is specified, then the default action will be executed, which is <allow>.
* If no condition is satisfied and no <else> element is specified, then the event will be allowed (blacklisting).
===============================
.Example: Prohibits access to transactions after 3pm and loggs access to transactions between 2pm and 3pm
.Example: Prohibit access to transactions after 3pm and log access to transactions between 2pm and 3pm
[source,xml]
----
<policy id='urn:policy:banking-demo:getTransactions'>
......@@ -216,38 +280,47 @@ A condition can have the following child elements:
----
[[then_else]]
== then, else
=== Decisions
If the condition (<if> or <elseif>) is satisfied, the authorization decision has to be defined.
Therefore you can use the <<then,<then>>> element.
Decisions are defined inside a *<then>* element inside a <<if_elseif,condition>> (<if> or <elseif>), or in an *<else>* element, which is used if no condition is fulfilled.
These two elements can have the following child elements:
The two elements can have the following child elements:
* <<allow,<allow>>>: The event will be allowed and executed
* <<inhibit,<inhibit>>>: The event will be inhibited and not executed
* <<modify,<modify>>>: The event is modified before execution
* <<execute,<execute>>>: Independent of the event allowance, additional actions are executed
* <<allow,<allow>>>: The event will be allowed
* <<modify,<modify>>>: The event is allowed, but modified before further execution
* <<inhibit,<inhibit>>>: The event will be inhibited
* <<execute,<execute>>>: Additional actions are executed, independent of the event allowance
.Policy Specification Rules
[CAUTION]
===============================
* The <then> and the <else> elements must have at least one child element.
* Only one from the elements <allow>, <inhibit> and <modify> must be chosen.
* If none of the elements <allow>, <inhibit> and <modify> is specified, an implicit <allow> is executed.
* The <then> and the <else> elements must have at either
** exactly one <<allow,binary decision>> (<allow>, <inhibit>), or
** at least one <<modify, event modification>> (<modify>), and
** multiple <<execute,executes>>, which are executed in the specified order.
===============================
.Example: If role is banker *then* allow the event "get transactions" *else* inhibit
.Example: If the role of the user is "ROLE_USER" *then* modify task desricption, name and budget; *else* inhibit
[source,xml]
----
<policy id='urn:policy:banking-demo:checkRole>
<mechanism event='urn:action:banking-demo:get-transactions'>
<policy id='urn:policy:cs4:anonymizeTasksOfOthers'>
<mechanism event='urn:action:cs4:show-task'>
<if>
<equals>
<pip:string method='urn:info:banking-demo:checkRole' default=''/>
<constant:string value='Banker'/>
<pip:string method='urn:info:cs4:getRoleByUsername' default=''>
<parameter:string name='userId'>
<event:string eventParameter='user' default='' jsonPathQuery='$.userId'/>
</parameter:string>
</pip:string>
<constant:string value='ROLE_USER'/>
</equals>
<then>
<allow/>
<modify eventParameter='task' method='anagram' jsonPathQuery='$.description'>
<parameter:number name='percentage' value='100'/>
</modify>
<modify eventParameter='task' method='replace' jsonPathQuery='$.name'>
<parameter:string name='replaceWith' value='******'/>
</modify>
<modify eventParameter='task' method='delete' jsonPathQuery='$.budget'/>
</then>
</if>
<else>
......@@ -255,20 +328,24 @@ The two elements can have the following child elements:
</else>
</mechanism>
</policy>
----
[[allow, inhibit]]
=== allow, inhibit
[[allow_inhibit]]
==== Simple Decisions
Similar to basic access control mechanisms, an event can be allowed or inhibited.
The *<allow>* tag is part of a positive authorization decision. It informs the PEP that the intercepted event can be released for reaching its destination.
The *<inhibit>* tag is part of a negative authorization decision. It informs the PEP that the intercepted event must be dropped so that it never reaches its destination.
A reason can be added to both elements:
[options='header']
.Allow and inhibit attributes
[width="100%",cols="2,2,2,10",options="header"]
|======================================================================================================================================
|Attribute |Type |Required |Meaning
|reason |String |no |The description of the authorisation reason.
|Attribute |Type |Required |Meaning
|reason |String |optional |The description or rationale for the decision.
|======================================================================================================================================
.Example: If role is banker then *allow* the event "get transactions" else *inhibit*
.Example: If role is banker then *allow* the event "get transactions" else *inhibit* the event
[source,xml]
----
<policy id='urn:policy:banking-demo:checkRoleExample'>
......@@ -290,20 +367,26 @@ A reason can be added to both elements:
----
[[modify]]
=== modify
==== Complex Decisions with Event Modifications
In addition to basic access control mechanisms, IND^2^UCE allows the modification of the intercepted event.
The *<modify>* element is used to specify event modifications that the PEP must enforce before releasing the intercepted event.
It has the following attributes:
[options='header']
.Allow and inhibit attributes
[width="100%",cols="2,2,2,10",options="header"]
|======================================================================================================================================
|Attribute |Type |Required |Meaning
|eventParameter |String |yes |The name of the parameter that should be modified.
|method |String |yes |The name of the modification that should be applied (e.g., delete, anonymize). This depends on the capabilities of the PEP. Available modifier methods can be checked in your component overview and proposed by the policy editor.
|jsonPathQuery |String |no |If the parameter contains a complex object, modifications can be applied to specific parts of the data structure. For example a query "$firstName" of a parameter "user" will result in the modification of the first name of the user object only. Please refer to http://goessner.net/articles/JsonPath/ for more information about JsonPath.
|reason |String |no |The description why the event is modified.
|eventParameter |String |required |The name of the event parameter that should be modified.
|method |String |required |The name of the modification that should be applied (e.g., delete, anonymize). This depends on the capabilities of the PEP. Available modifier methods can be checked in your component overview and are proposed by the policy editor.
|jsonPathQuery |String |optional |If the parameter contains a complex object, modifications can be applied to specific parts of the data structure. For example a query "$.firstName" of a parameter "user" will result in the modification of the first name of the user object only.
|reason |String |optional |The description or rationale for the event modification.
|======================================================================================================================================
Child elements can be all elements of the <<parameter-group,parameter-group>>. The mandatory and optional parameters depend on the selected modifier method.
Some modification methods ("modifiers") require additional parameters.
For example, the "replace" modifier gives you the option to replace a certain string (either the event parameter or part of a complex object) with another String.
This String has to be provided as a <<parameter, parameter>>, as the following example shows.
Our editor will automatically add stubs for all required parameters.
.Example: Replace the bank code number before showing it
[source,xml]
......@@ -314,7 +397,7 @@ Child elements can be all elements of the <<parameter-group,parameter-group>>. T
<constant:true/>
<then>
<modify eventParameter='accounts' method='replace' jsonPathQuery='$.accounts.bankCodeNumber'>
<parameter:object name='replaceWith' value='XXXXX'/>
<parameter:string name='replaceWith' value='XXXXX'/>
</modify>
</then>
</if>
......@@ -325,95 +408,75 @@ Child elements can be all elements of the <<parameter-group,parameter-group>>. T
.JSONPath
[TIP]
===============================
* JSONPath is an instrument to query JSON structures. JSONPath uses special notation to represent nodes and their connections to adjacent nodes in a JsonPath path.
* Notation to get the value of a transaction: $.transactions.amount.value
JSONPath is an instrument to query JSON structures, similar to XPath for XML.
JSONPath uses special notation to represent nodes and their connections to adjacent nodes in a JsonPath path.
Plese refer to http://goessner.net/articles/JsonPath/ for a full documentation on JsonPath.
===============================
[[execute]]