Protection

Protecting Documents

One feature of Cocoon Auth is user authentication and document protection. A document can be accessible for everyone, it can be accessible by authenticated users only, or it can be accessible only to users who supply additional credentials (apart from 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: Cocoon Auth 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: Cocoon Auth provides some FlowScript functions that make the same checks that are possible in a sitemap available to the flow controller.
4. Custom Components: Cocoon Auth consists of several 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. Cocoon Auth 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, Cocoon Auth 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, Cocoon Auth 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 display (error) information to the user. Again this is freely customizable.

This process is only one example for a use-case of Cocoon Auth. 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

Cocoon Auth provides the cauth-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="cauth-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 Cocoon Auth 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 cauth-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);