This guide explains what a Policy Enforcement Point (PEP) is and how it can be integrated with an existing system.

What is a PEP?

For any IND2UCE-enabled system, a PEP is a mandatory component. It is to be integrated into the system for interacting with IND2UCE. Its main purpose is to intercept events within the system, fetch a policy decision from the Policy Decision Point (PDP), and to modify the event according to the policy decision provided. The PEP directly interacts with the PDP, which in turn takes a decision depending on the policy specified and optionally on additional information provided by a Policy Information Point (PIP) or a Policy Execution Point (PXP). In a nutshell, the PEP sends a POJO (Plain Old Java Object) to the PDP and gets back an updated POJO that adheres to the specified security policies.

The diagram below shows the process of requesting a decision from the PDP.


When any event is intercepted by the PEP, it is packaged and sent to the PDP, which evaluates that event and returns an authorization decision along with modifications to be applied to the event. The PEP will enforce the decision and return the modified event to the system for further processing (or it drops the event if the PDP decided to deny its execution).

PEP Structure

A PEP is composed of several subcomponents. The following subcomponents are essential elements developers need to consider while integrating the PEP-SDK into a target system:

  1. Initialization & Registration

  2. Event

  3. Decision Enforcer

  4. PEP Interface Description

  5. Modifier Method

  6. ParameterList

  7. ComponentId

Below, we will provide exemplary snippets that illustrate in more detail how to integrate these components.

Initialization & Registration

During initialization, the PEP needs to know which Decision Enforcer, interface descriptor and modifiers are used. To this end, the PEP needs to register itself with the Policy Management Point (PMP). All information regarding modifier methods, interfaces and object structures (passed to the PDP) are passed to the PMP. This information is used for policy specification. Using java reflection, all this information is automatically registered. Details of this process are clarified in this page.


When a system wants to get a decision from a PDP, it needs to generate an Event and fire it via a PEP. The PEP returns an Observable<Event>, which can be subscribed to get the decision from the PDP. The event contains an encoded object, which is passed to the PDP for evaluation.

Decision Enforcer

The Decision Enforcers task is to enforce any decision on the given input parameter list. The JsonPathDecisionEnforcer is a concrete implementation of a DecisionEnforcer. The JsonPathDecisionEnforcer enforces the authorization decision on parameters using JsonPath. For a custom implementation, the DecisionEnforcer interface must be implemented and specified during PEP registration. Decision Enforcer also knows which modifier methods are registered.

Modifier methods

When an event is detected under the control of a preventive mechanism, the policy specifier has an option to modify parameters of that event so that security is not compromised. To do so, modifiers are used for changing the value of certain parameters of the event. By default, the following modifier methods are available; the methods evaluate the expression specified in the applicable policy and apply the following modifier methods

  • Anagram: Rearranges the letters of the given string by percentage specified in ParameterList of AuthorizationDecision

  • Append: Appends prefix or suffix as specified in ParameterList of AuthorizationDecision

  • Delete: Deletes those JSON keys that are specified in expression

  • Replace: Replaces result of expression by the value specified in ParameterList

These methods work on JsonPath expressions specified in a policy. Custom modifiers can be developed by implementing the ModifierMethod interface. This interface provides the doModification method, which is based on JsonPath. A DocumentContext is provided in the doModification method along with ParameterList and with the expression. Custom modifier methods can use this information to modify the event object. An exemplary modifier method is given below.


Along with AuthorizationDecision, the PDP also provides ParameterList. This list contains all parameters that can be used by modifiers.


Each system behaves like a Component, and it should be identified by a unique identifier. In general, the identifier has to be a urn, beginning with the keywords urn and component. An example is



  1. System objects are passed to DocumentationAPI which in turn converts them into events and puts them on the incoming event bus of PEP-SDK

  2. PEP-SDK intercepts the events and sends them to the PDP for decision making

  3. The Authorization Decision returned by the PDP is analyzed by PEP-SDK and enforced on the system objects

  4. The modified objects are again wrapped into events that are put on the outgoing event bus

  5. System can subscribe to these events via DocumentationAPI

The PEP is implemented using the following open source projects:

  1. RxJava is a Java VM implementation of ReactiveX (Reactive Extensions): a library for composing asynchronous and event-based programs by using observable sequences. Full documentation can be found here.

  2. JsonPath expressions always refer to a JSON structure in the same way as XPath expression are used in combination with an XML document. Full documentation can be found here.

The PEP is implemented following the Reactive manifesto. This paradigm has following benefits:

  1. event driven (react to events)

  2. scalable (react to load)

  3. resilient (react to failures)

  4. responsive (react to users)

The advantages of a reactive PEP is that it exploits the parallelism in modern processor architectures. By using reactive programming, we will end up having composable, call-back free code that avoids code sharing.

Using the RxJava extension, it is easy to compose results and to switch threads. Moreover, RxJava will also work with Java 8+ streams.

