XML.com: XML From the Inside Out
oreilly.comSafari Bookshelf.Conferences.


Building XML Portals with Cocoon

July 24, 2002


Cocoon is an Apache open source project originally started by Stefano Mazzocchi in 1998 because he was frustrated by the limitations HTML poses when it comes to separating content from design. He described the current Cocoon version in detail in an article for XML.com in February.

Although Cocoon was originally designed as a framework for XML-XSL publishing, we felt that due to the extensibility of the architecture, it would be possible to add components that extended Cocoon so that it could be used in a wider variety of applications. Around the same time we decided to use Cocoon, we were also evaluating available commercial portal solutions for several customers. Portals used in a more commercial environment have varied requirements. Therefore it seemed ideal to extend Cocoon with components for authentication and portals -- and at the same time to retain the original strengths of the platform.

The new components were originally developed as part of a commercial offering. In the middle of 2001 we installed the first Cocoon-powered portal at a financial institution in Germany. At the beginning of 2002 we then donated the components to the Cocoon project. The donation consisted of components and tools for authentication (originally called "sunRise") and portals (originally called "sunSpot"). Each part can be used without the other; the authentication can be used to protect certain resources on the server.

Related Reading

XML in a Nutshell, 2nd Edition

XML in a Nutshell, 2nd Edition
A Desktop Quick Reference
By W. Scott Means, Elliotte Rusty Harold

In this article we will look at the Cocoon portal and authentication frameworks, and we assume that the reader is familiar with the basic Cocoon concepts, such as the sitemap. You can find an introduction to Cocoon in a recent XML.com article by Steve Punte.


Authenticating a user is one of the central aspects of any modern middleware application. Once the user has been authenticated, she should be able to access the preconfigured resources for her particular user-id or role.


The goal of the contained authentication components is to allow the authentication of a user against a configured user data-source (such as a database). The components should also allow resources to be protected, meaning that they can only be accessed if the authentication was successful. The most important goal was however to make sure all this is possible using the original Cocoon concepts which allow a great deal of flexibility when it comes to connecting to external systems.


The authentication framework consists of additional Cocoon components that provide the necessary functionality. New components are provided for session handling and for allowing data to be stored in and retrieved from a user's session. In addition a Cocoon "action" component can then be used to protect the resources.

The concept of authentication-handlers was introduced to allow the logical grouping of resources. This means that once a user has authenticated herself against a particular handler, she can access all the resources that have been logically grouped under that particular handler. Each handler can then be configured to authenticate against a particular-data source, so handler A could authenticate against a database and handler B could use an LDAP directory. The actual authentication takes place using Cocoon pipelines.

Here is a snippet from the Cocoon sitemap. It shows how a handler is configured.

                <handler name="portalhandler">
                    <redirect-to uri="cocoon:/sunspotdemoportal"/>
                    <authentication uri="

The different handlers are grouped inside the authentication-manager section. Each handler has a unique name which can be referenced later when configuring the pipelines that needs to be protected. The redirect-to tag is used to configure the pipeline that is to be called if the user tries to access a protected page which she is currently not allowed to see. The authentication pipeline is defined in the tag authentication. This pipeline receives the input from, say, a login screen and can then authenticate the data against a data-source such as a database.

If successful, the authentication pipeline (in this case a pipeline called "sunrise-authuser") is required to return XML data in a specific format which is described in detail in the Cocoon documentation. The format is flexible: additional data about the user can be added by the authentication pipeline and used in the application at a later stage.

Once the handler has been defined and the authentication pipeline configured, the next step is to protect the resources. The following XML fragment taken from the sitemap, shows how a resource can be protected using the authentication action in conjunction with the defined handler.

<map:match pattern="protected-document">
    <!-- protect this document -->
    <map:act type="auth-protect">
        <map:parameter name="handler" value="portalhandler"/>

        <map:generate src="document.xml"/>
        <map:transform src="to_html.xsl"/>

In this case the resource protected-document "belongs" to the handler called portalhandler. If the user has previously logged into that handler, then all the resources grouped under that particular handler will be accessible to her. If the user has not already logged in, then she will be redirected to the pipeline previously defined when the handler was configured. Normally a login-screen will then be presented and the user can log in with an id and password.

Pages: 1, 2, 3

Next Pagearrow