apache > cocoon

Authentication Framework: The Authentication Handler

The Authentication handler

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.

Each authentication handler needs the following mandatory configuration:

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

The Configuration of a Handler

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

    ...component definitions...

        <handler name="portalhandler">
          <redirect-to uri="cocoon:/sunspotdemoportal"/>
          <authentication uri="cocoon:raw:/sunrise-authuser"/>
   ... document pipelines following here:

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.

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.

Protecting Documents

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

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

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

If the user is authenticated, the commands inside the map:act will be execute and the user gets the document itself.

So, the auth-protect 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 auth-protect action or the parameter handler is missing, the document is accessible by any user.

You will see learn later on how to efficiently protect several documents with a handler.

The redirect-to document

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

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

For example, the redirect-to 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 redirect-to document.