HomeDownloadsUser GuideDevelopment

User Guide: Examples

Your Permis distribution includes an examples folder which contains all the examples listed below.

Example Structure

Care has been taken to create the examples as self-explanatory as possible. If appropriate each example includes:

  • readme.txt a short introduction to the example.
  • build.xml an ANT build file to simplify building and executing.
  • src/ the folder containing the actual example sources.
  • resources/ additional resources required for the example.

This chapter shortly explains how to install and run the examples. However if you want to run the examples we strongly advice you to check out and set up the integration project and to run its shell scripts first. So: go to integration before continuing with this page!

Simple

This example is explained in detail in the ten minute tutorial, however, you can quickly run it from both Eclipse or the distribution.

To run it from the distribution, go to the example's distribution directory and then execute 'ant' to generate the certificates and 'ant run' to run the example.

To run it from Eclipse execute './build.sh examples-simple.certs4ide' from the projects root and then execute the main method of the 'examples/simple/HelloWorld.java' file.

XACML

This example shows quickly how a PERMIS authorization service is created, which takes XACML-Requests and returns XACML-Responses.
A detailed description of the PERMIS XACML support can be found in section architecture xacml.

To run it from the distribution, go to the example's distribution directory and then execute 'ant compile' to compile and 'ant run' to run the example.

EJB

Example that shows how to separate the authorization service and the client using it as an EJB3 application.
The example includes all files necessary to build and test the application using a JBoss 5.x.

You will need an EJB server to compile and run this example. The example has been tested and pre-configured to work JBoss 5.x and consists of a simple EJB3 bean and a rich client.

Preparations

  1. Download and install a JBoss 5.x.
  2. Start the JBoss 5.x server.
  3. Make sure the server is up and running.
  4. Move the working directory of your terminal to the 'examples/ejb' folder of the distribution.

Compiling/Deploying the EJB

  1. Adjust the 'server.xml' file in the toplevel folder of the example.
  2. Execute 'ant deploy' to compile and deploy the EJB to your server.

Once the example is deployed you should see the following server output:

hello-permis/HelloWorldService/remote - EJB3.x Default Remote Business Interface
hello-permis/HelloWorldService/remote-org.openpermis.examples.ejb.server.HelloWorldServiceRemote - EJB3.x Remote Business Interface

Compiling/Starting the Client

  1. Execute 'ant client'.

A simple Swing-based GUI will give you the option to choose between user "Mike" or "Sten". The EJB is configured to grant permission to "Mike" while "Sten" does not have permission.

Modifying the Example

To keep the example small and simple the resources and configurations used are mostly hard-coded in the client and server classes. However since those classes are small and there are not many resources you should be able to modify the classes or use them as a starting point for your own implementation.

The resources for the PDP which is embedded in the EJB are stored in the 'resources' folder. The certificates read and the policy ace file used are hard-coded in the org.openpermis.examples.ejb.server.HelloWorldService.

The users offered at the client chooser are hard-coded in the client class org.openpermis.examples.ejb.client.HelloWorldClient.

The following configuration files might also be of interest to you:

  1. config/server/application.xml (template for the application.xml of the EJB)
  2. config/client/jndi.properties (client jndi.properties)

Build Commands

The following build targets are available:

all
Builds and deploys the EJB and starts the client
clean
Removes all build artifacts
compile
Compiles the client and the server classes
ear
Builds the server EAR
deploy
Deploys the EAR on the server
client
Runs the client

LDAP

This example shows how to use an LDAP server as your storage location for policies and certificates. An LDAP server is available in the 'integration' project. So check out the 'integration' project before running this example.

Analogously to the 'simple' example, you can run this example from both Eclipse or the distribution. The only difference is that this time the certificates are on the LDAP server.

Before starting the LDAP server you have to generate the ldif-file with the certificates. You can generate it from the project's root by executing './build.sh examples-ldap.ldif'. This generates the file 'fixture.ldif' in the directory 'target/eclipse/ldap'. You can also generate the file 'fixture.ldif' from the distribution by executing 'ant' in the example's distribution directory. This generates the file 'fixture.ldif' in the 'classes' directory of the example's distribution directory. When you start the ldap server make sure that you fill it with the data from 'fixture.ldif'. To expand the ldap schema with the PmiUser class you can use the file 99-user.ldif which you can find in the folder ldap/resources/org/openpermis/examples/ .