Authentication Hooks

Authentication hooks work similar like those extending the framework core. So, if you want to run your own scripts at a particular stage of the library's execution process, the hooks feature is your friend.

Enabling Authentication Hooks

The authentication hooks feature can be enabled/disabled by setting the following item in the application/config/authentication.lc file:

put TRUE into sAuthenticationConf["enableAuthenticationHooks"]

Defining an Authentication Hook

Authentication hooks are defined in the application/config/authenticationHooks.lc file. Each hook is specified as an array with this prototype:

# IN THIS CASE THE HOOK POINT IS RIGHT BEFORE UPDATING USER DATA
put "myHandler" into sAuthenticationHooks["authPreUpdateUser"]["handler"]
put "myScript.livecodescript" into sAuthenticationHooks["authPreUpdateUser"]["filename"]
put "hooks/authenticationHooks" into sAuthenticationHooks["authPreUpdateUser"]["filepath"]
put "beer" into sAuthenticationHooks["authPreUpdateUser"]["params"][1]
put "wine" into sAuthenticationHooks["authPreUpdateUser"]["params"][2]
put "snacks" into sAuthenticationHooks["authPreUpdateUser"]["params"][3]

Notes:
The array index correlates to the name of the particular hook point you want to use. In the above example the hook point is authPreUpdateUser. A list of hook points is found below. The following items should be defined in your associative hook array:

Note: The handlers in your hook files have read access to the sAuthUserA array variable declared in the Authentication.lc library using the rigAuthenticationGet(pArrayKey) function. Check the code of the Authentication.lc library for available array key names.

Multiple Calls to the Same Hook

If you want to use the same hook point with more then one script, simply make your array declaration multidimensional, like this:

put "myHandler" into sAuthenticationHooks["authPreUpdateUser"][1]["handler"]
put "myScript.livecodescript" into sAuthenticationHooks["authPreUpdateUser"][1]["filename"]
put "hooks/authenticationHooks" into sAuthenticationHooks["authPreUpdateUser"][1]["filepath"]
put "beer" into sAuthenticationHooks["authPreUpdateUser"][1]["params"][1]
put "wine" into sAuthenticationHooks["authPreUpdateUser"][1]["params"][2]
put "snacks" into sAuthenticationHooks["authPreUpdateUser"][1]["params"][3]

put "myOtherHandler" into sAuthenticationHooks["authPreUpdateUser"][2]["handler"]
put "myOtherScript.livecodescript" into sAuthenticationHooks["authPreUpdateUser"][2]["filename"]
put "hooks/authenticationHooks" into sAuthenticationHooks["authPreUpdateUser"][2]["filepath"]
put "red" into sAuthenticationHooks["authPreUpdateUser"][2]["params"][1]
put "yellow" into sAuthenticationHooks["authPreUpdateUser"][2]["params"][2]
put "blue" into sAuthenticationHooks["authPreUpdateUser"][2]["params"][3]

This permits you to have the same hook point with multiple scripts. The order you define your array will be the execution order.

Authentication hook Points

The following is a list of available hook points.

Hook Example Using authPostLoginSuccessful and authLogout as Hook Point

The following is hardly a real world example but at least it illustrates the concept. Let's say you want to log whenever an admin logs in and out. This can easily be accomplished with the help of authentication hooks.

Create a hooks script only stack file called authLog.livecodescript. In it, place the code below and save it to your application/hooks/authenticationHooks/ folder.

script "authLog"


global gRigA, gAuthUserA



on libraryStack
  if (gRigA is not an array) and (the environment is "server") then
    put "No direct script access allowed."
    exit to top
  end if

  if the short name of the target <> the short name of me then
    pass libraryStack
  end if
end libraryStack


command rigLogAdminLogin
  # sAuthUser IS A VARIABLE DECLARED IN THE AUTHENTICATION LIBRARY
  if sAuthUser["username"] is "admin" then
    rigLogMessage "info", "Admin logged in."
  end if
end rigLogAdminLogin


command rigLogAdminLogout
  if rigSessUserdata("username") is "admin" then
    rigLogMessage "info", "Admin logged out."
  end if
end rigLogAdminLogout



--| END OF authLog.livecodescript
--| Location:  ./application/hooks/authenticationHooks/authLog.livecodescript
----------------------------------------------------------------------

The next step is to add the following lines to your authenticationHooks.lc file in application/config:

put "rigLogAdminLogin" into sAuthenticationHooks["authPostLoginSuccessful"]["handler"]
put "authLog.livecodescript" into sAuthenticationHooks["authPostLoginSuccessful"]["filename"]
put "hooks/authenticationHooks" into sAuthenticationHooks["authPostLoginSuccessful"]["filepath"]


put "rigLogAdminLogout" into sAuthenticationHooks["authLogout"]["handler"]
put "authLog.livecodescript" into sAuthenticationHooks["authLogout"]["filename"]
put "hooks/authenticationHooks" into sAuthenticationHooks["authLogout"]["filepath"]

Now enable authentication hooks in application/config/authentication.lc and your are done.