Authentication Framework: Pipeline Patterns

As explained in the previous chapters, the framework uses the auth-protect action for authentication and protecting documents. This chapter shows some commonly used pipeline patterns.

Single protected document

For protecting a document with an authentication handler only the auth-protect action with the parameter configuration for the handler is required.

Pattern:

1. Pipeline matching
2. Using the auth-protect action for protecting

Example:

<map:match pattern="protected">
  <map:act type="auth-protect">  <!-- protect the resource -->
    <map:parameter name="handler" value="myhandler"/>

    <map:generate src="resource.xml"/>
    <map:transform src="toHTML"/>
    <map:serialize/>
  </map:act>
</map:match>

It is very important that the auth-protect action wraps the real pipeline, as the pipeline is only invoked if the action grants access. The matching must be done before the action is checked as the action performs a redirect for this document.

Multiple protected documents

Often you want to protect a bunch of documents in the same way. One solution is to use the single protected document pattern for each document. With the multiple protected document pattern you only have to use the action once for all documents and not within each document pipeline.

The prerequisite for this is a common matching pattern for the documents:

1. Pipeline pattern matching
2. Using the auth-protect action for protection
3. Pipeline matching

Example:

<map:match pattern="protected-*">
  <map:act type="auth-protect"> <!-- protect the resource -->
    <map:parameter name="handler" value="myhandler"/>

    <map:match pattern="protected-first">
      <map:generate src="resource1.xml"/>
      <map:transform src="toHTML"/>
      <map:serialize/>
    </map:match>
        ....
    <map:match pattern="protected-second">
      <map:generate src="resource2.xml"/>
      <map:transform src="toHTML"/>
      <map:serialize/>
    </map:match>
  
  </map:act>
</map:match>

Very important - as explained with the single document pattern - is the leading match before the action is performed. The subsequent matches are required to check which pipeline to use.

Controlling the Application Flow

If you want to create documents which behave different depending if you are logged in or not, the auth-loggedIn action is the component to use to control your application flow. This action checks if the user is authenticated for a given handler and calls all sitemap components inside the act tag.

<map:match pattern="startpage">

  <map:act type="auth-loggedIn">  <!-- check authentication -->
    <map:parameter name="handler" value="myhandler"/>

    <map:redirect-to uri="loggedInStartPage"/>
  </map:act>

  <map:generate src="startpage.xml"/>
  <map:transform src="toHTML"/>
  <map:serialize/>
</map:match>

In the example above, if the user is already logged he is redirected to the loggedInStartPage document. If he is not logged in for the given handler, the usual start page is generated.

The auth-protect action returns - if the user is logged in for the given handler - all values from the context to the sitemap, e.g. ID, role etc. These values can be used within the other components:

<map:match pattern"protected">
  <map:act type="auth-protect">  <!-- protect the resource -->
    <map:parameter name="handler" value="myhandler"/>

    <!-- Append the ID of the user to the file name -->
    <map:generate src="resource_{ID}.xml"/>
    <map:transform src="toHTML"/>
    <map:serialize/>

  </map:act>
</map:match>

But the auth-loggedIn action does not give the included pipeline access to the authentication context belonging to the handler. If you want this, you have to nest the auth-protect action inside!

<map:match pattern"start">

  <map:act type="auth-loggedIn">  <!-- check authentication -->
    <map:parameter name="handler" value="myhandler"/>

    <map:act type="auth-protect">  <!-- give access to the context -->
      <map:parameter name="handler" value="myhandler"/>

      <map:generate src="getinfofromcontext.xml"/>
      <map:transform type="session"/>
      <map:transform src="toHTML"/>
      <map:serialize/>
    </map:act>
  </map:act>

</map:match>

Session Handling

If a user is authenticated, the user has a session. However, care has to be taken that the session tracking works, which means that Cocoon can detect that a follow up request of the user belongs to the same session.

The easiest way is to use the encodeURL transformer as the last transformation step in your pipeline. For more information about session handling, have a look in the chapter about sessions.