Your OpenPermis distribution includes an examples
folder which contains all the examples listed below.
Notes
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.
You have to execute 'ant' in the
'examples/common' directory before starting running the examples
The classes that are used in more than one example have been
moved to the 'examples/common' directory. To be able to run any example
you have first to go to that directory and execute the command 'ant' to
compile them!
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.
This example shows quickly how a OpenPermis authorization
service is created, which takes XACML-Requests and returns
XACML-Responses.
A detailed description of the OpenPermis 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.
Check out and run the integration project before
trying to run the server examples manually!
If you want to run the ejb or the ldap examples, which require
respectively a JEE and an LDAP server configured and running, we
strongly advice you to check out and set up the integration project and to
run its shell scripts first, since they already do it automatically. So:
go to integration before
continuing with this page!
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 taking advantage of the integration project
- check out the integration project
- run 'run-integration.sh' at the project's root once
- open 'run-javaee-integration.sh' in the 'src/javaee' directory of the integration project
- comment out the twenty last lines which shut down and erase the server
- run the modified script
- be aware of the fact that if you want to re-run the script to restart the server you now
have to first stop and remove the running server instance by executing manually the shutting
and deleting commands you commented out.
- if you accidentally removed the server directory before running the server stopping script
it contains, kill the server's java process.
Preparations not taking advantage of the integration project
- Download and install a JBoss 5.x.
- Start the JBoss 5.x server.
- Make sure the server is up and running.
- Move the working directory of your terminal to the
'examples/ejb' folder of the distribution.
- Adjust the 'server.xml' file in the toplevel folder of the
example.
- 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
- Execute 'ant client'.
A simple Swing-based GUI will give you the option to choose
between user "john" or "sara". The EJB is configured to grant permission
to "john" while "sara" 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:
- config/server/application.xml (template for the
application.xml of the EJB)
- 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
This example shows how to use an LDAP server as your storage
location for policies and certificates. You can run this example from
the IDE by executing the class HelloLdap or from the distribution
by going to the 'examples/ldap' directory and by executing first 'ant'
ant then 'ant run'.
Both ways of executing the example requires the LDAP server to be
configured and running. To configure and start the LDAP server follow the following steps:
- check out the integration project
- run 'run-integration.sh' at the project's root once
- open 'run-ldap-integration.sh' in the 'src/ldap' directory of the integration project
- comment out the eight last lines which shut down and erase the server
- run the modified script
- be aware of the fact that if you want to re-run the script to restart the server you now
have to first stop and remove the running server instance by executing manually the shutting
and deleting commands you commented out.
- if you accidentally removed the server directory before running the server stopping script
it contains, kill the server's java process.