Protecting Documents

One feature of CoWarp is user authentication and protecting documents. A document can be accessible for everyone, it can be accessible by authenticated users or the user needs more credentials than just being logged in to read it - for example she has to be in a specific role.

There are several ways of protecting a document:

  1. The Servlet Specification: It is possible to define URI spaces that require an authenticated users.
  2. The Sitemap: CoWarp provides some actions to protect pipelines. The checks range from testing if the user is authenticated, over if the user has a role to more specific, custom access checks.
  3. Cocoon Flow: CoWarp provides some FlowScript functions that make the same checks that are possible in a sitemap available to the flow controller.
  4. Custom Components: CoWarp consists of several (Avalon) components, that can be used in your own code if required.

Regardless which method you use, the process of requesting a document can be described as follows:

  1. The user request a document (original document).
  2. CoWarp checks (using one of the methods mentioned above) if this document is protected. If no protection is specified, the response is this original document.
  3. If the document is protected, CoWarp checks, if the user is authenticated.
  4. If the user is authenticated, the response is the original document. If the user is not authenticated, the application logic has to deal with this. For example a redirect to a special page can be done. This action is freely configurable and can for example contain information about the unauthorized access and in addition a login form.
  5. At some point, the user has to authenticate. This is usually done by creating a login form where the user can enter the required information (e.g. user id and password). When the user submits his data, CoWarp activates the corresponding security-handler and tries to authenticate the user.
  6. In case of a successful authentication a redirect to the original document (or to any configured start document) can take place.
  7. If the authentication fails another page is invoked that might displays(error) information to the user. Again this is freely customizable.

This process is only one example for a use-case of CoWarp. It can be configured for any authentication scheme and any flow. Every aspect is freely configurable.

Controlling the user access

An application can be used to protected documents. It's the task of the application developer to specifiy if a Cocoon pipeline is only accessible for authenticated users of an application. This can be done either in the sitemap using actions, or in flow using a component or in some custom code.

Using actions

CoWarp provides the cowarp-is-logged-in action to check in the sitemap if the user is logged in. The name of the application is required as a parameter. 

...
<map:act type="cowarp-is-logged-in">
  <map:parameter name="application" value="WebShop">
  // USER IS LOGGED IN
</map:act>
// USER IS NOT LOGGED IN
...

In contrast to the authentication-fw block of Cocoon, this action doesn't perform a redirect if the user is not logged in. It's up to the application developer to do the appropriate action.

Using flow

The functionality of CoWarp is available through a single component: the ApplicationManager. Testing if a user is authenticated is just calling a single method on this manager which takes the application as an argument: 

var appMan = cocoon.getComponent(ApplicationManager.class.getName());
if ( appMan.isLoggedIn("WebShop") ) {
  // YES, logged in
} else {
  // No, not logged in
}

Custom code

Using custom (java) code is very similar to using flow: you lookup the ApplicationManager as well and invoke the same methods.

Logging out

Usually a web application supports logging out of the application to free any resources and information on the server of the current user.

Using actions

The logout process can be triggered by the cowarp-logout action which requires the application name as a parameter: 

...
<map:act type="cowarp-logout">
  <map:parameter name="application" value="WebShop">
</map:act>
...

Using flow/Custom code

Again, the application manager can be used to logout a user from an application: 

var appMan = cocoon.getComponent(ApplicationManager.class.getName());
appMan.logout("WebShop", null);