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:

• handler  The handler name you wish to call. If you call a function, append a pair of brackets to the name like: "myHandler()".
• filename  The script only stack file name containing your handler.
• filepath  The name of the directory containing your script only stack. Note: Your stack must be located in a directory INSIDE your application folder, so the file path is relative to that folder. For example, if your stack is located in application/hooks/authenticationHooks, you will simply use hooks/authenticationHooks as your filepath. If your stack is located in application/hooks/authenticationUtilities you will use hooks/authenticationUtilities as your filepath. No trailing slash.
• params  Any parameters you wish to pass to your script. This item is optional.

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.

• authLibraryInitialized
  Called very early right after the library has been initialized.
• authPreActivate
  Called before a user is activated.
• authPostActivate
  Called after user activation.
• authPostActivateUnsuccessful
  Called after user activation failed.
• authPostActivateSuccessful
  Called after successfully activating a user.
• authExtraWhere
  Called before any database query.
• authDeactivate
  Called before deactivating a user.
• authCheckLoggedIn
  Called before checking a user's logged in state.
• authIsAdmin
  Called before checking if a particular user is a member of the admin group.
• authInGroup
  Called before checking if a particular user is a member of a particular group.
• authUsers
  Called before getting all users.
• authUser
  Called before getting a particular users.
• authUserGroups
  Called before getting the groups a particular user is a member of.
• authPostLogin
  Called after logging in.
• authPostLoginUnsuccessful
  Called after logging in failed.
• authPostLoginSuccessful
  Called after successfully logging in.
• authLogout
  Called before logging out.
• authPreAccountCreation
  Called before a new user is created.
• authPostAccountCreation
  Called after creating a new user.
• authPostAccountCreationSuccessful
  Called after successfully creating a new user.
• authPostAccountCreationUnsuccessful
  Called after creating a new user failed.
• authPActivationEmailSuccessful
  Called after sending an activation email or after returning activation data in case email activation is turned off.
• authPActivationEmailUnsuccessful
  Called after sending an activation email failed.
• authPreRegister
  Called registering a user.
• authExtraSet
  Called before inserting user data while registering a user.
• authPostRegister
  Called after registering a user.
• authUpdateLastLogin
  Called before updating the last login time.
• authPreRememberUser
  Called before turning on auto login.
• authPostRememberUser
  Called after turning on auto login.
• authRememberUserSuccessful
  Called after successfully turning on auto login.
• authRememberUserUnsuccessful
  Called after turning on auto login failed.
• authPreLoginRememberedUser
  Called before auto login of remembered users.
• authPostLoginRememberedUser
  Called after auto login of remembered users.
• authLoginRememberedUserUnsuccessful
  Called after auto login failed.
• authPostLoginRememberedUserSuccessful
  Called after a successfull auto login of remembered users.
• authIdentityCheck
  Called before the identity check for remembered users.
• authEmailCheck
  Called before checking if a particular email address exists in the database.
• authUsernameCheck
  Called before checking if a particular username exists in the database.
• authAddToGroup
  Called before adding a user to a group.
• authGroups
  Called before getting all groups.
• authGroup
  Called before getting a particular group.
• authPostFrogottenPassword
  Called after inserting a forgotten password key in the database.
• authPostFrogottenPasswordUnsuccessful
  Called after inserting a forgotten password key in the database failed.
• authPostFrogottenPasswordSuccessful
  Called after successfully inserting a forgotten password key in the database.
• authPreChangePassword
  Called before replacing a password with a new one.
• authPostChangePassword
  Called after replacing a password with a new one.
• authPostChangePasswordUnsuccessful
  Called after replacing a password with a new one failed.
• authPostChangePasswordSuccessful
  Called after successfully replacing a password with a new one.
• authPreChangePassword
  Called before processing a user's change password request.
• authPostChangePassword
  Called after processing a user's change password request.
• authPostChangePasswordUnsuccessful
  Called after processing a user's change password request failed.
• authPostChangePasswordSuccessful
  Called after successfully processing a user's change password request.
• authPreUpdateUser
  Called before updating user data.
• authPostUpdateUser
  Called after updating user data.
• authPostUpdateUserUnsuccessful
  Called after updating user data failed.
• authPostUpdateUserSuccessful
  Called after successfully updating user data.
• authPreDeleteUser
  Called before deleting a user.
• authPostDeleteUser
  Called after deleting a user.
• authPostDeleteUserUnsuccessful
  Called after deleting a user failed.
• authPostDeleteUserSuccessful
  Called after successfully deleting a user.
• authRemoveFromGroup
  Called before removing a user from a group.

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.