Note: Refer RxJava documentation for mode details


RxPEP is based on the publish-subscribe mechanism; It uses the rx.Observable<T> class. This Observable class implements the Reactive Pattern, and it provides methods for subscribing to the Observable as well as delegate methods to the various Observers. Detailed documentation for Observable can be found here.

When an event is fired, it is sent to the PDP via the PEP, and callbacks are registered for taking appropriate actions.

This methods are asynchronous in nature; they can be made synchronous by calling toBlocking() methods.

How to Integrate PEPs

PEP integration has two phases:

  1. PEP Registration: In this phase a DocumentationAPI interface is declared with all information required for the registration. During application boot-up time, this interface is registered at the PMP

  2. Event publish/subscription: In this phase, events are generated, then published and subscribed. System fires & subscribes to events using DocumentationAPI interface

PEP Registration

To register a PEP, add a maven dependency in the pom file:


In addition to these dependencies, one needs to add another dependency depending on the protocol used. IND2UCE by default uses HTTP protocol & following dependency is to be used for connection.


A DocumentationAPI interface must be specified for registering it with the PMP. A sample interface may look as follows:

@PEPServiceDescription(componentId = "urn:component:cs4:pep:reactivePEP")
@ProvidedModifiers(className = {
    AppendModifierMethod.class, ReplaceModifierMethod.class, AnagramModifierMethod.class, DeleteModifierMethod.class
public interface RxPEPDocumentationAPI {


The interface defines the annotation @PEPServiceDescription, which has the PEP componentId as a mandatory attribute. Note: ComponentId should be unique within the whole execution environment.

Annotation @ProvidedModifiers specifies the association with the event, which will be used to register the PEP at the PMP. @ProvidedModifiers will be initialized if it has a default constructor.

Each DocumentationAPI interface is configured as RxPEP using RxPEPFactory and is then used to register with the PMP.

ReactivePEP Registration

Here is an example for RxPEP generation and registration:

The RxPEPFactory.createRxPEP() method of RxPEPFactory is used for generating PEP as shown below:

ReactivePEP<RxPEPDocumentationAPI> rxPEP = RxPEPFactory.createRxPEP(RxPEPDocumentationAPI.class, pmpUri, aliveCheckUri, oauthCredentials);
RxPEPDocumentationAPI rxPepAPI;

If there was no error in the definition of the PEP documentation API (a RuntimeException with a reason is thrown if there were declaration errors), the ReactivePEP<T> is created successfully. pmpUri points to the URI of the PMP hosted in the target system and aliveCheckUri points to the URI of the PEP. The 'oauthCredentials' contain the client_id, client_secret and access_token_uri. This information is provided when the solution is initially created

The next step is to register the PEP at the PMP as shown below:

rxPEP.doRegisterAtPMP().subscribe((b) -> {
      // onNext registration status is pushed to subscription
      if( b.booleanValue())
        rxPepAPI = rxPEP.createInstanceAPI();

The methods specified above will generate an implementation for the specified DocumentationAPI interface and register with the PMP.

Events in ReactivePEP

Once the interfaces have been generated, the PEP needs to provide methods for policy enforcement. Using RxPEP, the return type of an enforcement method is Observable<Event> and by subscribing to that Observable<Event> one can access the decision.

The DocumentationAPI for RxPEP looks as follows:

@PEPServiceDescription(componentId = "urn:component:cs4:pep:ReactivePEP")
@ProvidedModifiers(className = { AppendModifierMethod.class, ReplaceModifierMethod.class })
public interface RxPEPDocumentationAPI {

  // arguments user and address will be used as parameter in event and event id will be "unr:action:cs4:show-user"
  @EventSpecification(scope = "cs4", action = "show-user")
  Observable<Event> enforceUserShow(@EventParameter(name = "user") User user, @EventParameter(name = "address") Address address);

  // arguments user will be used as parameter in event and event id will be "unr:action:cs4:show-project"
  @EventSpecification(scope = "cs4", action = "show-project")
  Observable<Event> enforceProjectShow(@EventParameter(name = "user") User user);

Explanation of the above annotations:

  • Annotation @EventSpecification is used for naming any event. It has two attributes: scope and action. These attributes are used to uniquely identify any event within the given system boundary.

  • Annotation @EventParameter is used for naming the object that is passed via the event.

Once these methods are declared, they can be accessed by the rxPepAPI object. The following example shows how the enforceProjectShow() interface method can be used in the target system using a rxPepAPI object

	.subscribe((event) -> {
		User user = (User) event.getValueForName("user");
		log.info("Modified user name is ", user.getName());
	}, (throwable) -> {
		log.info("Error occurred while processing enforceProjectShow" + throwable.getMessage());

These calls are non-blocking. A blocking call it can be issued with toBlocking() in the following manner:

	.subscribe((event) -> {
		User user = (User) event.getValueForName("user");
		log.info("Modified user name is ", user.getName());
	}, (throwable) -> {
		log.info("Error occurred while processing enforceProjectShow" + throwable.getMessage());

Modifier Method

The AuthorizationDecision of the PDP comprises a list of ModifierMethod items that have to be applied to given parameters of the event. Currently, the predefined ModifierMethods provided by IND2UCE mainly serve for demonstration purposes, and they are rather limited in functionality. If required, more sophisticated, system-specific modifier methods can be developed.

To create a custom modifier method, one needs to implement the 'ModifierMethod' interface and its methods. An example AnagramModifier is shown below:

public class AnagramModifierMethod implements ModifierMethod {
	 public AnagramModifierMethod() {

    public DocumentContext doModification(DocumentContext documentContext, String expression, ParameterList parameterList) {
        Object percentage = parameterList.getParameterValueForName("percentage");
        int percentageParam = percentage != null?Integer.parseInt(String.valueOf(percentage)):0;
        return this.anagram(documentContext, expression, percentageParam);

    @ActionDescription(description =
    	  "Jumbles up the letters of the word so string does not make any sense",
        pepSupportedType = String.class
    public DocumentContext Anagram(DocumentContext documentContext, String expression, @ActionParameterDescription(name = "percentage", description = "percentage of String to be modified (value between 0 and 100)", mandatory = true) int percentage) {
        final MapFunction blur = (o, configuration) -> this.scramble(o.toString(), percentage);
        return documentContext.map(expression, blur);

    public String getDisplayName() {
        return "anagram";

    private String scramble(String inputString, int count) {
        Random random = new Random();
        char[] a = inputString.toCharArray();

        final int limit = Math.round((a.length * (Math.min(count, 100) / 100f)));

		  for (int i = 0; i < Math.min(a.length - 1, limit); i++) {
        	  final int j = random.nextInt(Math.min(a.length - 1, limit));
        	  final char temp = a[i];
      		  a[i] = a[j];
      		  a[j] = temp;
    	  final String result = new String(a);

    	  return result;

Modification is based on JsonPath, so a DocumentContext from JsonPath is returned. DocumentContext contains a compiled version of an object in JSON format, and the doModification method has to modify the given object and return back a modified DocumentContext.

Explanation of the above example:

  1. doModification modifies the object

  2. getDisplayName denotes the name of modifier that is visible during policy specification

  3. expression is the JsonPath expression that is specified in the policy

  4. parameterList contains parameters that are specified in the policy

  5. DocumentContext is the compiled version of the object from JsonPath in JSON format

  6. @ActionDescription is used by the PEP to describe what this modifier method would do. Its attribute description specifies what it does and pepSupportedType specifies which data types are supported by this modifier

  7. @ActionParameterDescription specifies details of parameters that can be specified in the policy and passed in AuthorizationDecision. If the name attribute is not specified, then it takes the name of the parameter.

  8. MapFunction is taken from JsonPath, and it is used for modifying the object based on expression

Spring-boot Integration

For spring-boot based application, one can autowire RxPEP. DocumentationAPI would remain the same, but registration and initialization is handled by spring auto configuration.

The following dependency is required for adding spring-autoconfiguration along with the SDK:


Configuration with application.properties

IND2UCE uses the default spring autoconfiguration support to configure the PEP registration. Therefore, the following properties must be declared in the application.properties:

ind2uce.es-id= urn:es:cs4
ind2uce.es-type= urn:es-type:cs4

Each property is described in the table below :

Table 1. application properties


The common url-path used in RestController which is serving PEP requests.


The URI of the PMP to connect to.


Id of the enforcement scope.


Enforcement Type


URL used to reach the PEP from PMP Service. This URL can be used if PEP and PMP have been deployed to different domains/subnets.

Enabling PEP AutoConfiguration

In order to tell Spring that it shall scan the beans for PEPServices, the Spring Boot Application class or a configuration class of the PEP should be annotated with

@EnablePolicyEnforcementPoint(basePackageClasses = MyPEPDocumentationAPI.class)
public class Application extends SpringBootServletInitializer {


@EnablePolicyEnforcementPoint loads the configuration to discover interfaces with @PepInterfaceDescription and creates a bean by creating via Factory. As @EnablePolicyEnforcementPoint was defined you can inject the PEP via autowiring and call the defined event enforcement methods:

private MyPEPDocumentationAPI myPepApi;


To introduce IND2UCE into a target system, one definitely needs to integrate a PEP as a starting point. Along with that, a PIP and a PXP may be integrated as well, so that the overall system architecture looks as shown in the diagram:

PEP PXP PIP interaction via PDP

PEP integration comprises the following steps:

  1. Add IND2UCE dependencies

  2. Create DocumentationAPI

  3. Register PEP at PMP along with DocumentationAPI

  4. Publish & subscribe events via DocumentationAPI

PEP, ReactivePEP and SpringPEP are classified as below

Table 2. Feature matrix
Async Sync Auto-registration