HomeDownloadsUser GuideDevelopment

User Guide: Tutorial

This 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.

Overview

In 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:

  1. Setup a source of authority.
  2. Create a policy.
  3. Issue roles to users.
  4. Create an authorization service.

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 Policy

1. 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 Policy

In 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 the bouncycastle provider jar, "bcprov-*.jar")
Arguments:

  1. -policy
  2. Input PKCS12 keystore file
  3. Keystore password and private key password
  4. Number of valid days
  5. Output attribute certificate file
  6. Input policy xml file (UTF-8 encoding)

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 Certificates

Now 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:

  1. -role
  2. Input PKCS12 keystore file
  3. Keystore password and private key password
  4. Number of valid days
  5. Output attribute certificate file
  6. Comma separated list of type#role
  7. Holder distinguished name

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 Application

Now 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.

Overview

The application is structured as follows:

  • Access to the letterbox is ruled by a service.
  • The main entry point creates the authorization service.
  • There is an authorized service implementation that wraps access to the letterbox service and serves as PEP.

4. Creating your Authorization Service

Setup of the authorization service is performed as follows (see HelloWorld.java for detailed comments about the actual steps):

  1. First the SOA certificate is read.
  2. Next the policy decision point (PDP) is created with a certificate verifier that uses the SOA certificate.
  3. Then a subject repository (i.e. the repository of authenticated people, in our case John and Sara) is read.
  4. Based on the PDP and the subject repository the authorization service is built using an AuthorizationServiceBuilder.
  5. Finally an AuthorizedHelloWorldService using the actual service implementation and the authorization service is built.

Execution

Once 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.