cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [DAISY] Created: Authenticating a User
Date Tue, 16 Aug 2005 13:23:35 GMT
A new document has been created.

Document ID: 666
Branch: main
Language: default
Name: Authenticating a User
Document Type: Document
Created: 8/16/05 1:23:33 PM
Creator (owner): Helma
State: publish


Mime type: text/xml
Size: 8898 bytes

<p>Usually, the <em>redirect-to</em> document of a handler contains a form
the user to authenticate. But of course, you are not limited to this. No matter
how the <em>redirect-to</em> document looks like, the user has "somewhere" the
abilitiy to authenticate, so in most cases the user has a form where he can
enter his information (e.g. user name and password). You have to write a
pipeline presenting this form to the user. When the form is submitted, the
authentication process has to be started inside the authentication framework. As
a submit of a form invokes a request to Cocoon, a pipeline in the sitemap is
triggered. We refer to this pipeline as a <em>login pipeline</em>.</p>

<h2>The Login Process</h2>

<p>The authentication process is started by invoking the <em>auth-login</em>
action. So, the <em>login pipeline</em> has to contain this action:</p>

<pre>&lt;map:match pattern="login"&gt;
  &lt;map:act type="auth-login"&gt;
    &lt;map:parameter name="handler" value="portalhandler"/&gt;
    &lt;map:parameter name="parameter_userid" value="{request-param:name}"/&gt;
    &lt;map:parameter name="parameter_password" value="{request-param:password}"/&gt;
    &lt;map:redirect-to uri="authentication-successful"/&gt;
  &lt;!-- authentication failed: --&gt;
  &lt;map:generate src="auth_failed.xml"/&gt;
  &lt;map:transform src="tohtml.xsl"/&gt;

<p>The <em>auth-login</em> action uses the handler parameter to call the
<em>authentication resource</em> of this handler. This <em>authentication
resource</em> needs to know the information provided by the user, e.g. in the
form. For each piece of information a separate parameter is created. The name of
this parameter has to start with "parameter_". So in the example above, the
<em>authentication resource</em> gets two parameters: userid and password. Since
the values of these parameters were sent by a form, they need to be passed on to
the <em>authentication resource</em>. If you use "{request-param:...}" for the
value of a parameter, the <em>auth-login</em> action will pass the actual value
of that request parameter to the <em>authentication resource</em> by using the
input modules concept of Cocoon.</p>

<p class="note">You might be wondering why we explicitly pass the request
parameters on to the internal pipeline call. Note that the <em>authentication
resource</em> of the portalhandler is defined by <em>cocoon:raw</em>. By
this, no request parameter of the original request is passed on to the internal
pipeline by default and therefore we have to define them explicitly. If you use
<em>cocoon:</em> then the parameters of the form are by default passed on to the
<em>authentication resource</em> and we could omit the parameter definition from
above. But we feel that it is safer to explicitly define them.</p>

<p>If the user is not already authenticated with this handler, the framework
calls the <em>authentication resource</em> and passes the parameters to it. If
this authentication is successful, the action returns a map and the sitemap
commands inside the <em>map:act</em> are executed. If not already done, a
session is created on the server as well.</p>

<p>If the authentication fails, the action does not deliver a map and therefore
the commands inside the <em>map:act</em> are skipped. The error information
delivered by the <em>authentication resource</em> is stored in the
<em>temporary</em> context. So you can get the information using either the
<em>session transformer</em> or the <em>session-context input module</em>.</p>

<p class="note">As you can see from the example above, you are not limited in
defining the information the user has to provide. This can be as many fields as
you need.</p>

<h2>The authentication resource</h2>

<p>The last chapter described the authentication process but left out details
about the authentication itself. This chapter closes this gap.</p>

<p>The authentication can be done by different components:</p>

<li>A sitemap resource (pipeline).</li>
<li>A distant resource, e.g. requested via HTTP.</li>
<li>A java class.</li>

