Overview

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

During policy evaluation and decision-making, information from various subsystems has to be taken into account. However, a Policy Decision Point (PDP) itself does not have access to any information unless this information has been supplied by an incoming event or specified in the policy. The PIP component is responsible for providing additional information to a PDP to support the decision making process.

In order to enable the PDP to find a PIP during decision making, the PIP has to register at the PMP. This registration is done automatically if the Spring version of the PIP is used.

The diagram below shows how a PDP requests information from a PIP component.

Communication between PDP and PIP diagram
Communication between PDP and PIPCommunication between PDP and PIP

A PIP 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 PIP 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 PIP

This section explains how to build a PIP web-app.

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 autoconfiguration support to configure the PIP 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

Each property is described in the table below :

Table 1. application properties

ind2uce.component.path

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

ind2uce.pmpUri

The URI of the PolicyManagementPoint to connect to.

ind2uce.es-id

Id of the enforcement scope this PIP belongs to.

ind2uce.es-type

Enforcement Type

externalServerUrl

URL used to reach the PIP from PMP Service. This URL can be used if PIP and PMP 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 PIP AutoConfiguration

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

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

The annotation @EnablePolicyInformationPoint loads the configuration to discover Beans with @PIPService.

PIPService

The PIP actions can be implemented in a Spring Bean that is annotated with @PIPService. As @PIPService is a sub-annotation of @Component, Spring will handle this class as a spring bean. For each PIPService class a developer has annotated, he has to specify the following:

  • componentId which is a unique id at the PMP; the prefix should be "urn:component:<scope>:pip:<id>", such as "urn:component:cs4:pip:authority"

  • path which is the path a PDP will use to call back the PIP, e.g., authority, which will yield {ind2uce.externalServerUrl}/{ind2uce.component.path}/pip/authority

The PIPService class contains the actions the PDP should be able to call during policy evaluation. Action methods are annotated with @ActionDescription, which has the following information specified:

  • return type (mandatory)

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

  • description (optional) of the purpose of the PIP 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) of the purpose of the parameter.

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

    • mandatory (default false) if the parameter is mandatory to use this PIP. 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 PIP Action Method in an PIPService:

@PIPService(componentId = "urn:component:cs4:pip:authority", path = "authority")
public class AuthorityPip {

  @Autowired
  private Repository repository;

  @ActionDescription(description = "Retrieves the authority (role) of a user")
  public String getAuthority(
        @ActionParameterDescription(name = "username", description = "The user the authority should be evaluated for.", mandatory = true) String username) {
    return repository.getRole(username);
  }
}

Providing health status data

Every PIP 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 PIP 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 PIPService.

Here is an example for a PIP health status method in a PIPService:

@PIPService(componentId = "urn:component:cs4:pip:authority", path = "authority")
public class AuthorityPip {

  @Autowired
  private Repository repository;

  @ActionDescription(description = "Retrieves the authority (role) of a user")
  public String getAuthority(
        @ActionParameterDescription(name = "username", description = "The user the authority should be evaluated for.", mandatory = true) String username) {
    return repository.getRole(username);
  }

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