Author: dashorst
Date: Thu Aug 12 22:51:35 2010
New Revision: 985026
URL: http://svn.apache.org/viewvc?rev=985026&view=rev
Log:
Added auth/roles docs to webstie
Modified:
wicket/common/site/trunk/_site/atom.xml
wicket/common/site/trunk/_site/learn/projects/authroles.html
wicket/common/site/trunk/learn/projects/authroles.md
Modified: wicket/common/site/trunk/_site/atom.xml
URL:
http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/atom.xml?rev=985026&r1=985025&r2=985026&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/atom.xml (original)
+++ wicket/common/site/trunk/_site/atom.xml Thu Aug 12 22:51:35 2010
@@ -4,7 +4,7 @@
<title>Apache Wicket</title>
<link href="http://wicket.apache.org/atom.xml"; rel="self"/>
<link href="http://wicket.apache.org/"/>
- <updated>2010-08-13T00:36:32+02:00</updated>
+ <updated>2010-08-13T00:51:11+02:00</updated>
<id>http://wicket.apache.org/</id>
<author>
<name>Apache Wicket</name>
Modified: wicket/common/site/trunk/_site/learn/projects/authroles.html
URL:
http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/learn/projects/authroles.html?rev=985026&r1=985025&r2=985026&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/learn/projects/authroles.html (original)
+++ wicket/common/site/trunk/_site/learn/projects/authroles.html Thu Aug 12
22:51:35 2010
@@ -144,7 +144,108 @@
<div id="contentbody">
<h1>Wicket Auth/Roles</h1>
- <p>Waiting for someone to contribute some introductory
documentation about this project. See for an example the <a
href='velocity.html'>Velocity project description</a>.</p>
+ <p>This is mostly a technology demonstration
implementing authorization and authentication for the Apache Wicket web
framework. The project supplies roles based authorization and some simple
authentication components.</p>
+
+<h2 id='contents'>Contents</h2>
+
+<ul>
+<li><a href='#introduction'>Introduction</a></li>
+
+<li><a href='#example'>Example</a></li>
+
+<li><a href='#installing'>Installing</a></li>
+</ul>
+
+<h2 id='introduction'>Introduction</h2>
+
+<p>Wicket Auth/Roles is a simplistic but useful security extension to the
Wicket framework. It is intended to be simplistic and not to be confused with a
framework. If you find this library useful, great. If you need more than is
supplied by this library, either look at <a href='#alternatives'>alternative
security integrations</a> or copy these classes and modify them at will (this
project <strong>is</strong> <a href='http://www.apache.org/licenses/'>open
source</a> after all.)</p>
+
+<p>Like most if not all security solutions for Wicket, this project provides
an implementation for Wicket’s <code>IAuthorizationStrategy</code>. When
an authorization strategy is installed in the security settings
(<code>WebApplication#getSecuritySettings</code>), Wicket will check for each
component (including pages) if instantiation is allowed and if rendering is
allowed.</p>
+
+<p>For more documentation use the following links:</p>
+
+<ul>
+<li><a
href='http://wicket.apache.org/apidocs/1.4/org/apache/wicket/authentication/package-frame.html'>Authentication
API</a></li>
+
+<li><a
href='http://wicket.apache.org/apidocs/1.4/org/apache/wicket/authorization/package-frame.html'>Authorization
API</a></li>
+</ul>
+
+<p>Note that for the instantiation check Wicket will invoke the constructor
hierarchy of your component, but will throw an exception if the authorization
check fails.</p>
+
+<h3 id='authentication'>Authentication</h3>
+
+<p>As a basis, you should extend your web application class from
<code>AuthenticatedWebApplication</code>. When you create your class
you’ll be asked to override the following methods:</p>
+
+<ul>
+<li><code>newSession</code> - return a subclass of
<code>AuthenticatedWebSession</code></li>
+
+<li><code>getSignInPageClass</code> - return the class for your login page
(this one should not require authentication, otherwise you’ll create an
infinite loop)</li>
+</ul>
+
+<p>Next you’ll need to provide your custom session class-making it a
subclass of <code>AuthenticatedWebSession</code>. This class requires you to
override the following methods:</p>
+
+<ul>
+<li><code>authenticate</code> - called when the user needs to be authenticated
using a username and password</li>
+
+<li><code>getRoles</code> - called after the users was authenticated and
should provide the roles associated with the authenticated user.</li>
+</ul>
+
+<p>You can use the provided <code>SignInPage</code>, which has been translated
to a couple of languages (see the source code for the actual translations), or
roll your own. When you roll your own, you can opt to use the provided
<code>SignInPanel</code> (which has been translated as well) so you don’t
have to create your own login form.</p>
+
+<h3 id='authorization'>Authorization</h3>
+
+<p>Annotation for configuring what roles are allowed for instantiation the
annotated component or package. This annotation can be used for classes and
packages, and can be used like this:</p>
+<div class='highlight'><pre><code class='java'><span class='c1'>// only users
with role ADMIN are allowed to create instances of this page, whether it
is</span>
+<span class='c1'>// either bookmarkable or not</span>
+<span class='nd'>@AuthorizeInstantiation</span><span class='o'>(</span><span
class='s'>"ADMIN"</span><span class='o'>)</span>
+<span class='kd'>public</span> <span class='kd'>class</span> <span
class='nc'>AdminAnnotationsBookmarkablePage</span> <span
class='kd'>extends</span> <span class='n'>WebPage</span>
+</code></pre>
+</div>
+<p>When someone who doesn’t have the role ADMIN, Wicket will not allow
the page to be fully constructed and throw an authorization exception during
the construction of the page. This will result in an access denied page for the
user.</p>
+
+<p>Enablng the annotations for role based authorization is done by setting the
<code>WebApplication#getSecuritySettings</code> value to
<code>AnnotationsRoleAuthorizationStrategy</code>. Then you can use the
auth/roles provided authorization annotations.</p>
+
+<h3 id='alternatives'>Alternatives</h3>
+
+<p>More elaborate security solutions exist in the following projects:</p>
+
+<ul>
+<li><a
href='http://wicketstuff.org/confluence/display/STUFFWIKI/wicket-shiro'>Wicket
Shiro</a> - integration between Apache Shiro and Wicket</li>
+
+<li><a
href='http://wicketstuff.org/confluence/display/STUFFWIKI/Wicket-Security'>Wicket
Security</a> - JAAS inspired, principal based security framework</li>
+</ul>
+
+<p>If other security solutions are available for Wicket, <a
href='https://issues.apache.org/jira/browse/WICKET'>let us know</a>.</p>
+
+<h2 id='example'>Example</h2>
+
+<p>The Wicket Examples project contains a <a
href='http://wicketstuff.org/wicket14/authorization'>complete example</a> of
limiting access to pages and components using roles based authorization. It
also contains an <a
href='http://wicketstuff.org/wicket14/authentication'>authentication
example</a>.</p>
+
+<p>Click on the source links to see the related source code.</p>
+
+<h2 id='installing'>Installing</h2>
+
+<p>Installing Wicket Auth/Roles can be done through adding a dependency in
your project’s Maven pom, or by putting the wicket-auth-roles.jar and the
required dependencies in your projects classpath.</p>
+
+<h3 id='using_maven'>Using Maven</h3>
+
+<p>Add the following dependency to your pom:</p>
+<div class='highlight'><pre><code class='xml'><span
class='nt'><dependency></span>
+ <span class='nt'><groupId></span>org.apache.wicket<span
class='nt'></groupId></span>
+ <span class='nt'><artifactId></span>wicket-auth-roles<span
class='nt'></artifactId></span>
+ <span class='nt'><version></span>1.4.10<span
class='nt'></version></span>
+<span class='nt'></dependency></span>
+</code></pre>
+</div>
+<h3 id='required_dependencies'>Required dependencies</h3>
+
+<p>Wicket Auth/Roles requires the following jar files to be on your
classpath:</p>
+
+<ul>
+<li>Wicket</li>
+
+<li>Wicket Auth/Roles</li>
+</ul>
</div>
<div id="clearer"></div>
<div id="footer"><span>
Modified: wicket/common/site/trunk/learn/projects/authroles.md
URL:
http://svn.apache.org/viewvc/wicket/common/site/trunk/learn/projects/authroles.md?rev=985026&r1=985025&r2=985026&view=diff
==============================================================================
--- wicket/common/site/trunk/learn/projects/authroles.md (original)
+++ wicket/common/site/trunk/learn/projects/authroles.md Thu Aug 12 22:51:35
2010
@@ -3,5 +3,134 @@ layout: default
title: Wicket Auth/Roles
---
-Waiting for someone to contribute some introductory documentation about this
-project. See for an example the [Velocity project description](velocity.html).
+This is mostly a technology demonstration implementing authorization and
+authentication for the Apache Wicket web framework. The project supplies roles
+based authorization and some simple authentication components.
+
+## Contents ##
+
+* [Introduction](#introduction)
+* [Example](#example)
+* [Installing](#installing)
+
+## Introduction ##
+
+Wicket Auth/Roles is a simplistic but useful security extension to the Wicket
+framework. It is intended to be simplistic and not to be confused with a
+framework. If you find this library useful, great. If you need more than is
+supplied by this library, either look at [alternative security
+integrations](#alternatives) or copy these classes and modify them at will
+(this project **is** [open source](http://www.apache.org/licenses/) after
+all.)
+
+Like most if not all security solutions for Wicket, this project provides an
+implementation for Wicket's `IAuthorizationStrategy`. When an authorization
+strategy is installed in the security settings
+(`WebApplication#getSecuritySettings`), Wicket will check for each component
+(including pages) if instantiation is allowed and if rendering is allowed.
+
+For more documentation use the following links:
+
+* [Authentication
API](http://wicket.apache.org/apidocs/1.4/org/apache/wicket/authentication/package-frame.html)
+* [Authorization
API](http://wicket.apache.org/apidocs/1.4/org/apache/wicket/authorization/package-frame.html)
+
+Note that for the instantiation check Wicket will invoke the constructor
+hierarchy of your component, but will throw an exception if the authorization
+check fails.
+
+### Authentication ###
+
+As a basis, you should extend your web application class from
+`AuthenticatedWebApplication`. When you create your class you'll be asked to
+override the following methods:
+
+* `newSession` - return a subclass of `AuthenticatedWebSession`
+* `getSignInPageClass` - return the class for your login page (this one should
+ not require authentication, otherwise you'll create an infinite loop)
+
+Next you'll need to provide your custom session class-making it a subclass of
+`AuthenticatedWebSession`. This class requires you to override the following
+methods:
+
+* `authenticate` - called when the user needs to be authenticated using a
+ username and password
+* `getRoles` - called after the users was authenticated and should provide the
+ roles associated with the authenticated user.
+
+You can use the provided `SignInPage`, which has been translated to a couple
+of languages (see the source code for the actual translations), or roll your
+own. When you roll your own, you can opt to use the provided `SignInPanel`
+(which has been translated as well) so you don't have to create your own login
+form.
+
+### Authorization ###
+
+Annotation for configuring what roles are allowed for instantiation the
+annotated component or package. This annotation can be used for classes and
+packages, and can be used like this:
+
+{% highlight java %}
+// only users with role ADMIN are allowed to create instances of this page,
whether it is
+// either bookmarkable or not
+...@authorizeinstantiation("ADMIN")
+public class AdminAnnotationsBookmarkablePage extends WebPage
+{% endhighlight %}
+
+When someone who doesn't have the role ADMIN, Wicket will not allow the page
+to be fully constructed and throw an authorization exception during the
+construction of the page. This will result in an access denied page for the
+user.
+
+Enablng the annotations for role based authorization is done by setting the
+`WebApplication#getSecuritySettings` value to
+`AnnotationsRoleAuthorizationStrategy`. Then you can use the auth/roles
+provided authorization annotations.
+
+### Alternatives ###
+
+More elaborate security solutions exist in the following projects:
+
+ * [Wicket
+ Shiro](http://wicketstuff.org/confluence/display/STUFFWIKI/wicket-shiro) -
+ integration between Apache Shiro and Wicket
+ * [Wicket
+
Security](http://wicketstuff.org/confluence/display/STUFFWIKI/Wicket-Security)
+ - JAAS inspired, principal based security framework
+
+If other security solutions are available for Wicket, [let us
+know](https://issues.apache.org/jira/browse/WICKET).
+
+## Example ##
+
+The Wicket Examples project contains a [complete
+example](http://wicketstuff.org/wicket14/authorization) of limiting access to
+pages and components using roles based authorization. It also contains an
+[authentication example](http://wicketstuff.org/wicket14/authentication).
+
+Click on the source links to see the related source code.
+
+## Installing ##
+
+Installing Wicket Auth/Roles can be done through adding a dependency in your
+project's Maven pom, or by putting the wicket-auth-roles.jar and the required
+dependencies in your projects classpath.
+
+### Using Maven ###
+
+Add the following dependency to your pom:
+
+{% highlight xml %}
+<dependency>
+ <groupId>org.apache.wicket</groupId>
+ <artifactId>wicket-auth-roles</artifactId>
+ <version>{{site.wicket.version}}</version>
+</dependency>
+{% endhighlight %}
+
+### Required dependencies ###
+
+Wicket Auth/Roles requires the following jar files to be on your classpath:
+
+ * Wicket
+ * Wicket Auth/Roles
+