<p>The first two are actually similar as in both cases a URI is called. So we
will talk about them in the next chapter. Authentication using a java class is
the topic of the following chapter.</p>

<h3>Using a URI as the authentication resource</h3>

<p>Using this flexible approach nearly any kind of authentication is possible
(e.g. database, LDAP). The <em>authentication resource</em> is a mandatory
configuration of the authentication handler:</p>

    &lt;!-- Now follows the handlers configuration --&gt;
    &lt;handler name="portalhandler"&gt;
      &lt;!-- The login resource --&gt;
      &lt;redirect-to uri="cocoon:/sunspotdemoportal"/&gt;
      &lt;authentication uri="cocoon:raw:/sunrise-authuser"/&gt;

<p>If the <em>authentication resource</em> is a sitemap resource or a remote
resource, this resource is requested by the framework with the given parameters
from the <em>auth-login</em> action (see previous section). In addition, all
parameters inside the <em>authentication</em> tag of the handler configuration
are passed to the resource. The response of this resource must contain XML
conforming to the following scheme:</p>

    &lt;ID&gt;Unique ID of the user in the system&lt;/ID&gt;
    &lt;role&gt;rolename&lt;/role&gt; &lt;!-- optional --&gt;
        Any additional optional information can be supplied here. 
        This will be stored in the session for later retrieval

<p>The XML is very simply, only the root element <em>authentication</em>
and the
<em>ID</em> element with a valid unique ID for the user in this handler is
required. Everything else is optional.</p>

<p>The framework checks the response of the authentication resource for the
given scheme: the root node must be named <em>authentication</em> and one child
called <em>ID</em> must be present. In this case the authentication is
successfull and the framework creates an authentication session context and
stores the XML inside.</p>

<p>The mandatory <em>ID</em> tag is an unique identification for the user
the web application or more precisly inside this handler. The <em>role</em> is
optional and can be used for categorizing users and displaying different
functionality inside the Cocoon portal engine.</p>

<p class="note">The <em>role</em> element is optional; you can use your
categorization and exchange it with a <em>roles</em> element or a <em>group</em>
element or leave it out, if you don't need it. In addition you can add any other
element there as well and access the information later on.</p>

<p>Using the <em>data</em> node, the <em>authentication resource</em>
can pass
any information of the user to the session. You can retrieve the information as
long as the session is valid.</p>

<p>If the authentication is not successful, the resource must create an XML with
the root node <em>authentication</em>, without the <em>ID</em> tag.
In addition
a <em>data</em> node can be added containing more information about the
unsuccessful attempt. This data node is then stored into the <em>temporay</em>
context (see previous section).</p>

<p class="note">It is advisable to make an internal pipeline for the
<em>authentication resource</em>. An internal pipeline is not directly
accessible by a user.</p>

<h3>Using a Java class as the authentication resource</h3>

<p>Using a class is an alternative for using a pipeline. You can define this
class in the handler configuration as an attribute <em>authenticator</em> of the
<em>authentication</em> element, e.g.:</p>

    &lt;!-- Now follows the handlers configuration --&gt;
    &lt;handler name="portalhandler"&gt;
      &lt;!-- The login resource --&gt;
      &lt;redirect-to uri="cocoon:/sunspotdemoportal"/&gt;
      &lt;authentication authenticator="mypkg.MyAuthenticator"/&gt;

<p>This class must conform to the <em>Authenticator</em> interface. This
interface provides a method that tries to authenticate a User and delivers XML
that is stored in the session on success. So, the behaviour is similar to the

<h2>Logging out</h2>

<p>The logout process is triggered by the "auth-logout" action:</p>

<pre>&lt;map:act type="auth-logout"&gt;
  &lt;map:parameter name="handler" value="unique"/&gt;

<p>This action logs the user out of the given handler and removes all the
information about this handler that is stored in the session.</p>


The document belongs to the following collections: documentation

View raw message