Critical issues will be fixed for 0.4.x, feature development only for 0.=
6.x versions. Versions before 0.4.0 are not maintained anymore. 0.4.0=
introduced fully Tapestry-style configuration and performance improvements=
.

=20

=20

=20

Overview

Enforcing security by implementing security checks in your application c=
ode is labor-intensive and a potentially dangerous practice as you can very=
easily miss a check and leave a big security hole open. Standard container=
-managed authentication and authorization was created to address this issue=
, but it's based purely on roles and URLs, and as such, is typically too co=
nstricting for modern web applications. With Tapestry 5, it's relatively ea=
sy to get started with securing your application by creating custom filters=
and dispatchers, but really, every user of Tapestry shouldn't need to crea=
te their own security framework. Developing comprehensive, proven bullet-pr=
oof security framework is difficult and time consuming. Tynamo's tapestry-security is a comprehensive security module that pro=
vides tight integration with Apache Shiro, an established, high-performing =
and easy-to-use security framework for Tapestry applications.

Using security

There are several aspects to providing security. Technically you can eit=
her hide functionality from user's view, visibly disable or lock certain fu=
nctionality or display errors when user tries accessing forbidden resources=
or operations. Security can be enforced at different integration points: f=
or example, you may restrict users' access to certain URLs, secure access t=
o the data itself or make specific checks in an operation of the controllin=
g page class or service before executing certain functionality. Tapestry-se=
curity module supports all these different types of authorization mechanism=
s.

To use the feature, you need to add the following dependency to your pom=
.xml:

Apache Shiro, the security framework that tapestry-security is based on,=
is modular and extensible, but to get started, you need to understand just=
three key Shiro concepts: realms, filters and security configuration. A realm is responsible for a=
uthenticating and authorizing users, so you at least need to configure a re=
ady-made realm, or, if you are authenticating users against your own custom=
database, likely need to implement your own custom realm. Typically, in yo=
ur AppModule you provide a realm configuration such as:

Obviously, if your Realm needs to use other Tapestry services, you could=
let Tapestry build your Realm implementation with @Autobuild and in=
ject it as an argument to your WebSecurityManager contribution method. If y=
ou create a first-class Tapestry IoC service out of your realm (you can but=
there should be very little need), make sure you identify your rea=
lm to the Tapestry with the right super interface=
. For example, if your realm is authorizing users, the interface to use is =
Autho=
rizingRealm - if you claimed that the service implements Realm interface=
only, your realm wouldn't be allowed to participate in authorization, but =
only in authentication process. See an example of a simple, custom JP=
A-based entity realm (service). Shiro provides an extensive set of inte=
rfaces, often providing different functionalities depending on which featur=
es are available.

=20

=20

Storing password

=20
Icon=20

=20

Apache Shiro is persistence agnostic so you need to decide yourself how =
to store the passwords and compare their equality. Shiro comes with several=
built-in matchers to make this simple. The User entity used by the realm s=
ample referred to above also shows an example of storing an SHA-1 hash =
with per user salt.

=20

=20

=20

Shiro is based on multiple filter chains which is a natural fit with tap=
estry's (filter) pipeline pattern. In the typical case, you don't have to i=
mplement new filters but merely configure them to process desired urls of y=
our application. Refer to the Shiro configuration for more information, but=
tapestry-security makes the default Shiro filters available so you can ref=
er to them by name.

Shiro supports url-based permission checking out of the box. Tapestry-se=
curity also comes with several security annotations and some security compo=
nents that you can use in your page classes and templates to secure specifi=
c operations or access to the page.

For 0.3.x and earlier versions, you can use a standard Shiro INI configu=
ration file (see Shiro's documentation for more in=
fo) with tapestry-security. All versions support annotation-based security.=
The simplest and most typical security models are based on url and role pe=
rmissions, see the following version-specific sections for examples on them=
.

Note that above, a call to factory.<filtername>() gives you a new =
instance of the filter each time. In fact, you get a runtime error if you t=
ry to contribute the same filter instance to a different c=
hain with a different configuration.

Also, note that by the servlet spec, application filters don't handle er=
ror requests by default (Jetty, at least the old versions, didn't conform).=
So, to get the Tapestry filter to handle the ERROR request, you also need =
to configure:

In your realm, you allocate individual permission strings to each user t=
hat are then matched against the permission strings from the annotations. F=
or more information, read Shiro's documentation on permi=
ssions. While the permission concept is flexible, it still doesn't allo=
w you to declaratively secure instances of data. You can programmatically c=
heck for instance level permissions but it's cumbersome to allocate the cor=
rect permissions and equally cumbersome to later verify them. Entity-Relati=
onship Based Access Control (ERBAC) system allows declaring subject-ins=
tance security rules. For example, all users can read each other's pro=
file data, but only modify their own. If you are using JPA, you are in luck=
since our implementation of ERBAC security concept, tapestry-security-jpa =
module allows securing your entities with simple annotations @RequiresAssoc=
iation and @RequiresRole, check out tapestry-securi=
ty-jpa!

Security components

There are often cases where it's not enough to simply secure the urls or=
the pages. If a user doesn't have a permission to invoke a particular acti=
on, it's a good practice to also hide it from his view. Tapestry-security m=
odule contains several built-in conditional components to make conditional =
rendering of your page templates and more fine-grained permission control e=
asier.

The names of following components should give you a pretty good hint of =
their purpose, can you guess what all of them do? 0.5.1 also added support =
for an p:else block for all the built-in security components.

Overriding login, success and unauthorized URLs

tapestry-security comes with two very simple login and =
unauthorized pages, and also by default the success url will be /index<=
/em> Most likely, you will want to change these URLs to point to your=
own customized pages. To do that use SecuritySymbols

Javamelody is one of the best open-source server hea=
lth monitoring packages available for Java webapps at the moment. Javamelod=
y is implemented as a ServletFilter. Each request needs to pass through the=
filter to be accounted for. The same filter is also responsible for produc=
ing the reports by handling requests to "/monitoring" url directl=
y. This imposes a problem with securing the "/monitoring" url. If=
you declare the Javamelody filter before Tapestry filter you couldn't secu=
re the monitoring page (with a Tapestry-based security solution), and if yo=
u declared it after the Tapestry filter, the monitoring filter would never =
be invoked for requests handled by Tapestry. The solution is to inject the =
Monitoring filter into your security filter chain configuration, like so:=
p>

Notice that above, we are using the same instance of the monitoring filt=
er in both chains, which is perfectly fine since standard servlet filters d=
o not carry any chain specific configuration (unlike typical Shiro filters)=
. With this configuration, we can now both analyze every request and secure=
the monitoring reporting page. Any other standard ServletFilters can also =
easily be configured as part of the security configuration, completely avoi=
ding web.xml configuration. Also, unrelated to security, but Javamelody com=
es with its own gzipping, so remember to use 1.39.0 version or better and t=
urn off its gzipping (using context parameter gzip-compression-disable=
d), otherwise it'll conflict with Tapestry's gzipping facilities.