A new document has been created.
http://cocoon.zones.apache.org/daisy/documentation/670.html
Document ID: 670
Branch: main
Language: default
Name: User Administration
Document Type: Document
Created: 8/16/05 1:26:11 PM
Creator (owner): Helma
State: publish
Parts
=====
Content
-------
Mime type: text/xml
Size: 11419 bytes
Content:
<html>
<body>
<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><autentication-manager>
<handlers>
<handler name="unique">
...redirect-to/authentication configuration...
<!-- Optional resource for loading user information -->
<load-users uri="cocoon:raw://financeresource-sunrise-loaduser"/>
<!-- Optional resource for loading roles information-->
<load-roles uri="cocoon:raw://financeresource-sunrise-roles"/>
<!-- Optional resource for creating a new user -->
<new-user uri="cocoon:raw://financeresource-sunrise-newuser"/>
<!-- Optional resource for creating a new role -->
<new-role uri="cocoon:raw://financeresource-sunrise-newrole"/>
<!-- Optional resource for changing user information -->
<change-user uri="cocoon:raw://financeresource-sunrise-newuser"/>
<!-- Optional resource for deleting a role -->
<delete-role uri="cocoon:raw://financeresource-sunrise-delrole"/>
<!-- Optional resource for deleting a user-->
<delete-user uri="cocoon:raw://financeresource-sunrise-deluser"/>
</handler>
</handlers>
</autentication-manager></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><!-- Optional resource for deleting a user-->
<delete-user uri="cocoon:raw://financeresource-sunrise-deluser">
<connection>database</connection>
<url>db:usertable</url>
</delete-user></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><roles>
<role>admin</role>
<role>guest</role>
<role>user</role>
</roles></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><users>
<user>
<ID>authentication ID</ID>
<role>rolename</role>
<data>
... application specific data ...
</data>
</user>
<user>
...
</user>
...
</users></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><autentication-manager>
<handlers>
<handler name="unique">
<!-- The redirect-to resource -->
<redirect-to uri="cocoon:raw://loginpage"/>
<!-- Authentication resource -->
<authentication uri="cocoon:raw://authenticationresource"/>
<load uri="cocoon:raw://authenticationsaveresource">
<!-- optional parameters -->
</load>
<!-- optional save resource -->
<save uri="cocoon:raw://authenticationsaveresource">
<!-- optional parameters -->
</save>
<applications>
<!-- the applications for this handler -->
<application name="unique">
<!-- Loading/Saving -->
<load uri="cocoon:raw://loadapp">
<!-- optional -->
<!-- optional parameters -->
</load>
<save uri="cocoon:raw://saveapp">
<!-- optional -->
<!-- optional parameters -->
</save>
<!-- module configurations: -->
<configuration name="portal">
...portal configuration
</configuration>
</application>
</applications>
</handler>
</handlers>
</autentication-manager></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><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></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><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></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><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></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><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></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><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></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>
Collections
===========
The document belongs to the following collections: documentation
