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.