JSecurity

Kasper,

I will be updating our documentation and quick-start guide with information about the WildcardPermission very soon. I apologize for the lack of documentation at the moment.

The WildcardPermission object can be used directly, or you can simply call the String-based permission methods on Subject or SecurityManager and WildcardPermission will be used under-the-hood. The WildcardPermission is very flexible and can support multiple levels of permission matching, but most people will probably follow some standard conventions.

In the simplest form, WildcardPermission can be used as a simple permission string. I could grant a user a "editNewsletter" permission and then check to see if the user has the editNewsletter permission by calling subject.isPermitted("editNewsletter"). This is (mostly) equivalent to subject.isPermitted( new WildcardPermission("editNewsletter") ) - more on that later. The simple permission string may work for simple applications, but it requires that I have permissions like "viewNewsletter", "deleteNewsletter", "createNewsletter". I can also grant a user "*" permissions, which means they have all permissions - but using this approach there's no way to just say a user has "all newsletter permissions".

For this reason, WildcardPermission supports multiple levels of permissioning. For example, I could restructure my previous example by granting a user the permission "newsletter:edit" - the colon in this example is a special character used by the WildcardPermission that delimits the next token in the permission. In this example, the first token is the domain that is being operated on, and the second token is the action being performed. Each level can contain multiple values - so I could simply grant a user the permission "newsletter:view,edit,create" which gives them access to perform view, edit, and create actions in the newsletter domain. Then I could check to see if the user has the "newsletter:create" permission by calling subject.isPermitted("newsletter:create") (which would return true).

In addition to granting multiple permissions via a single string, I can grant all permission for a particular "level" of the WildcardPermission. So if I wanted to grant a user all actions in the newsletter domain, I could simply give them "newsletter:*". Now, any permission check for "newsletter:XXX" will return true. It's also possible to use the wildcard token at the domain level (or both) - so I could grant a user the "view" action across all domains "*:view".

Another common usage of the WildcardPermission is to model instance-level Access Control Lists. In this scenario I use three tokens - the first is the domain, the second is the action, and the third is the instance I am acting on. So for example I could grant a user "newsletter:edit:12,13,18" In this example, assume that the third token is the system's ID of the newsletter. That would allow the user to edit newsletters 12, 13, and 18. This is an extremely powerful way to express permissions, since you can now say things like "newsletter:*:13" (grant a user all actions for newsletter 13), "newsletter:view,create,edit:*" (allow the user to view, create, or edit any newsletter), or "newsletter:*:* (allow the user to perform any action on any newsletter). To perform checks against these permissions, the application should include the instance ID in the permission check like so: subject.isPermitted( "newsletter:edit:13" ).

Of course, there is no limit to the number of tokens that can be used, so the sky is the limit in terms of ways that this could be used in your application. However, we'd like to standardize some common usages to help people get started and provide consistency in the JSecurity community.

One nice thing about WildcardPermissions being supported by default in JSecurity is that it makes it very easy to store complex permissions in the database - and also makes it very easy to represent permissions in JSP files, annotations, etc. - where a simple string representation is useful. Although WildcardPermissions are the default permission instance constructed from string representations, JSecurity uses a PermissionResolver internally to build a Permission object from Strings - so you could plug in any PermissionResolver you wanted for these features.

Finally, to get an idea of the behavior of WildcardPermission now, you may want to have a look at the WildcardPermissionTest unit test, which puts WildcardPermission through the paces and shows how some of the stranger edge cases are evaluated by the permission.

Please don't hesitate to ask any further questions you have. I hope this explained the basics of using this permission in your application. We will be updating the JavaDoc and documentation with this information and more examples very soon!