Extended Authentication Interface

Site Map

Home

Application Guide
	Quick Start
	PHP and ASP
	Writing Apps
	Applications
	Tutorials
		Replication
		Postgres Interface
		XML Processing
		Using XPath
		Binary Object
		Using HttpRequest
		SmtpRequest
		Session
		Meta Data
		Iterators
		Memb Services
		Page Look&feel
		Authentication+
		Questionnaires
		Message Groups
		Form Handling
	Samples
Reference
Community
Contact Whitebeam
To-Do
Download
Credits
Licence
Whitebeam Users

Extended Authentication Interface

Subject

The Whitebeam system comes with an authentication system bundled. This bundled system is entirely secure, but depends on the behaviour of individual browsers; this makes customising the login and authentication processes and their behaviour difficult. The extended authentication module is intended to allow the designer to extend this behaviour simply.

The following topics are covered:

Formal Definitions

Formal defintions for the extended authentication interface can be found here.

Overview

It is important to be aware that for most of the macrotags implemented for extended authentication, a corresponding javaScript function is available that achieves the same effect. Indeed such macrotags invoke their corresponding javaScript function. The "extauth" module has been designed such that these functions should not be called directly, nor should there be any need to call them.

Dependencies

These features are immediately available by including the file extauth.inc. Unlike many Whitebeam include files, this file should generally be included immediately at the top of the file, outside any HTML. This will allow the authentication system to decide whether any HTML will be generated. Note that the script below does not invoke any authentication at-all.


<rb:include src="extauth.inc"/>
<html>
<head>
<title>"A Simple Presentation Page"</title>
</head>
<body>
<p>Hello World!</p>
</body>
</html>

Important note: The above module makes use of browser-cookie technology. Most modern browsers consider cookies to be private-data and protect them accordingly, but you should be aware that if a cookie is somehow stolen from a machine where a user is logged-in, then access could be gained to the system.

At no time is any user information (particularly password) stored in this cookie. The cookie is simply a session identifier.

Return to top

Detailed Usage

Authentication systems generally support the functions described in the following table, which also shows how the extauth module maps onto this functionality.

Log-in	ExtAuth supports log-in of users, and automatic prompting for login upon failed authentication.
Log-out	ExtAuth supports log-out of user. Users can be auto logged-out after a timeout. A default of 30 minutes is enforced by the Whitebeam system if a session expires through non-use.
Identification	ExtAuth allows the current user to be identified by the pattern-page. This information is provided in the form of a unique user-name (uName) which can be passed to the membership system or contacts template to retrieve further information.
User types and communities	ExtAuth allows the user to be authenticated as a member of Communities and Organisational Units (eg. Administrator, User, Guest, Finance.) The currently active user-type or Community is made available to the pattern-page.
Optional authentication	Authentication is not black-and-white, so optional authentication allows behaviour to be defined programmatically within the pattern-page.
User management	ExtAuth DOES NOT provide any user management facilities. For this, use the Whitebeam membership abstraction, or the Whitebeam contacts template directly.

A simple authenticated page

The fundamental requirement of an authenticated page it the ability to protect its contents. The following example will only display the "Hello World!" message if the user is already logged-in, and belongs to the Community of "users". If not logged in, a default "Authentication failed!" message is displayed.


<rb:include src="extauth.inc"/>
<rbm:extauth community="users">

<html>
<body>
<p>Hello World!</p>
</body>
</html>

</rbm:extauth>

Note that any portion of the page may be wrapped in these tags, as long as basic HTML rules regarding overlapping tags are observed.

The following code is valid:


<rb:include src="extauth.inc"/>

<html>
<body>

<rbm:extauth community="users">
<p>Hello Secure user!</p>
</rbm:extauth>

<p>Hello World!</p>
</body>
</html>

The following code is not-valid: (Note that the <body> tag is secured, but the </body> tag is not)


<rb:include src="extauth.inc"/>
<rbm:extauth community="users">

<html>
<body>
<p>Hello Secure user!</p>

</rbm:extauth>

<p>Hello World!</p>
</body>
</html>

A page which identifies the logged-in user

The next-step from the page above is to identify the user, and the user-status. The extauth module provides access to some JavaScript variables to assist in this. The variables are:


extauth.sessionUser

extauth.sessionComm

extauth.sessionAuth

Thus, the following page code:


<rb:include src="extauth.inc"/>
<rbm:extauth community="superhero">
<html>
<body>
<p>
Username is: <rb:eval expr="extauth.sessionUser"/><br>
Community is: <rb:eval expr="extauth.sessionComm"/><br>
Authenticated: <rb:eval expr="extauth.sessionAuth"/><br>
</p>
</body>
</html>
</rbm:extauth>

Might produce the following result for a logged-in user:

Username is: superman
Community is: superheros
Authenticated: true

Changing behaviour upon failed login

In the previous examples, a very basic failure message is inserted into the page for a logged-out user. This behaviour can be changed in the following ways:

Silently ignore the fact that the user is not logged-in.
Completely and silently ignore the secured text.
Request that a login page be displayed.

This is achieved by extending the <rbm:extauth> tag as follows:

<rbm:extauth community="users" mandatory="no">

