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/ file:

put TRUE into sAuthenticationConf["enableAuthenticationHooks"]

Defining an Authentication Hook

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

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]

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 library using the rigAuthenticationGet(pArrayKey) function. Check the code of the 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
  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 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/ and your are done.