User Guide: TutorialThis page is a short tutorial about setting up your OpenPermis from scratch. For the meaning of the used terms and abbreviations please visit our Glossary. OverviewIn the following we are going to show how to implement a simple "Hello World" style example that uses OpenPermis. Our example features a postman called "John", a letterbox that has to be protected from curious users and from "Sara", an author that frequently deposits letters in the box. In order to get the example running we need to conduct the following steps:
To use this tutorial please have a look at the build file build.xml of the simple example in your distribution folder. The commands for the actual steps outlined below are included in the build file and everything you need to get the example running is included, so there is no need to issue the commands yourself. Certificates and Policy1. Setup your SOA (Source of Authority)Your SOA is the root of trust, it signs the policy, it issues roles to users, and it may also define subordinate AA's (Attribute Authorities), which are also able to issue roles. What you need is a public-private key pair for your SOA, in order to be able to sign certificates. You can use the Java Key and Certificate Management Tool - keytool, which is included in the Java Runtime Environment, for generating a self signed public key. Open a console and type the following command (everything on one line, formatting is only for better readability): keytool -genkey -storetype PKCS12 -storepass 123456 -keystore soa-keystore.p12 -alias mykey -keypass 123456 -sigalg "SHA1withRSA" -keyalg "RSA" -dname "cn=soa,o=post,c=ch" -validity 365 You generated a PKCS12 key store containing a private and public key for signing and verifying certificates with RSA. The generated private key is referenced by the alias "mykey". The key store and the private key are protected by the same password "123456". Your SOA certificate is valid for the next 365 days. Command for extracting the generated public key certificate from the keystore (again, the command is on one line and split only for better readability): keytool -export -alias mykey -storetype PKCS12 -keystore soa-keystore.p12 -storepass 123456 -file soa.cer 2. Creating your PolicyIn your policy you define which roles have the privilege to access your protected resources. Open the OpenPermis Policy Editor to write your own policy or open the following policy we've already prepared for you. Now you have to sign the policy with your SOA. In the editor click on "File -> Export Signed Policy", choose the previously created keystore file of your SOA, type the password "123456", and specify the output file of your signed policy. Alternatively you can use the ACM command line utility provided in the OpenPermis distribution. The utility is located in the bin folder of the distribution (it is named openpermis-acm-<version>.jar in the example below we simply call it acm.jar). The command line utility is an executable Java archive and takes the following arguments:
Example command for John (again, issue on one line, split only for better readability): java -jar acm.jar -policy soa-keystore.p12 123456 mykey 365 policy.ace policy.xml 3. Issue Roles to Users by Creating Role Attribute CertificatesNow that you have defined the policy which specifies the access to your protected resources, you want to give your users access to them. Therefore you have to bind roles (which are stated in your policy) to users. This binding is done by issuing a role attribute certificate. To create role attribute certificates you can use either the role assignment tool in the policy editor or the command line utility "acm.jar" provided in the OpenPermis distribution in "core/acm/". Arguments:
Example command (again, issue on one line, split only for better readability): java -jar acm.jar -role soa-keystore.p12 123456 mykey 356 john.ace "http://postRole#postman" "cn=john,o=post,c=ch" Your ApplicationNow that we have the resources for our application created we can write the actual authorization service. For the example we stick to a very simple rich client that includes the policy decision points and accesses the certificates itself. OverviewThe application is structured as follows:
4. Creating your Authorization ServiceSetup of the authorization service is performed as follows (see org.openpermis.examples.simple.HelloSimple for detailed comments about the actual steps):
ExecutionOnce we have an authorized service the actual execution of a request (i.e. accessing the letterbox) is pretty straightforward. Since the authorized service provides an implementation of the actual service you can simply call the desired method and the authorized service will throw an exception if permission is denied. In the example the last few lines of the main method perform the actual invocation of the service: ... try { service.collectLetters(principal); System.out.println("Collected Letter"); } catch (LetterboxException e) { System.out.println("<" + e.getMessage() + ">"); } ... The example will simply print out the result of the service invocation or show the exception message in case the permission is denied. Therefore executing the example with user "John" will print out "Collected Letter" while invocation with "Sara" will show an error (since she doesn't have permission to collect letters from the letterbox). This concludes the simple tutorial. For a more advanced usage of OpenPermis please have a look at the EJB and LDAP examples. |