User Guide: TutorialThis page is a short tutorial about setting up your Permis 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 Permis. 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 -sigalg "SHA1withRSA" -keyalg "RSA" -dname "cn=soa,o=post,c=ch" -keypass 123456 -keystore soa-keystore.p12 -storetype PKCS12 -storepass 123456 -validity 365 You generated a PKCS12 key store containing a private and public key for signing and verifying certificates with RSA. The key store and the first entry 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 -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 Permis 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 command line utility "acm.jar"
provided in the Permis distribution in "core/acm/acm.jar".
(Note: acm.jar depends on bcprov-jdk15-141.jar)
Example command for John (again, issue on one line, split only for better readability): java -jar acm.jar -policy soa-keystore.p12 123456 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. Unfortunately so far we have not yet developed a GUI tool for creating role attribute certificates, but in the meantime you can use the command line utility "acm.jar" provided in the Permis distribution in "core/acm/acm.jar". Arguments:
Example command (again, issue on one line, split only for better readability): java -jar acm.jar -role soa-keystore.p12 123456 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 HelloWorld.java 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 { System.out.println(service.getHelloMessage(name)); } catch (HelloWorldException 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 the service result while invocation with "Sara" will show an error (since she doesn't have permission to open the letterbox). This concludes the simple tutorial. For a more advanced usage of Permis please have a look at the EJB and LDAP examples. |