You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by cz...@apache.org on 2005/08/12 11:03:32 UTC
svn commit: r232243 -
/cocoon/branches/BRANCH_2_1_X/src/documentation/xdocs/developing/webapps/authentication.xml
Author: cziegeler
Date: Fri Aug 12 02:03:29 2005
New Revision: 232243
URL: http://svn.apache.org/viewcvs?rev=232243&view=rev
Log:
Apply documentation updates submitted by Ron Wheeler (rwheeler@artifact-software.com)
Modified:
cocoon/branches/BRANCH_2_1_X/src/documentation/xdocs/developing/webapps/authentication.xml
Modified: cocoon/branches/BRANCH_2_1_X/src/documentation/xdocs/developing/webapps/authentication.xml
URL: http://svn.apache.org/viewcvs/cocoon/branches/BRANCH_2_1_X/src/documentation/xdocs/developing/webapps/authentication.xml?rev=232243&r1=232242&r2=232243&view=diff
==============================================================================
--- cocoon/branches/BRANCH_2_1_X/src/documentation/xdocs/developing/webapps/authentication.xml (original)
+++ cocoon/branches/BRANCH_2_1_X/src/documentation/xdocs/developing/webapps/authentication.xml Fri Aug 12 02:03:29 2005
@@ -32,22 +32,21 @@
<p>The basic concept of the authentication framework is to protect documents generated by Cocoon.
By document we refer to the result of a request to Cocoon, this can either be the result
of a pipeline or of a reader defined in the sitemap.</p>
- <p>A document is protected by a so called (authentication) handler. A document is associated to a
- defined handler to be protected. A user can only request this document if he is authenticated
- against this handler.</p>
+ <p>A document is protected by a authentication handler. A document is associated with a
+ defined handler to provide the protection. A user's request for a document will only succeed if the handler
+ signals that the user passes authentication.</p>
<p>A handler can be used to protect several documents in the same way. If a user is authenticated
- he can access all these documents. It is possible to use different handlers, to product documents
+ he can access all these documents. It is possible to use 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>
<note>As you will see, the user management of the authentication framework is very flexible.
- You can design your application without taking into account, which backend is used for the
- user management. This can be the file-system, a SQL database, an XML database, a LDAP directory,
- just anything. Simply by developing the <em>authentication resource</em>, you can connect to any
- system. And another advantage is the flexible switching between user databases. You can for example
- use the file-system for the development process and switch than later on to a LDAP system on the
- production system. This can be done by simply changing the <em>authentication resource</em>. If you
- test this resource on your production system, you don't have to test your whole application again.
+ You can design your application without taking into account which backend is used for the
+ user management. The backend can be the file-system, a SQL database, an XML database, a LDAP directory or
+ just about anything. You can connect to any system simply by developing the <em>authentication resource</em>.
+ Another advantage is the flexible switching between user databases. For example, you can use the file-system for
+ the development process and later on, switch to a LDAP system on the production system. This is done by changing
+ the <em>authentication resource</em>. If you test this resource on your production system, you don't have to test your whole application again.
(Although in general this might be a good idea...).
</note>
</s1>
@@ -55,7 +54,7 @@
<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 framework and the actions controle the pipelines.
+ the configuration for the authentication framework and the actions control the pipelines.
The <em>auth-login</em> and the <em>auth-logout</em> action control the
authentication whereas the <em>auth-loggedIn</em> action controls the application
flow.</p>
@@ -67,18 +66,18 @@
accessible for everyone or it can be protected using this framework. The process of
requesting a document can be described as follows:</p>
<ol>
- <li>The user request a document (original document).
+ <li>The user requests a document (original document).
</li>
<li>The authentication framework checks if this document is protected. If no protection
- is specified, the response to the request is this original document.
+ is specified, the response to the request is the original document.
</li>
<li>If the document is protected, the framework checks, if the user is
authenticated to view it.
</li>
<li>If the user is authenticated, the response is the original
- document. If not the framework redirects to a special redirect-to document. This
- redirect-to document is freely configurable and can for example contain
- information about the unauthorized access and in addition a login form.
+ document. If not, the framework redirects to a special redirect-to document. This
+ redirect-to document is freely configurable and could, for example, contain
+ information about the unauthorized access and a login form.
</li>
<li>Using the login form an authentication resource can be called
with the corresponding user information (e.g. user id and password). This
@@ -95,29 +94,27 @@
can be configured for any authentication scheme. All resources are freely
configurable.</p>
<s2 title="The Authentication handler">
- <p>The basic object for authentication is the so called (authentication)
- handler. It controlles the access to the documents. Each document in the
+ <p>The basic object for authentication is the authentication handler.
+ It controlles 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 of this
+ 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 trying to authenticate a user.
+ <li>The authentication resource: A Cocoon pipeline used to 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 not
- authorized user tries to access a protected document.
+ <li>The redirect-to document: This document is displayed when a user fails authentication.
</li>
</ul>
</s2>
<s2 title="The Configuration of a Handler">
- <p>So let's have a look at the configuration. A handler can be configured in the sitemap.
- It is a so-called component configuration for the authentication manager. This
- configuration takes place in the <em>map:pipelines</em> section of a sitemap:</p>
+ <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:</p>
<source>
<map:sitemap>
...component definitions...
@@ -146,7 +143,7 @@
redefine (overwrite) a previously defined handler in a sub sitemap.</p>
</s2>
<s2 title="Protecting Documents">
- <p>A document can be protected by associating it to a defined handler.
+ <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>
<source><map:match pattern="protectedresource">
<map:act type="auth-protect">
@@ -155,8 +152,8 @@
<map:serialize type="xml"/>
</map:act>
</map:match></source>
- <p>If this document is requested, the action checks if the user is authenticated against the
- defined handler. If not, the action automatically redirects to the <em>redirect-to</em> document
+ <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>
@@ -167,9 +164,9 @@
<note>You will see learn later on how to efficiently protect several documents with a handler.</note>
</s2>
<s2 title="The redirect-to document">
- <p>If the requested document is not accessible to the user, the authentication framework
+ <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
- configuration of the authentication handler as we have seen above.</p>
+ 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>
@@ -185,13 +182,13 @@
<s1 title="Authenticating a User">
<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
+ <em>redirect-to</em> document is constructed, there is somewhere where the user has 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 with <em>login pipeline</em>.</p>
+ We refer to this pipeline as a <em>login pipeline</em>.</p>
<s2 title="The Login Process">
<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>
@@ -209,14 +206,13 @@
</map:match></source>
<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 an own
+ 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. As
- the values of these parameters were sent by a form they need to be passed on
+ 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>
+ parameter to the <em>authentication resource</em> by using the input modules concept
+ of Cocoon.</p>
<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
@@ -226,18 +222,17 @@
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.</note>
<p>If the user is not already authenticated with this handler, the framework calls
- the <em>authentication resource</em> and passes it the parameters. If this
+ 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. A session is created on
- the server (if not already done) as well.</p>
+ 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 into the
+ 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>
<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 either one field, two or
- as many fields as you need.</note>
+ the information the user has to provide. This can be as many fields as you need.</note>
</s2>
<s2 title="The authentication resource">
<p>The last chapter described the authentication process but left out
@@ -256,7 +251,7 @@
is the topic of the following chapter.</p>
<s3 title="Using a URI as the authentication resource">
<p>Using this flexible approach nearly any kind of authentication is
- possible (e.g. database, LDAP). The <em>authentication resource</em> is another
+ possible (e.g. database, LDAP). The <em>authentication resource</em> is a
mandatory configuration of the authentication handler:</p>
<source><autentication-manager>
<handlers>
@@ -270,9 +265,9 @@
</autentication-manager></source>
<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 chapter). In addition all parameters inside
+ the <em>auth-login</em> action (see previous chapter). 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 valid XML conforming to the following scheme:</p>
+ The response of this resource must contain XML conforming to the following scheme:</p>
<source><authentication>
<ID>Unique ID of the user in the system</ID>
<role>rolename</role> <!-- optional -->
@@ -288,20 +283,20 @@
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 information inside this XML scheme, the <em>ID</em> tag, is
- an unique identification for the given user inside the web application or
- more precisly inside this handler. The <em>role</em> is optional and can for example
+ <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>
- <note>As stated, the <em>role</em> element is optional, you can use your own
+ engine.</p>
+ <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.</note>
- <p>Using the <em>data</em> node the <em>authentication resource</em> can pass any
- information of the user into the session. From there you can retrieve the
+ <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>, but of course without
+ 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
@@ -336,51 +331,50 @@
<map:parameter name="handler" value="unique"/>
</map:act></source>
<p>This action logs the user out of the given handler and removes all
- information about this handler stored in the session.</p>
+ the information about this handler that is stored in the session.</p>
</s2>
</s1>
<s1 title="User Management">
- <p>In addition to the authentication the framework manages all kinds of
- information belonging to the user in XML format. For this reason the framework
+ <p>In addition to the authentication, the framework manages all kinds of
+ information belonging to the user. For this reason the framework
creates an own session context called <em>authentication</em>. All information
- is stored in this context.</p>
+ 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>
<note>The <em>authentication</em> context is only available to the
- <em>session transformer</em> if the pipeline, the transformer is
- running in, is associated to the (authentication) handler. Or putting
- it in other words: you have to use the <em>auth-project</em> action
+ <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.</note>
<s2 title="Getting information from the context">
- <p>Each information from within the context is gettable using an XML
+ <p>Each element from the context is gettable using an XML
tag:</p>
<source><session:getxml context="authentication" path="/authentication/ID"/> <!-- Get the ID -->
<session:getxml context="authentication" path="/authentication/data/username"/></source>
<p>The path expression is an absolute XPath-like expression where only
- concrete nodes and attributes are allowed. The session transformer replaced
+ 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>
</s2>
<s2 title="Setting information in the context">
- <p>Using another tag information can be stored into the
- context:</p>
+ <p>Using another tag, information can be stored into the context:</p>
<source><session:setxml context="authentication" path="/authentication/data/usersername">
Mr. Sunshine
</session:setxml></source>
- <p>Again the path is an absolute XPath-like expression where only
+ <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.</p>
+ <p>The tag is removed from the resource before it is passed to the next component in the pipeline.</p>
</s2>
</s1>
<s1 title="Application Management">
- <p>A very useful feature for building and maintaining web applications
- is the application management. It allows to configure different
+ <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>
<s2 title="Configuring an Application">
<p>A "authentication" application is related to one authentication handler, so an
@@ -403,20 +397,20 @@
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 for each application
- of the handler the load resource (if present). The content or result of the
- load resource is stored into the session context.</p>
- <p>The user does not always visit all sides or all applications at
- once. So it is not necessary to load all applications in advance when not all
- information is needed. Each application can specify if the data is loaded on
- successful authentication or the first time needed:</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 wether the data is loaded upon
+ successful authentication or the first time it is needed:</p>
<source>....<application name="unique" loadondemand="true"/>...</source>
- <p>The load resource gets several parameters: all values of the
+ <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" with the unique name of the application.
+ 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 parameters specified
+ <p>In addition the load and save resource get all of the parameters specified
inside the load / save tag of the handler configuration.</p>
</s2>
<s2 title="Configuring the resources">
@@ -434,24 +428,23 @@
</map:match>
</source>
<p>With this mechanism each application resource can easily access its
- and only its information. If a resource has no "application" parameter it can
+ (and only its own) information. If a resource has no "application" parameter it can
not access information of any application.</p>
</s2>
<s2 title="Getting, setting and saving application information">
- <p>Analogue to the access of the authentication data a resource can
- access its application data:</p>
+ <p>A resource accesses its application data similar to the way it accesses the authentication data:</p>
<source><session:getxml context="authentication" path="/application/username"/>
<session:setxml context="authentication" path="/application/shoppingcart"><item1/><item2/></session:setxml></source>
- <p>The path underlies the same restrictions and rules as always, but
+ <p>The path must follow the same restrictions and rules as always and
it has to start with "/application/". </p>
</s2>
</s1>
<s1 title="Module Management">
- <p>In addition to the application management the framework offers a facility
- called module management. It enhances the application management by the
- possibility to configure components for the application. For example the Cocoon
- portal engine needs information about where the portal profile
- for the user is retrieved from, where the layout is stored etc. Now each portal
+ <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
@@ -478,7 +471,7 @@
module configuration named "portal".</p>
</s1>
<s1 title="User Administration">
- <p>Using the framework it is possible to add new roles to the system and to
+ <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>
<source><autentication-manager>
@@ -521,7 +514,7 @@
<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 subelement "role" with a text child
+ the root node "roles" and for each role a sub-element "role" with a text child
of the rolename:</p>
<source><roles>
<role>admin</role>
@@ -534,8 +527,7 @@
about the available users is needed. There are three different uses of this
resource:</p>
<ul>
- <li>Loading all users: The resource gets the parameter "type"
- with the value "users". It should then deliver all users in the system.
+ <li>Loading all users: The parameter "type" with the value "users" is passed tothe 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.
@@ -573,19 +565,19 @@
user.</p>
</s2>
<s2 title="Changing information of a user">
- <p>The <em>change-user</em> resources changes information of a user.
- It gets the parameters "type" with the value "user", "role" with the rolename
- and "ID" with the ID of the user. In addition all - application specific -
- information of this user is send as parameters.</p>
+ <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>
</s2>
<s2 title="Delete a user">
- <p>The <em>delete-user</em> resource should delete a user. It gets the
- parameters "type" with the value "user", "role" with the rolename and "ID" with
- the ID of the user.</p>
+ <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>
</s2>
<s2 title="Delete a role">
- <p>The <em>delete-role</em> resources deletes a role. It gets the
- parameters "type" with the value "role" and "role" with the rolename .</p>
+ <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>
</s2>
</s1>
<s1 title="Configuration Summary">
@@ -635,7 +627,7 @@
<s1 title="Pipeline Patterns">
<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
- common used pipeline patterns for using this framework.</p>
+ commonly used pipeline patterns.</p>
<s2 title="Single protected document">
<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>
@@ -656,7 +648,7 @@
<map:serialize/>
</map:act>
</map:match></source>
- <p>It is very important that the <em>auth-protect</em> action wrapps the real
+ <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>
@@ -696,13 +688,13 @@
</map:act>
</map:match></source>
<p>Very important - as explained with the single document pattern - is
- the leading match before the action is performed. The second match is required
+ the leading match before the action is performed. The subsequent matches are required
to check which pipeline to use.</p>
</s2>
<s2 title="Controlling the Application Flow">
- <p>If you want to create documents which behave different wheather you
- are logged in or not, the <em>auth-loggedIn</em> action is the component to
- controll your application flow. This action checks if the user is authenticated
+ <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>
<source><map:match pattern="startpage">
@@ -755,7 +747,7 @@
</map:match></source>
</s2>
<s2 title="Session Handling">
- <p>If a user is authenticated the user has a session. However, care has to be taken that
+ <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