You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by da...@cocoon.zones.apache.org on 2005/08/16 15:22:35 UTC

[DAISY] Created: The Authentication Handler

A new document has been created.

http://cocoon.zones.apache.org/daisy/documentation/665.html

Document ID: 665
Branch: main
Language: default
Name: The Authentication Handler
Document Type: Document
Created: 8/16/05 1:22:34 PM
Creator (owner): Helma
State: publish

Parts
=====

Content
-------
Mime type: text/xml
Size: 4503 bytes
Content:
<html>
<body>

<h2>The Authentication handler</h2>

<p>The basic object for authentication is the authentication handler. It
controls the access to the documents. Each document in the sitemap can be
related to exactly one authentication handler. All documents belonging to the
same handler are protected in the same way. If a user has access to the handler,
the user has the same access rights for all documents associated with this
handler.</p>

<p>Each authentication handler needs the following mandatory configuration:</p>

<ul>
<li>A unique name.</li>
<li>The authentication resource: A Cocoon pipeline usedto authenticate a user.
(We will see later on, that there are more possibilities than using a pipeline).
</li>
<li>The redirect-to document: This document is displayed when a when a user
fails authentication.</li>
</ul>

<h2>The Configuration of a Handler</h2>

<p>So let's have a look at the configuration. A handler is configured in the
sitemap using a <em>component configuration<em> for the authentication manager.
This configuration is specified in the <em>map:pipelines</em> section of a
sitemap:</em></em></p>

<pre>&lt;map:sitemap&gt;
    ...component definitions...

&lt;map:pipelines&gt;
  &lt;map:component-configurations&gt;
    &lt;authentication-manager&gt;
      &lt;handlers&gt;
        &lt;handler name="portalhandler"&gt;
          &lt;redirect-to uri="cocoon:/sunspotdemoportal"/&gt;
          &lt;authentication uri="cocoon:raw:/sunrise-authuser"/&gt;
        &lt;/handler&gt;
      &lt;/handlers&gt;
    &lt;/authentication-manager&gt;
  &lt;/map:component-configurations&gt;
&lt;map:pipeline&gt;
   ... document pipelines following here:
</pre>

<p>Using a unique name for each handler (only alphabetical characters and digits
are allowed for the handler name), the framework manages different handlers. So
various parts of the sitemap can be protected in different ways.</p>

<p>A handler is inherited to a sub sitemap. Each sub sitemap can define its own
handlers. These handlers are only available to the sub sitemap (and of course to
its sub sitemaps). However, it is not possible to redefine (overwrite) a
previously defined handler in a sub sitemap.</p>

<h2>Protecting Documents</h2>

<p>A document is protected by associating it with a defined handler. This is
done by using the <em>auth-protect</em> action and the handler parameter:</p>

<pre>&lt;map:match pattern="protectedresource"&gt;
  &lt;map:act type="auth-protect"&gt;
    &lt;map:parameter name="handler" value="portalhandler"/&gt;
    &lt;map:generate src="source/resource.xml"/&gt;
    &lt;map:serialize type="xml"/&gt;
  &lt;/map:act&gt;
&lt;/map:match&gt;</pre>

<p>If this document is requested, the action checks that the defined handler
successfully authenticates the user. If not, the action automatically redirects
to the <em>redirect-to</em> document configured in the handler. (In the example
above this is the pipeline defined by <em>cocoon:/sunspotdemoportal</em>.</p>

<p>If the user is authenticated, the commands inside the <em>map:act</em> will
be execute and the user gets the document itself.</p>

<p>So, the <em>auth-protect</em> action must be included in the pipeline of the
document. It gets the handler information as a parameter. If the pipeline does
not use the <em>auth-protect</em> action or the parameter <em>handler</em> is
missing, the document is accessible by any user.</p>

<p class="note">You will see learn later on how to efficiently protect several
documents with a handler.</p>

<h2>The redirect-to document</h2>

<p>If the requested document is not accessible by the user, the authentication
framework redirects to the configured <em>redirect-to</em> document. This
document is a mandatory element of the authentication handler.</p>

<p>This <em>redirect-to</em> document is an unprotected pipeline in the sitemap.
For tracking which document was originally requested by the user, the
<em>redirect-to</em> pipeline gets the request parameter <em>resource</em> with
that value. In addition all parameters specified inside the <em>redirect-to</em>
tag of the handler configuration are passed to the pipeline as well.</p>

<p>For example, the <em>redirect-to</em> document can contain a form for the
user authentication. This form should invoke the real authentication process
that is described below. However, the document you show when an unauthorized
access is made, can be controlled by you by defining this <em>redirect-to</em>
document.</p>

</body>
</html>

Collections
===========
The document belongs to the following collections: documentation