Authentication Stack API

Overview

The authentication stack is created and then one function is run to authenticate and other function is run to retrieve the logged in user object.

The authenticiation stack interacts with the plugins by callback functions for various sections. These callbacks are registered with the authentication stack by the plugins when they are initilaised during the authentication stack construct process. The callback function is given an object and is expected to return this object when it finishes after adding/modifying things which will then be parsed to the next callback function, it will generally have things in it set before being parsed to the first registered callback for this section.

The sections are init:: extra startup routines lookupuser:: routine to check if this is a recognised local user preauth:: run before main authentication routine is run auth:: the main authentication function postauth:: run after authentication postauthsuccess:: run after successful authentication postauthfail:: run after failed authentication displaystdform:: run before the standard login form is displayed displayerrform:: run before the login error page is displayed getauthobj:: run when getting the userobject from the authentication sessionstore:: run when data will be stored in the session

The process is given in more detail below

How the Authentication Stack Works

Startup

First the Authentication class object is constructed

This loads the configuration from the config Object. Then it runs the setup.

The setup checks to see if the alreadyloggedin module has been included in the config, if it hasn't it includes it automatically at the beginning. If 'rogo-login-form-std' has been set in the request then it stores the 'ROGO_USER' & 'ROGO_PW' from the request in a local object called form['std'] for later use.

Initiate plugins

A loop is made going through each plugin in the authentication config.

Authentication Init Object is created.

it runs the apicheck function if this says they are compatible then it will run the init function, after this it will run the register_callback_routines function. The data from this function is then parsed onto the register_callback function

Authentication

The do_authentication function is called, this is the start of the authentication routine/procedure.

PreAuth

This is run before any authentication is done.

This is the first set of callbacks run and takes a Authentication preauth object

Auth

The auth callbacks are then called with a Authentication auth object

if the returned element of the authobject is ROGO_AUTH_OBJ_SUCCESS then sets the username to be the authobject username and saves with auth plugin sucessfully authenticated.

if the returned element of the authobject is ROGO_AUTH_OBJ_LOOKUPONLY then it attempts to lookup the user using the userlookup function of the lookup stack. It then checks whats returned by this and sees if it has enough data to create a user and checks the flags from the lookup that it shouldnt create a user eg not unique user data found. If sucessfully creates user then it sets things as though it had successfully authenticated.

it then checks if the plugin says dont use other plugins if so it stops

Post Auth

This is run after authentication regardless of the status

Then the postauth callbacks are called with a Authentication postauth object

After this it checks if authentication was sucessfully.

If unsuccesfull then it increases the attempt count, and creates a Authentication postauthfail object and runs the postauthfail callback

If successfull then it creates a Authentication postauthsuccess object and runs the postauthsuccess callback and then runs stores any appropriate data in the session before ending the function

Post Auth Fail

This is run after authentication has failed

after this callback runs it checks if callback is set if so run it, then if form is set to err then run the display_error_form (which runs the callback), then if form is set to std then it runs display_std_form (which runs the callback), then if url is set then redirect to that url

Post Auth Success

This is run after authentication has succeded

User Object

This is run after authentication when the code wants the user object associated with the logged in user.

This runs a callback after initial setup and parses the Authentication getauth object that it is parsed to it (or if not exists it creates)

Form Display

display_std_form

If the display_std_form fucntion is run then it creates a Authentication displaystdform object and then includes the default login form unless the login form in config exists

display_err_form

If the display_err_form fucntion is run then it creates a Authentication displayerrform object and then includes the default errorform unless the error form in config exists

Internal Callbacks

Session Store

This is run before data is stored into a session (this makes sure that the plugins data that it wants to store in a session is stored before 'exit'

Lookup User

This is run when plugins want to determine if another plugin recognise a username, a Authentication lookupuser object is created then parsed to it.