Authentication Framework

One central point in building a web application is authentication and authorization. The Cocoon authentication framework is a flexible module for authentication, authorization and user management. A user can be legitimated using any information available via any source, e.g. an existing database, LDAP or the file system. With this mechanism it is very easy to use an exisiting user management/authentication system within Cocoon.

The basic concept of the authentication framework is to protect documents generated by Cocoon. By document we refer to the result of a request to Cocoon, this can either be the result of a pipeline or of a reader defined in the sitemap.

A document is protected by an authentication handler. A document is associated with a defined handler to provide the protection. A user's request for a document will only succeed if the handler signals that the user passes authentication.

A handler can be used to protect several documents in the same way. If a user is authenticated he can access all these documents. It is possible to use different handlers, to protect documents in different ways.

The use of the authentication framework and its components is described in the following sections.

The Authentication Framework adds some actions to the sitemap: the auth-protect action, the auth-login action, the auth-logout action and the auth-loggedIn action. The authentication-manager gets the configuration for the authentication framework and the actions control the pipelines. The auth-login and the auth-logout action control the authentication whereas the auth-loggedIn action controls the application flow.

One feature of the framework is the user authentication. A document can be accessible for everyone or it can be protected using this framework. The process of requesting a document can be described as follows:

1. The user requests a document (original document).
2. The authentication framework checks if this document is protected. If no protection is specified, the response to the request is the original document.
3. If the document is protected, the framework checks, if the user is authenticated to view it.
4. If the user is authenticated, the response is the original document. If not, the framework redirects to a special redirect-to document. This redirect-to document is freely configurable and could, for example, contain information about the unauthorized access and a login form.
5. Using the login form an authentication resource can be called with the corresponding user information (e.g. user id and password). This authentication resource uses the framework for the authentication process.
6. In case of a successful authentication the framework can redirect to the original document (or to any configured start document).
7. If the authentication fails another document is invoked by the framework displaying information to the user.

This process is only one example for a use-case of the framework. It can be configured for any authentication scheme. All resources are freely configurable.