The "mandatory" attribute defaults to "yes". Setting it to "no" will cause the extauth system to attempt to authenticate the user, but failure to do so will allow the page to be displayed anyway. If the user is not authenticated, then extauth.sessionUser contains an empty string, and extauth.sessionAuth is set to false. It is assumed that the pattern-page will use this information to display different text to a logged-out user.

<rbm:extauth community="users" authfail="ignore">

The "authfail" attribute is only used if mandatory is NOT set to "no" and the user is not logged-in. Setting it to the keyword "ignore" supresses the default "Authentication Failed!" message.

<rbm:extauth community="users" authfail="login-page.rhtm">

The most commonly required behaviour if authentication fails if for the user to be presented with a login-page. In the example above the user is diverted to the page "login-page.rhtm".

Operating with multiple communities

It is possible to specify a list of communities:

<rbm:extauth community="admin,users,guest">

This will cause the authentication of the user to be checked against each community in turn, and stop as soon as the first match is made. The resulting match will be placed into the


extauth.sessionUser

variable so that you know what level of access the user has.

You can also specify multiple different

<rbm:extauth>

tags to cause different chunks of page to be displayed for different users:


<rb:include src="extauth.inc"/>
<html>
<body>

Everybody sees this piece of the page!<br>

<rbm:extauth community="users,admin" authfail="ignore">
Users and administrators see this part of the menu!<br>
</rbm:extauth>

<rbm:extauth community="users" authfail="ignore">
Only users will see this.<br>
</rbm:extauth>

<rbm:extauth community="admin" authfail="ignore">
Only administrators see this part of the menu!<br>
</rbm:extauth>

</body>
</html>

The login page

The extauth system provides assistance for the login process using the <rbm:extlogin> tag. Below is a simple example, with explanations following:


<rb:include src="extauth.inc"/>
<rbm:extlogin community="user,guest" authok="authok.rhtm">
 
<html>
<head>
<title>Login page</title>
</head>
<body>
 
<p>Please provide either a user or administrator login</p>
<form default="submit" method="post" action="login.rhtm"'>
   <br>User:
   <input type="text" name="sessionUser" rb:eval="value#extauth.sessionUser">
   <br>Pass:
   <input type="password" name="sessionPass" value=""><br>
   <br>Timeout (mins):
   <input type="number" name="sessionExp" value="0"><br>
</form>
 
</body>
</html>
 
</rbm:extlogin>

As expected, the script first includes the extauth.inc file to provide the required functionality, then we encapsulate a form in the <rbm:extlogin> tags.

The form must follow the following rules:

The form must post back to its own page (Method may be "post" or "get".)
The form must provide a text field called "sessionUser" which has the name of the user logging-in.
The form must provide a password field called "sessionPass" which has the password for this user.
OPTIONAL: The form can provide a value (number) in minutes which is the session timeout for the login. If this is set higher than the Whitebeam session timeout, it is ignored.
OPTIONAL: Providing a text field of "sessionComm" allows the form to override the "community" attribute in the <rbm:extlogin> tag.

The "community" attribute of the <rbm:extlogin> tag provides a list of communities that the user must be a member of for login to succeed. To allow login to ANY community, set the sessionComm form field equal to the sessionUser form field (This will require client-side script) The user will still need to provide a valid user-password.

The "authok" attribute of the <rbm:extlogin> tag provides the filename of a page that will be presented if login is successful. If this is missed, the form is not displayed, and a very basic message is displayed. If set to "ignore" then no redirection takes place.

An alternative method of using the login tag is to provide username, password and expiry values to the tag. While these values are over-ridden by any formdata that is present (per the example above), it can be used to log-in for example as a newly registered user.

Note: The example below is incomplete as there is no code to set the username and password variables.


<rb:include src="extauth.inc"/>
 
<html>
<head>
<title>You are now registered</title>
</head>
<body>
 
<rbm:extlogin rb:eval="user#username" rb:eval1="password#password"
			 community="user,guest" authok="ignore"/>

And have been logged in... 

</body>
</html>

See also the notes section for details of logging out using a JavaScript call.

The logout page

The extauth system provides a logout process using the <rbm:extlogout> tag. This tag does not actually log the user out until the tag is closed, so you can display an appropriate logout message by putting it INSIDE the logout tag. Below are two examples, with explanations following:


<rb:include src="extauth.inc"/>
<rbm:extlogout/>

<html>
<head>
<title>Now logged-out</title>
</head>
<body>
<h1>You are now logged out</h1>
</body>
</html>

The above is the simplest use of <rbm:extlogout>. It ensures the user is logged out, and displays a static message.


<rb:include src="extauth.inc"/>
 
<rbm:extlogout>
 
<html>
<head>
<title>Now logged-out</title>
</head>
<body>
<h1>You are now logged out</h1>
You were previously logged in as : <rb:eval expr="extauth.sessionUser"/><br>
</body>
</html>
 
</rbm:extlogout>

In this second example, the user is logged-out, but the page is encapsulated INSIDE the logout tags. This allows the page to present an appropriate "goodbye" message.

See also the notes section for details of logging out using a JavaScript call.

Return to top

Whitebeam release 1.3.36

View XML source of this page

(loadtime : 8ms)

Extended Authentication Interface

Subject