cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From da...@cocoon.zones.apache.org
Subject [DAISY] Updated: Authentication Framework
Date Tue, 16 Aug 2005 13:21:35 GMT
A document has been updated:

http://cocoon.zones.apache.org/daisy/documentation/604.html

Document ID: 604
Branch: main
Language: default
Name: Authentication Framework (unchanged)
Document Type: Document (unchanged)
Updated on: 8/16/05 1:21:18 PM
Updated by: Helma

A new version has been created, state: publish

Parts
=====
Content
-------
This part has been updated.
Mime type: text/xml (unchanged)
File name:  (unchanged)
Size: 4281 bytes (previous version: 36394 bytes)
Content diff:
(24 equal lines skipped)
    different handlers, to protect documents in different ways.</p>
    
    <p>The use of the authentication framework and its components is described in
--- the following chapters.</p>
+++ the following sections.</p>
    
    <p class="note">As you will see, the user management of the authentication
    framework is very flexible.<br/>
(11 equal lines skipped)
    production system, you don't have to test your whole application again. <br/>
    (Although in general this might be a good idea...).</p>
    
--- <h1>Sitemap-Components</h1>
+++ <h1>Sitemap Components</h1>
    
--- <p>The authentication Framework adds some actions to the sitemap: the
+++ <p>The Authentication Framework adds some actions to the sitemap: the
    <em>auth-protect</em> action, the <em>auth-login</em> action,
the
    <em>auth-logout</em> action and the <em>auth-loggedIn</em> action.
The
    <em>authentication-manager</em> gets the configuration for the authentication
(33 equal lines skipped)
    configured for any authentication scheme. All resources are freely configurable.
    </p>
    
