**********************************************************

    auth.txt
    
    $Id$
    
    @author gERD Schaufelberger <gerd@exit0.net>
    @copyright 2004/2005 Wombat Web Bench
    @link http://wombat.exit0.net
    @package wombat
    @subpackage manual

**********************************************************

Please read authentication.txt - otherwise, you won't understand what it is all
about! 

Using Authorisation Modules
===========================
After the current page was selected and the login-process has been handled (if 
there was any) the controller tries to authorize the visitor of the page. 

See wbSite::process()

-----------------8<-----------------8<-----------------8<-----------------
// in which page we are now?	
$page	=	$this->_selectPage();

// require login-failed-template in case of failed login
$this->_tmpl->readTemplatesFromInput( $this->_page['layout'] . '.tmpl' );

// check for user login at first - login may change session id!
$this->_authenticate();

// run authorization module
$this->_authorize();

$this->_addGlobalContent();
		
// process content parts
foreach( $this->_config['content'] as $part => $default ) {
	// do some cool stuff :-) 
}

// do some more important things

// display page
$this->_tmpl->displayParsedTemplate( 'page' );

// display debugging output

return true;
-----------------8<-----------------8<-----------------8<-----------------

The authorisation is made by the method wbSite::_authorize(). It uses the global
the page-wide configuration to figure out which authorisation process is
required and it uses the global configuration to find out what has to be done 
in case of denied access. 

For example, the selected page is called "group" which results in loading the 
configuration of pages/group.xml which may look like this: 
-----------------8<-----------------8<-----------------8<-----------------
<configuration>
	<xinc href="/defines.xml" once="yes" />

	<page:page>
		<auth>
			<auth:module>Group</auth:module>
			<auth:param>German</auth:param>
		</auth>
	
		<page:content>
			<page:title>
				<page:action>staticString</page:action>
				<page:href>Group Page</page:href>
			</page:title>
			<page:head>
				<page:action>staticString</page:action>
				<page:href>Page requires user group: German</page:href>
			</page:head>
			<page:maincontent>
				<page:action>staticString</page:action>
				<page:href>User is in required group!</page:href>
			</page:maincontent>
		</page:content>
	</page:page>
</configuration>
-----------------8<-----------------8<-----------------8<-----------------

In this case the important part is the auth-section (<auth>...</auth>). This 
sections contains <auth:module> and <auth:param> - similar to the global 
configuration (showed in authentication.txt). The auth-section is optional. If
there is no per-page auth-section specified, the global auth-section
(<auth:module> and <auth:param>) will be used. Otherwise (in this case) the
page-specified auth-seciton will overwrite the default value. 

The rest of the page configuration will be used to recieve the content for the 
selecte page. If the authorisation process fails, the "denied" content will be 
shown. This content must be specified in the global configuration in section
auth:denied. This section will replace the content-section of the current page -
therefore it requires the same subsections as the section page:content. 

The decide whether a visitor is authorized to view a page's content, the quest
will be delegated to the authorisation module named in <auth:module>. Some
modules require or accept an additional parameter, this parameter must or may be 
specified in <aut:param>. 

Each authorisation module is represented by a class which implements the public 
method checkAuthorisation(). It returns true if the authorisation process 
is successful. All authorisation modules are stored in the  directory 
"include/wbAuthorize". The authetication modules are plugable - just add 
another class-file into the module directory and use it. 

In this case, the authorization module "Group" will be used. Or, in more 
programmers language: the class wbAuthorize_Group will be instanciated and the 
method wbAuthorize_Group->checkAuthorisation() will be called with the 
parameter "German". In other words, this page requires an authenticated user 
who is a member of the group "German". 

A detailed descritption of all authentication modules can be found in the 
folder doc/auth.