Overview

This guide explains what a Policy Execution Point (PXP) is. It covers the topic of how to create and register a PXP at the Policy Management Point (PMP).

During policy specification, one can specify a set of actions that shall be taken when any particular event is fired. Along with the actions, one can specify what parameters to pass for executing these actions. In addition, the PXP provides a set of predefined execution methods that can be used in policies.

Before a PXP can be used, it needs to be registered at the Policy Management Point (PMP). In Spring projects, this can be done by using annotations. After registering the PXP at the PMP, the Policy Decision Point (PDP) will call the PXP when evaluating a policy to execute the actions specified in the policy.

The diagram below shows the process of requesting information from a PXP component by a PDP.

Communication between PDP and PXP diagram
Communication between PDP and PXPCommunication between PDP and PXP

In order to be callable by a PDP, the PXP has to provide a remote interface. This interface can be published via RMI, CORBA, HTTP and others if implemented. Currently, IND2UCE supports auto-registration if PXP is implemented as spring-boot app and it is using HTTP protocol. In this case a remote HTTP interface is automatically registered.

Developing a Spring PXP

This section explains how to develop a PXP Webapp.

Project dependencies

In addition to spring-boot-starter-web dependencies, the following dependencies have to be included in the pom.xml or gradle file.

    <dependency>
        <groupId>de.fraunhofer.iese.ind2uce</groupId>
        <artifactId>sdk</artifactId>
        <version>${ind2uce.version}</version>
    </dependency>

    <dependency>
        <groupId>de.fraunhofer.iese.ind2uce</groupId>
        <artifactId>sdk.spring</artifactId>
        <version>${ind2uce.version}</version>
    </dependency>

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.

    <dependency>
        <groupId>de.fraunhofer.iese.ind2uce</groupId>
        <artifactId>connectors.rest</artifactId>
        <version>${ind2uce.version}</version>
    </dependency>

Configuration with application.properties

Ind2uce uses the default Spring auto-configuration support to configure the PXP registration. Therefore, the following properties must be declared in the application.properties:

ind2uce.component.path= ind2uce
ind2uce.pmpUri= https://localhost:8080/ws
ind2uce.es-id= urn:es:cs4
ind2uce.es-type= urn:es-type:cs4
ind2uce.externalServerUrl= http://localhost:9551
management.security.enabled=true
endpoints.enabled=false

In the table below each property is described:

Table 1. application properties

ind2uce.component.path

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

ind2uce.pmpUri

The URI of the Policy Management Point to connect to.

ind2uce.es-id

Id of the enforcement scope this PXP belongs to.

ind2uce.es-type

Enforcement Type

externalServerUrl

URL used to reach the PXP from the PMP service. The URL can be used if PXP and PDP have been deployed to different domains/subnets.

endpoints.enabled

As this SDK uses the Health.class provided by the Spring Framework, the actuator package is used. It is enabled by default and creates various mappings. If not needed, it should be disabled.

management.security.enabled

Enables the actuator endpoint security, so that no sensitive data is exposed.

Enabling PXP AutoConfiguration

In order to tell Spring that it shall scan the beans for PXPServices, the Spring Boot Application class or a Configuration class of the PXP should be annotated with

@EnableAutoConfiguration
@SpringBootApplication
@EnablePolicyExecutionPoint
public class Application extends SpringBootServletInitializer {

The annotation @EnablePolicyExecutionPoint loads the configuration to discover Beans with @PXPService.

PXPService

The PXP` actions can be implemented in a Spring Bean that is annotated with @PXPService. As @PXPService is a sub-annotation of @Component, Spring will handle this class as a spring bean.

The PXPService class contains the actions the PDP should be able to call after policy evaluation.

Registering an action at the PMP requires that the following information is provided:

  • methodName (only required if the method name is not the same as the name used during policy specification

  • #return type (mandatory)(Can be primitive data-type or any Plain Old Java Object POJO)

  • description (optional): purpose of the PXP method

  • for each parameter annotated by @ActionParameterDescription, the following information is specified:

    • name (As Java drops the parameter names per default, this could not be introspected by the registration discovery)

    • description (optional): purpose of the parameter.

    • pattern (optional): This input should match the regex-pattern

    • mandatory (default false) If the parameter is mandatory to use this PXP. Be aware when setting parameters with primitive datatypes as optional. In that case the default value of the datatype is assigned when the function is called. Better use wrapper datatypes as Boolean for example.

Here is an example for a PXP Action Method in a PXPService:

@PXPService(componentId = "urn:component:cs4:pxp:sendmail", path = "sendmail")
public class SendMailPXP {

   @ActionDescription(description = "Send a mail with the defined content to the addressee.")
   public boolean sendMail(
       @ActionParameterDescription(name = "body") String body,
       @ActionParameterDescription(name = "subject") String subject,
       @ActionParameterDescription(name = "receiver_address") String rcpt_to,
       @ActionParameterDescription(name = "host", description = "Host of the mailserver") String host,
       @ActionParameterDescription(name = "port", description = "Port of the mailserver") String port,
       @ActionParameterDescription(name = "username", description = "Username for login to the mailserver") String user,
       @ActionParameterDescription(name = "password", description= "Password for login to the mailserver") String pwd) {

     Mail mailer = new Mail(user, pwd, host, port);
     mailer.setBody(body);
     mailer.setSubject("[IND2UCE] " + subject);
     mailer.setFrom("ind2uce@exla.de");
     String[] toArr = {rcpt_to};
     mailer.setTo(toArr);

     return new SendMail(mailer).call();
   }
}

Providing health status data

Every PXP is able to provide data regarding its health status to the PMP. This is done by providing a method with the signature String getHealth() within the PXP implementation.

The value returned by this method should be a String containing either

  • a boolean value like "true" or "false"

  • or the JSON representation of a Spring Health.class object, that can contain much more detailed information.

This health information is exposed as a JSON response of the Spring Health.class when calling the /health method of a PXPService.

Here is an example for a PXP health status method in a PXPService:

@PXPService(componentId = "urn:component:cs4:pxp:sendmail", path = "sendmail")
public class SendMailPXP {

   @ActionDescription(description = "Send a mail with the defined content to the addressee.")
   public boolean sendMail(/* ... */)
        // See implementation above
   }

   public String getHealth() {
     return new Gson().toJson(Health.up().build());
     // or: return "true";
   }
}