--- <h2>The Authentication handler</h2>
--- 
--- <p>The basic object for authentication is the authentication handler. It
--- controls the access to the documents. Each document in the sitemap can be
--- related to exactly one authentication handler. All documents belonging to the
--- same handler are protected in the same way. If a user has access to the handler,
--- the user has the same access rights for all documents associated with this
--- handler.</p>
--- 
--- <p>Each authentication handler needs the following mandatory configuration:</p>
--- 
--- <ul>
--- <li>A unique name.</li>
--- <li>The authentication resource: A Cocoon pipeline usedto authenticate a user.
--- (We will see later on, that there are more possibilities than using a pipeline).
--- </li>
--- <li>The redirect-to document: This document is displayed when a when a user
--- fails authentication.</li>
--- </ul>
--- 
--- <h2>The Configuration of a Handler</h2>
--- 
--- <p>So let's have a look at the configuration. A handler is configured in the
--- sitemap using a <em>component configuration<em> for the authentication manager.
--- This configuration is specified in the <em>map:pipelines</em> section of a
--- sitemap:</em></em></p>
--- 
--- <pre>&lt;map:sitemap&gt;
---     ...component definitions...
--- 
--- &lt;map:pipelines&gt;
---   &lt;map:component-configurations&gt;
---     &lt;authentication-manager&gt;
---       &lt;handlers&gt;
---         &lt;handler name="portalhandler"&gt;
---           &lt;redirect-to uri="cocoon:/sunspotdemoportal"/&gt;
---           &lt;authentication uri="cocoon:raw:/sunrise-authuser"/&gt;
---         &lt;/handler&gt;
---       &lt;/handlers&gt;
---     &lt;/authentication-manager&gt;
---   &lt;/map:component-configurations&gt;
--- &lt;map:pipeline&gt;
---    ... document pipelines following here:
--- </pre>
--- 
--- <p>Using a unique name for each handler (only alphabetical characters and digits
--- are allowed for the handler name), the framework manages different handlers. So
--- various parts of the sitemap can be protected in different ways.</p>
--- 
--- <p>A handler is inherited to a sub sitemap. Each sub sitemap can define its own
--- handlers. These handlers are only available to the sub sitemap (and of course to
--- its sub sitemaps). However, it is not possible to redefine (overwrite) a
--- previously defined handler in a sub sitemap.</p>
--- 
--- <h2>Protecting Documents</h2>
--- 
--- <p>A document is protected by associating it with a defined handler. This is
--- done by using the <em>auth-protect</em> action and the handler parameter:</p>
--- 
--- <pre>&lt;map:match pattern="protectedresource"&gt;
---   &lt;map:act type="auth-protect"&gt;
---     &lt;map:parameter name="handler" value="portalhandler"/&gt;
---     &lt;map:generate src="source/resource.xml"/&gt;
---     &lt;map:serialize type="xml"/&gt;
---   &lt;/map:act&gt;
--- &lt;/map:match&gt;</pre>
--- 
--- <p>If this document is requested, the action checks that the defined handler
--- successfully authenticates the user. If not, the action automatically redirects
--- to the <em>redirect-to</em> document configured in the handler. (In the example
--- above this is the pipeline defined by <em>cocoon:/sunspotdemoportal</em>.</p>
--- 
--- <p>If the user is authenticated, the commands inside the <em>map:act</em>
will
--- be execute and the user gets the document itself.</p>
--- 
--- <p>So, the <em>auth-protect</em> action must be included in the pipeline
of the
--- document. It gets the handler information as a parameter. If the pipeline does
--- not use the <em>auth-protect</em> action or the parameter <em>handler</em>
is
--- missing, the document is accessible by any user.</p>
--- 
--- <p class="note">You will see learn later on how to efficiently protect several
--- documents with a handler.</p>
--- 
--- <h2>The redirect-to document</h2>
--- 
--- <p>If the requested document is not accessible by the user, the authentication
--- framework redirects to the configured <em>redirect-to</em> document. This
--- document is a mandatory element of the authentication handler.</p>
--- 
--- <p>This <em>redirect-to</em> document is an unprotected pipeline in
the sitemap.
--- For tracking which document was originally requested by the user, the
--- <em>redirect-to</em> pipeline gets the request parameter <em>resource</em>
with
--- that value. In addition all parameters specified inside the <em>redirect-to</em>
--- tag of the handler configuration are passed to the pipeline as well.</p>
--- 
--- <p>For example, the <em>redirect-to</em> document can contain a form
for the
--- user authentication. This form should invoke the real authentication process
--- that is described below. However, the document you show when an unauthorized
--- access is made, can be controlled by you by defining this <em>redirect-to</em>
--- document.</p>
--- 
--- <h1>Authenticating a User</h1>
--- 
--- <p>Usually, the <em>redirect-to</em> document of a handler contains
a form for
--- 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;/map:act&gt;
---   &lt;!-- authentication failed: --&gt;
---   &lt;map:generate src="auth_failed.xml"/&gt;
---   &lt;map:transform src="tohtml.xsl"/&gt;
---   &lt;map:serialize/&gt;
--- &lt;/map:match&gt;</pre>
--- 
--- <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 using
--- 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>
--- 
--- <ul>
--- <li>A sitemap resource (pipeline).</li>
--- <li>A distant resource, e.g. requested via HTTP.</li>
--- <li>A java class.</li>
--- </ul>
--- 
--- <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>
--- 
--- <pre>&lt;autentication-manager&gt;
---   &lt;handlers&gt;
---     &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;
---     &lt;/handler&gt;
---   &lt;/handlers&gt;
--- &lt;/autentication-manager&gt;</pre>
--- 
--- <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>
--- 
--- <pre>&lt;authentication&gt;
---     &lt;ID&gt;Unique ID of the user in the system&lt;/ID&gt;
---     &lt;role&gt;rolename&lt;/role&gt; &lt;!-- optional --&gt;
---     &lt;data&gt;
---         Any additional optional information can be supplied here. 
---         This will be stored in the session for later retrieval
---     &lt;/data&gt;
--- &lt;/authentication&gt;</pre>
--- 
--- <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 inside
--- 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
own
--- 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>
--- 
--- <pre>&lt;autentication-manager&gt;
---   &lt;handlers&gt;
---     &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;
---     &lt;/handler&gt;
---   &lt;/handlers&gt;
--- &lt;/autentication-manager&gt;</pre>
--- 
--- <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
--- pipeline.</p>
--- 
--- <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;
--- &lt;/map:act&gt;</pre>
--- 
--- <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>
--- 
--- <h1>User Management</h1>
--- 
--- <p>In addition to the authentication, the framework manages all kinds of
--- information belonging to the user. For this reason the framework creates its own
--- session context called <em>authentication</em>. All information is stored
in
--- this context in an XML structure.</p>
--- 
--- <p>The authentication information (the "authentication" scheme retrieved from
--- the authentication resource) is stored in this context, so you can retrieve and
--- change the information using the session transformer and the usual getxml,
--- setxml etc. commands, so we suggest you to read the session context document.
--- </p>
--- 
--- <p class="note">The <em>authentication</em> context is only available
to the
--- <em>session transformer</em> if the pipeline in which the transformer is
--- running, is associated with the (authentication) handler. Or putting it in other
--- words, you have to use the <em>auth-project</em> action in that pipeline.
--- Otherwise the <em>authentication</em> context is not available.</p>
--- 
--- <h2>Getting information from the context</h2>
--- 
--- <p>Each element from the context is gettable using an XML tag:</p>
--- 
--- <pre>&lt;session:getxml context="authentication" path="/authentication/ID"/&gt;
&lt;!-- Get the ID --&gt;
--- &lt;session:getxml context="authentication" path="/authentication/data/username"/&gt;</pre>
--- 
--- <p>The path expression is an absolute XPath-like expression where only concrete
--- nodes and attributes are allowed. The session transformer replaces the tag with
--- the value of the first node found in the context, this can either be text or
--- XML.</p>
--- 
--- <h2>Setting information in the context</h2>
--- 
--- <p>Using another tag, information can be stored into the context:</p>
--- 
--- <pre>&lt;session:setxml context="authentication" path="/authentication/data/usersername"&gt;
---     Mr. Sunshine
--- &lt;/session:setxml&gt;</pre>
--- 
--- <p>The path is an absolute XPath-like expression where only concrete nodes and
--- attributes are allowed. If the requested node exists, the framework changes the
--- value of that node. If the node does not exists, the framework adds it to the
--- context with the given value.</p>
--- 
--- <p>The tag is removed from the resource before it is passed to the next
--- component in the pipeline.</p>
--- 
--- <h1>Application Management</h1>
--- 
--- <p>The application management is a very useful feature for building and
--- maintaining web applications. A developer uses it to configure different
--- applications and to manage the user data for these applications.</p>
--- 
--- <h2>Configuring an Application</h2>
--- 
--- <p>A "authentication" application is related to one authentication handler, so
--- an application is part of the authentication handler configuration:</p>
--- 
--- <pre>&lt;autentication-manager&gt;
---     &lt;handlers&gt;
---         &lt;handler name="unique"&gt;
---              ....redirect-to/authentication configuration
---              &lt;applications&gt; &lt;!-- the applications for this handler
--&gt;
---                  &lt;application name="unique"&gt;
---                      &lt;load uri="loadapp"/&gt; &lt;!-- optional --&gt;
---                      &lt;save uri="saveapp"/&gt; &lt;!-- optional --&gt;
---                  &lt;/application&gt;
---              &lt;/applications&gt;
---         &lt;/handler&gt;
---     &lt;/handlers&gt;
--- &lt;/autentication-manager&gt;</pre>
--- 
--- <p>A configuration for an application consists of a unique name (only
--- alphabetical characters and digits are allowed for the application name) and
--- optional load and save resources. The application configuration can contain
--- application specific configuration values for the various parts of the
--- application, e.g. information for a portal.</p>
--- 
--- <p>On a successful authentication, the framework invokes the load resource (if
--- present) for each application of the handler. The content or result of the load
--- resource is stored in the session context.</p>
--- 
--- <p>The user does not always visit all sites or all applications at once, so it
--- is not necessary to load all applications in advance. Each application can
--- specify whether the data is loaded upon successful authentication or the first
--- time it is needed:</p>
--- 
--- <pre>....&lt;application name="unique" loadondemand="true"/&gt;...</pre>
--- 
--- <p>The load resource gets several parameters: all the values of the subnodes of
--- the "authentication" node from the authentication context (e.g. ID, role etc.)
--- and the parameter "application" containing the unique name of the application.
--- This unique name must not contain one of the characters '_', ':' or '/'.</p>
--- 
--- <p>In addition, the load and save resource get all of the parameters specified
--- inside the load / save tag of the handler configuration.</p>
--- 
--- <h2>Configuring the resources</h2>
--- 
--- <p>For managing the application the framework needs to know to which application
--- a resource belongs. So in addition to the handler parameter the auth-protect
--- action gets the application name as a second parameter:</p>
--- 
--- <pre>&lt;map:match pattern="protectedresource"&gt;
---   &lt;map:action type="auth-protect"&gt;
---     &lt;map:parameter name="handler" value="unique handler name"/&gt;
---     &lt;map:parameter name="application" value="unique application name"/&gt;
---     
---     &lt;map:generate src="source/resource.xml"/&gt;
---             ...
---   &lt;/map:action&gt;
--- &lt;/map:match&gt;
--- </pre>
--- 
--- <p>With this mechanism each application resource can easily access its (and only
--- its own) information. If a resource has no "application" parameter it can not
--- access information of any application.</p>
--- 
--- <h2>Getting, setting and saving application information</h2>
--- 
--- <p>A resource accesses its application data similar to the way it accesses the
--- authentication data:</p>
--- 
--- <pre>&lt;session:getxml context="authentication" path="/application/username"/&gt;
--- &lt;session:setxml context="authentication"  path="/application/shoppingcart"&gt;&lt;item1/&gt;&lt;item2/&gt;&lt;/session:setxml&gt;</pre>
--- 
--- <p>The path must follow the same restrictions and rules as always and it has to
--- start with "/application/".</p>
--- 
--- <h1>Module Management</h1>
--- 
--- <p>In addition to the application management feature, the framework offers a
--- facility called module management. It enhances the application management by
--- adding the possibility of configuring components for the application. For
--- example, the Cocoon portal engine needs information about the source of the
--- portal profile for the user, about where the layout is stored, etc. Each portal
--- needs this information. Assuming that a portal is an application each
--- application needs this information. As only the portal engine itself knows what
--- information it needs, the module management is a standarized way for configuring
--- such components.</p>
--- 
--- <p>The module configuration is part of the application configuration:</p>
--- 
--- <pre>&lt;autentication-manager&gt;
---   &lt;handlers&gt;
---     &lt;handler name="unique"&gt;
---       ....redirect-to/authentication configuration
---       &lt;applications&gt;  &lt;!-- the applications for this handler --&gt;
---         &lt;application name="unique"&gt;
---           ...
---           &lt;configuration name="portal"&gt;
---             ...portal configuration
---           &lt;/configuration&gt;
---         &lt;/application&gt;
---       &lt;/applications&gt;
---     &lt;/handler&gt;
---   &lt;/handlers&gt;
--- &lt;/autentication-manager&gt;</pre>
--- 
--- <p>So whenever the portal engine is asked to build the portal it can easily
--- retrieve its configuration from the current application by getting the module
--- configuration named "portal".</p>
--- 
--- <h1>User Administration</h1>
--- 
--- <p>Using the framework, it is possible to add new roles to the system and to add
--- new users. For this purpose, there are several optional entries for the
--- authentication handler which provide the needed functionality:</p>
--- 
--- <pre>&lt;autentication-manager&gt;
---   &lt;handlers&gt;
---     &lt;handler name="unique"&gt;
---              ...redirect-to/authentication configuration...
--- 
---       &lt;!-- Optional resource for loading user information --&gt;
---       &lt;load-users uri="cocoon:raw://financeresource-sunrise-loaduser"/&gt;
--- 
---       &lt;!-- Optional resource for loading roles information--&gt;
---       &lt;load-roles uri="cocoon:raw://financeresource-sunrise-roles"/&gt;
--- 
---       &lt;!-- Optional resource for creating a new user --&gt;
---       &lt;new-user uri="cocoon:raw://financeresource-sunrise-newuser"/&gt;
--- 
---       &lt;!-- Optional resource for creating a new role --&gt;
---       &lt;new-role uri="cocoon:raw://financeresource-sunrise-newrole"/&gt;
--- 
---       &lt;!-- Optional resource for changing user information --&gt;
---       &lt;change-user uri="cocoon:raw://financeresource-sunrise-newuser"/&gt;
--- 
---       &lt;!-- Optional resource for deleting a role --&gt;
---       &lt;delete-role uri="cocoon:raw://financeresource-sunrise-delrole"/&gt;
--- 
---       &lt;!-- Optional resource for deleting a user--&gt;
---       &lt;delete-user uri="cocoon:raw://financeresource-sunrise-deluser"/&gt;
---     &lt;/handler&gt;
---   &lt;/handlers&gt;
--- &lt;/autentication-manager&gt;</pre>
--- 
--- <p>The entries are described in the following subchapters. All tags can have
--- additional parameter definitions which are passed to the given resource, e.g:
--- </p>
--- 
--- <pre>&lt;!-- Optional resource for deleting a user--&gt;
--- &lt;delete-user uri="cocoon:raw://financeresource-sunrise-deluser"&gt;
---   &lt;connection&gt;database&lt;/connection&gt;
---   &lt;url&gt;db:usertable&lt;/url&gt;
--- &lt;/delete-user&gt;</pre>
--- 
--- <h2>Getting Roles</h2>
--- 
--- <p>The <em>load-roles</em> resource is invoked from the framework whenever
it
--- needs information about the available roles. This resource gets the parameter
--- "type" with the value "roles" and should deliver an XML schema with the root
--- node "roles" and for each role a sub-element "role" with a text child of the
--- rolename:</p>
--- 
--- <pre>&lt;roles&gt;
---   &lt;role&gt;admin&lt;/role&gt;
---   &lt;role&gt;guest&lt;/role&gt;
---   &lt;role&gt;user&lt;/role&gt;
--- &lt;/roles&gt;</pre>
--- 
--- <h2>Getting Users</h2>
--- 
--- <p>The <em>load-users</em> resource is called whenever information about
the
--- available users is needed. There are three different uses of this resource:</p>
--- 
--- <ul>
--- <li>Loading all users: The parameter "type" with the value "users" is passed to
--- the resource. It should then deliver all users in the system.</li>
--- <li>Loading all users of one role. The resource gets the parameters "type" with
--- the value "users" and "role" with the rolename.</li>
--- <li>Load information of one user. The resource gets the parameters "type" with
--- the value "user", "role" with the rolename and "ID" with the authentication ID
--- of the user.</li>
--- </ul>
--- 
--- <p>The XML format of the resource should look like the following:</p>
--- 
--- <pre>&lt;users&gt;
---   &lt;user&gt;
---     &lt;ID&gt;authentication ID&lt;/ID&gt;
---     &lt;role&gt;rolename&lt;/role&gt;
---     &lt;data&gt;
---        ... application specific data ...
---     &lt;/data&gt;
---   &lt;/user&gt;
---   &lt;user&gt;
---     ...
---   &lt;/user&gt;
---     ...
--- &lt;/users&gt;</pre>
--- 
--- <h2>Creating a new role</h2>
--- 
--- <p>The <em>new-role</em> resource creates a new role in the system.
It gets the
--- parameters "type" with the value "role" and "role" with the new rolename.</p>
--- 
--- <h2>Creating a new user</h2>
--- 
--- <p>The <em>new-user</em> resource creates a new user with a role. It
gets the
--- parameters <em>"type"</em> with the value <em>"user"</em>, <em>"role"</em>
with
--- the rolename and <em>"ID"</em> with the new ID for this user.</p>
--- 
--- <h2>Changing information of a user</h2>
--- 
--- <p>The <em>change-user</em> resources changes the user information.
The
--- parameters "type" with the value "user", "role" with the rolename and "ID" with
--- the ID of the user are passed to it. In addition all application-specific
--- information for this user is passed as parameters.</p>
--- 
--- <h2>Delete a user</h2>
--- 
--- <p>The <em>delete-user</em> resource will be called to delete a user.
The
--- parameter "type" with the value "user", "role" with the rolename and "ID" with
--- the ID of the user are passed as parameters.</p>
--- 
--- <h2>Delete a role</h2>
--- 
--- <p>The <em>delete-role</em> resources deletes a role. The parameters
"type" with
--- the value "role" and "role" with the rolename are passed as parameters.</p>
--- 
--- <h1>Configuration Summary</h1>
--- 
--- <p>Here is a brief summary of the authentication handler configuration:</p>
--- 
--- <pre>&lt;autentication-manager&gt;
---   &lt;handlers&gt;
---     &lt;handler name="unique"&gt;
---       &lt;!-- The redirect-to resource --&gt;
---       &lt;redirect-to uri="cocoon:raw://loginpage"/&gt;
---       &lt;!-- Authentication resource --&gt;
---       &lt;authentication uri="cocoon:raw://authenticationresource"/&gt;
--- 
---       &lt;load uri="cocoon:raw://authenticationsaveresource"&gt;
---         &lt;!-- optional parameters --&gt;
---       &lt;/load&gt;
---       &lt;!-- optional save resource --&gt;
---       &lt;save uri="cocoon:raw://authenticationsaveresource"&gt;
---         &lt;!-- optional parameters --&gt;
---       &lt;/save&gt;
--- 
---       &lt;applications&gt;
---         &lt;!-- the applications for this handler --&gt;
---         &lt;application name="unique"&gt;
--- 
---           &lt;!-- Loading/Saving --&gt;
---           &lt;load uri="cocoon:raw://loadapp"&gt;
---             &lt;!-- optional --&gt;
---             &lt;!-- optional parameters --&gt;
---           &lt;/load&gt;
---           &lt;save uri="cocoon:raw://saveapp"&gt;
---             &lt;!-- optional --&gt;
---             &lt;!-- optional parameters --&gt;
---           &lt;/save&gt;
---           &lt;!-- module configurations: --&gt;
--- 
---           &lt;configuration name="portal"&gt;
---             ...portal configuration
---           &lt;/configuration&gt;
---         &lt;/application&gt;
---       &lt;/applications&gt;
--- 
---     &lt;/handler&gt;
---   &lt;/handlers&gt;
--- &lt;/autentication-manager&gt;</pre>
--- 
--- <h1>Pipeline Patterns</h1>
--- 
--- <p>As explained in the previous chapters, the framework uses the
--- <em>auth-protect</em> action for authentication and protecting documents.
This
--- chapter shows some commonly used pipeline patterns.</p>
--- 
--- <h2>Single protected document</h2>
--- 
--- <p>For protecting a document with an authentication handler only the
--- <em>auth-protect</em> action with the parameter configuration for the handler
is
--- required.</p>
--- 
--- <p>Pattern:</p>
--- 
--- <ol>
--- <li>Pipeline matching</li>
--- <li>Using the <em>auth-protect</em> action for protecting</li>
--- </ol>
--- 
--- <p>Example:</p>
--- 
--- <pre>&lt;map:match pattern="protected"&gt;
---   &lt;map:act type="auth-protect"&gt;  &lt;!-- protect the resource --&gt;
---     &lt;map:parameter name="handler" value="myhandler"/&gt;
--- 
---     &lt;map:generate src="resource.xml"/&gt;
---     &lt;map:transform src="toHTML"/&gt;
---     &lt;map:serialize/&gt;
---   &lt;/map:act&gt;
--- &lt;/map:match&gt;</pre>
--- 
--- <p>It is very important that the <em>auth-protect</em> 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.</p>
--- 
--- <h2>Multiple protected documents</h2>
--- 
--- <p>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.</p>
--- 
--- <p>The prerequisite for this is a common matching pattern for the documents:</p>
--- 
--- <ol>
--- <li>Pipeline pattern matching</li>
--- <li>Using the <em>auth-protect</em> action for protection</li>
--- <li>Pipeline matching</li>
--- </ol>
--- 
--- <p>Example:</p>
--- 
--- <pre>&lt;map:match pattern="protected-*"&gt;
---   &lt;map:act type="auth-protect"&gt; &lt;!-- protect the resource --&gt;
---     &lt;map:parameter name="handler" value="myhandler"/&gt;
--- 
---     &lt;map:match pattern="protected-first"&gt;
---       &lt;map:generate src="resource1.xml"/&gt;
---       &lt;map:transform src="toHTML"/&gt;
---       &lt;map:serialize/&gt;
---     &lt;/map:match&gt;
---         ....
---     &lt;map:match pattern="protected-second"&gt;
---       &lt;map:generate src="resource2.xml"/&gt;
---       &lt;map:transform src="toHTML"/&gt;
---       &lt;map:serialize/&gt;
---     &lt;/map:match&gt;
---   
---   &lt;/map:act&gt;
--- &lt;/map:match&gt;</pre>
--- 
--- <p>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.</p>
--- 
--- <h2>Controlling the Application Flow</h2>
--- 
--- <p>If you want to create documents which behave different depending if you are
--- logged in or not, the <em>auth-loggedIn</em> 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 <em>act</em>
--- tag.</p>
--- 
--- <pre>&lt;map:match pattern="startpage"&gt;
--- 
---   &lt;map:act type="auth-loggedIn"&gt;  &lt;!-- check authentication --&gt;
---     &lt;map:parameter name="handler" value="myhandler"/&gt;
--- 
---     &lt;map:redirect-to uri="loggedInStartPage"/&gt;
---   &lt;/map:act&gt;
--- 
---   &lt;map:generate src="startpage.xml"/&gt;
---   &lt;map:transform src="toHTML"/&gt;
---   &lt;map:serialize/&gt;
--- &lt;/map:match&gt;</pre>
--- 
--- <p>In the example above, if the user is already logged he is redirected to the
--- <em>loggedInStartPage</em> document. If he is not logged in for the given
--- handler, the usual start page is generated.</p>
--- 
--- <p>The <em>auth-protect</em> 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:</p>
--- 
--- <pre>&lt;map:match pattern"protected"&gt;
---   &lt;map:act type="auth-protect"&gt;  &lt;!-- protect the resource --&gt;
---     &lt;map:parameter name="handler" value="myhandler"/&gt;
--- 
---     &lt;!-- Append the ID of the user to the file name --&gt;
---     &lt;map:generate src="resource_{ID}.xml"/&gt;
---     &lt;map:transform src="toHTML"/&gt;
---     &lt;map:serialize/&gt;
--- 
---   &lt;/map:act&gt;
--- &lt;/map:match&gt;</pre>
--- 
--- <p>But the <em>auth-loggedIn</em> 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 <em>auth-protect</em> action inside!</p>
--- 
--- <pre>&lt;map:match pattern"start"&gt;
--- 
---   &lt;map:act type="auth-loggedIn"&gt;  &lt;!-- check authentication --&gt;
---     &lt;map:parameter name="handler" value="myhandler"/&gt;
--- 
---     &lt;map:act type="auth-protect"&gt;  &lt;!-- give access to the context
--&gt;
---       &lt;map:parameter name="handler" value="myhandler"/&gt;
--- 
---       &lt;map:generate src="getinfofromcontext.xml"/&gt;
---       &lt;map:transform type="session"/&gt;
---       &lt;map:transform src="toHTML"/&gt;
---       &lt;map:serialize/&gt;
---     &lt;/map:act&gt;
---   &lt;/map:act&gt;
--- 
--- &lt;/map:match&gt;</pre>
--- 
--- <h2>Session Handling</h2>
--- 
--- <p>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.</p>
--- 
--- <p>The easiest way is to use the <em>encodeURL</em> transformer as the
last
--- transformation step in your pipeline. For more information about session
--- handling, have a look in the <a href="daisy:607">chapter about sessions</a>.</p>
--- 
    </body>
    </html>


Fields
======
no changes

Links
=====
no changes

Custom Fields
=============
no changes

Collections
===========
no changes

Mime
View raw message