search

OpenConext / OpenConext-pdp

OpenConext implementation of a XACML based PDP engine for access policy enforcement
Apache License 2.0
8 stars 8 forks source link

readme

OpenConext-pdp

Build Status codecov.io

OpenConext implementation of a XACML based PDP engine for access policy enforcement including a GUI for maintaining policies

Getting started

System Requirements

Create database

Connect to your local mysql database: mysql -uroot

Execute the following:

DROP DATABASE IF EXISTS pdpserver;
CREATE DATABASE pdpserver CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
CREATE USER 'pdpserver'@'localhost' IDENTIFIED BY 'secret';
GRANT ALL privileges ON `pdpserver`.* TO 'pdpserver'@'localhost';

CREATE DATABASE pdpserver DEFAULT CHARACTER SET latin1;
create user 'root'@'localhost';
grant all on pdpserver.* to 'root'@'localhost';

Building and running

The pdp-server

This project uses Spring Boot and Maven. To run locally, type:

cd pdp-server

mvn spring-boot:run -Drun.jvmArguments="-Dspring.profiles.active=dev"

When developing, it's convenient to just execute the applications main-method, which is in PdpApplication. Don't forget to set the active profile to dev otherwise the application uses the real VOOT client on the test environment.

The pdp-gui

cd pdp-gui

Initial setup if you do:

npm install

Add new dependencies to devDependencies:

npm install ${dep} --dev

To build:

npm run webpack

To run locally:

npm run local

Browse to the application homepage.

Testing

There are (slow) integration tests for PdpApplication where various decisions are tested against a full-blown running Spring app. See PdpEngineTest

If you want to test individual Policies with specific Request / Response JSON then use the (much faster) StandAlonePdpEngineTest

If you want to test policies against a full test system (e.g. the VM) then you can use the Mujina API to add or reset attributes:

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X PUT -d '{"value": ["hero"]}' "https://mujina-idp.vm.openconext.org/api/attributes/urn:mace:dir:attribute-def:eduPersonAffiliation"
curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST "https://mujina-idp.vm.openconext.org/api/reset"

Miscellaneous

Design considerations

The XACML framework works with policies defined in XML. We store the policies as XML strings in the database. However to effectively let XACML evaluate policies we need to convert them to the internal XACML format - see OpenConextEvaluationContextFactory.

Working with XML on the pdp-gui does not work well and we want to keep the pdp-gui simple. Therefore the PdpPolicyDefinition is used as an intermediate format for policies that is easy to work with for the pdp-gui and also enables the server to transform it easily into the desired - yet very complex - XML format.

Using the internal XACML Policy class hierarchy for communication back and forth with the client was not an option because of the cyclic dependencies in the hierarchy (and not desirable because of the complexity it would have caused).

Architecture

See this image

Security

Read this section for a in-depth security overview.

Policy limitations

The policies that can be created are limited in functionality:

Policy access

The Admin GUI has no restrictions in the accessibility of policies. The external API for trusted applications restricts access to policies based on the Identity Provider and the possible associated Service Provider(s) of the user and the corresponding Service and Identity Provider(s) of the policy. See this image for an overview of the logic applied in determining accessibility.

Local database content

We don't provide flyway migrations to load initial policies.

However if you start up the application with the spring.profiles.active=dev then all the policies in the folder OpenConext-pdp/pdp-server/src/main/resources/xacml/policies are added to the database. Do note that any other policies already in the database are deleted.

Manage

The pdp-server needs to access the metadata of Identity and Service providers from Manage. In production modus the content is read (and periodically refreshed) from the API exposed by Manage

In any other modus the content is read from the file system:

Configuration and Deployment

On its classpath, the application has an application.properties file that contains configuration defaults that are convenient when developing.

When the application actually gets deployed to a meaningful platform, it is pre-provisioned with ansible and the application.properties depends on environment specific properties in the group_vars. See the project OpenConext-deploy and the role pdp for more information.

For details, see the Spring Boot manual.

cUrl

The API can be tested with cUrl. See WebSecurityConfig for the security rules. When starting in dev modus the mock Shib headers are added automatically.

curl -ik -H "Content-Type: application/json" http://localhost:8080/pdp/api/internal/policies
curl -ik --user "pdp_admin:secret" -H "Content-Type: application/json" -H "X-IDP-ENTITY-ID: http://mock-idp" -H "X-UNSPECIFIED-NAME-ID: test" -H "X-DISPLAY-NAME: okke" http://localhost:8080/pdp/api/protected/policies
curl -ik -X POST --data-binary @./src/test/resources/xacml/requests/test_request_sab_policy.json --user "pdp_admin:secret" -H "Content-Type: application/json" http://localhost:8080/pdp/api/decide/policy

OpenAZ dependency

The OpenConext-pdp project heavily uses the PD framework https://github.com/apache/incubator-openaz. This repo is cloned in https://github.com/OpenConext/incubator-openaz-openconext and changes - e.g. distribution management, some bug fixes and minor optimizations - are pushed to openconext/develop branch in https://github.com/OpenConext/incubator-openaz-openconext.

To pull in changes from upstream run ./git-fetch-upstream.sh