URLPermission

URLPermission

This permission is one possible way to protect webapp resources, but is NOT the only one. you can represent webapp resources by other java.security.permission subclasses, and handle them with jGuard too.

you can also mix URLPermission with other ones to protect your webapp.

Description

this permisison represents the right to access through an URL to a resource on a webapp.

Build an URLPermission

URLPermission has got two constructors:

• one single argument constructor required by the Abstract Permission class

public URLPermission(String name)

this constructor cannot be used 'alone'. you should use the method setActions too to complete the object.

• one two arguments constructor

public URLPermission(String name,String actions)

the name parameter permits to add to the newly created permission, a custom name to remind it easily.

the actions parameter is a string which contains a list of actions separated by ','(this constructor is required by the BasicPermission abstract class).

here are the corresponding actions:

• uri
• scheme or protocol (optional, but required if description is present)
• http method (optional), among DELETE,GET,HEAD,OPTIONS,POST,PUT,TRACE, or ANY(all methods are authorized)

• description (optional)

Usage

To use an URLPermission, basically you deal with two methods: implies() and equals()

implies()

When you create an URLPermission, its URI can be, for example, in the form "http://someurl.domain" or "/someurl.do".

However, you probably want to use GET parameters on that URLs, like "http://someurl.domain?param1=value1¶m2=value2...". Here is the "trick" of URLPermission. When you define a base URL for a permission, any permission derived from it will be implied. If you have access to the base url "http://someurl.domain", certainly you must have access to the derived "http://someurl.domain?param1=value1".

The signature of implies() is:

boolean implies(Permission p)

Let's call basePerm the base URLPermission, and derivedPerm the derived one. Using the URLs presented before, if you execute:

basePerm.implies(derivedPerm)

It will return true.

In another example, if you have an URLPermission called perm1, with the URI http://webapp/someurl.do, and another called perm2, with the URI http://webapp/anotherurl.do:

perm1.implies(perm2)

Will return false, since perm2 cannot be derived from perm1.

equals()

URLPermission has an own implementation of equals(), that tests if a given URL is equals to the present one. To be equals, the URL must have its name and URL (including parameters) with the same values of the permission being compared.

For example, if you define 2 URLs as following:

URLPermission perm_1 = new URLPermission("url_1","http://someurl.domain/path1?param1=a¶m2=b");

URLPermission perm_2 = new URLPermission("url_2","http://someurl.domain/path1?param1=a¶m2=b");

Then:

perm_1.equals(perm_2)

Will return false, because perm_1 has a different name of perm_2 (url_1 != url_2).

note that parameters order doesn't affect the equals mechanism on jGuard.

URLPermission perm_1 = new URLPermission("url_1","http://someurl.domain/path1?param1=a¶m2=b");

URLPermission perm_2 = new URLPermission("url_1","http://someurl.domain/path1?param2=b¶m1=a");

Then:

perm_1.equals(perm_2) return true

using the star operator

when you define URLPermissions in your web applications, you can think that this work is tedious: on big webapps, you can have to create many URLPermissions. a trick to reduce the number of URLPermissions is to use the star operator ,which implies all the URI with the same starting sequence and any characters placed after the last character before the star.

URLPermission perm_1 = new URLPermission("url_1","http://someurl.domain/path1*");

URLPermission perm_2 = new URLPermission("url_2","http://someurl.domain/path1234");

perm1.implies(perm2) return true

and:

URLPermission perm_1 = new URLPermission("url_1","http://someurl.domain/pat*h1");

URLPermission perm_2 = new URLPermission("url_2","http://someurl.domain/path99999h1");

perm1.implies(perm2) return true

so, in conclusion, the trick is to give a good attention on url naming.

URL parameters

If the URL permission is defined with a uri with no query part, the permission implies any permission with parameters.

URLPermission perm_1 = new URLPermission("url_1","http://someurl.domain/path");

URLPermission perm_2 = new URLPermission("url_2","http://someurl.domain/path?param1=a¶m2=b");

perm1.implies(perm2) return true

If the uri of the URLPermission contains a query part, the permission implies only the permissions having the exact same parameters

URLPermission perm_1 = new URLPermission("url_1","http://someurl.domain/path?param1=a");

URLPermission perm_2 = new URLPermission("url_2","http://someurl.domain/path?param1=a¶m2=b");

perm1.implies(perm2) return false

In order to allow at least the permission having the good parameter defined but any values for any other parameter, use &* at the end of the query part fo the url

URLPermission perm_1 = new URLPermission("url_1","http://someurl.domain/path?param1=a&*");

URLPermission perm_2 = new URLPermission("url_2","http://someurl.domain/path?param1=a¶m2=b¶m3=c");

perm1.implies(perm2) return true

Stars can also be used in parameter names or values definition just as in path

URLPermission perm_1 = new URLPermission("url_1","http://someurl.domain/path?param1=a¶m2=*&pa*3=c");

URLPermission perm_2 = new URLPermission("url_2","http://someurl.domain/path?param1=a¶m2=b¶m3=c");

perm1.implies(perm2) return true

and what's about star symbol in our url?

URL can contains the star , without any signification. so, to include it in your url, you have to double your star.

URLPermission perm_1 = new URLPermission("url_1","http://someurl.domain/path1*");

this url will be used by jGuard like a regexp character.

URLPermission perm_1 = new URLPermission("url_1","http://someurl.domain/path1**");

but this url won't be used by jGuard like a regexp character, and will be evaluated like a url with only one star symbol.

what's about URLPermission and my webapp?

the star operator will not have some impact on the web framework you use (i.e Struts or another one). AccessFilter handle all the http user requests, and handle any trick on star characters. so, you can use any star character in your urls without problems outside jGuard configuration.