Authentication Handler Reference

Please find OTP specific handlers in chapter One-Time Password Authentication.

rigAuthLogin( pIdentity, pPassword, pRemember )

Logs the user in.

Parameters

This function returns TRUE if the user was successfully logged in, otherwise it returns FALSE.

Example:

put FALSE into tRemember
# CHECK IF THERE IS A POST VARIABLE remember
put rigVarPost("remember[]") into tPostRemember
if tPostRemember <> FALSE then
  # CHECK VALUE
  if tPostRemember[1] is 1 then
    put TRUE into tRemember
  end if
end if

get rigAuthLogin(rigVarPost("identity"), rigVarPost("password"), tRemember)

Note: For security reasons think about setting gConfig["sess_expire_on_close"] in application/config/config.lc to TRUE. Otherwise, in case you don't log out, as long as the session cookie has not expired protected pages can be accessed without password even if you close the browser and even if the pRemember parameter is not set to TRUE.

rigAuthLogout

Logs the user out.

Example:

command logout
  # LOG USER OUT
  rigAuthLogout

  # GET AUTHENTICATION MESSAGES
  put rigAuthMessages() into tMessages

  rigSetSessFlashdata "message", tMessages
  
  # REDIRECT TO THE LOGIN PAGE
  rigRedirect "/auth/login"
end logout

rigAuthRegister( pUsername, pPassword, pEmail, pExtraData, pGroupname )

Register (create) a new user.

Parameters

This function returns a user ID if the user was successfully created, otherwise it returns FALSE.

# GET ACCOUNT DATA
if $_POST is an array then
  put toLower(rigVarPOST("first")) && toLower(rigVarPOST("last")) into tUserName
  put rigVarPOST("password") into tPassword
  put rigVarPOST("email") into tEmail
  
  put rigVarPOST("first") into tExtraData["firstName"]
  put rigVarPOST("last") into tExtraData["lastName"]
  put rigVarPOST("company") into tExtraData["company"]
  put rigVarPOST("phone") into tExtraData["phone"]
end if

put 2 into tGroups["1"]
put 3 into tGroups["2"]

put rigAuthRegister(tUserName, tPassword, tEmail, tExtraData, tGroups) into tRegistration

Note: The default URI used for activating a new user is "auth/activate". This means you should provide a controller called "auth" including a handler called "activate" to process user activation. To specify your own URI segments you need to set the fourth parameter using the array key "activationLink" to "yourController/yourHandler". Of course, replace "yourController/yourHandler" with your URI segments.

rigAuthUpdate( pID, pData )

Update user data.

Parameters

This function returns TRUE if the user was successfully updated, otherwise it returns FALSE.

Example:

# GET USER ID
put rigFetchSegment(3) into tID

# CHECK POST ARRAY DATA
if $_POST is an array then
  # VALIDATE THE REQUEST
  if tID <> rigVarPOST("hiddenUserID") then
    rigLogMessage "error", "This form post did not pass the security check.", TRUE
  end if
  
  put rigVarPost("phone") into tData["phone"]
  
  get rigAuthUpdate(tID, tData)
end if

rigAuthDeleteUser( pID )

Delete a user.

Parameters

This function returns TRUE if the user was successfully deleted, otherwise it returns FALSE.

Example:

# GET USER ID
put rigFetchSegment(3) into tID

# CHECK THE USER LEVEL
if (rigAuthLoggedIn() is TRUE) and (rigAuthIsAdmin() is TRUE) then
  put rigAuthDeleteUser(tID) into tDeleted
end if

rigAuthForgottenPassword( pIdentity, pExtraData )

Resets the user's password by emailing the user a reset code.

Parameters

This function returns TRUE if the user's password was reset successfully. It returns an array containing values for "identity" and "forgottenPasswordCode" in case sAuthenticationConf["sendEmails"] is set to FALSE.

# CALL THE rigAuthForgottenPassword FUNCTION TO SEND A RESET CODE TO THE USER
put rigAuthForgottenPassword(rigVarPOST("email")) into tResetPasswordSent

if tResetPasswordSent is TRUE then
  put rigAuthMessages() into tMessages
  
  rigSetSessFlashdata "message", tMessages
  rigRedirect "/auth/login"
else
  put rigAuthErrors() into tErrors
  
  rigSetSessFlashdata "message", tErrors
  rigRedirect "auth/forgotPassword"
end if

Note: The default URI used to process forgotten password requests is "auth/resetPassword". This means you should provide a controller called "auth" including a handler called "resetPassword". To specify your own URI segments you need to set the second parameter using the array key "passwordResetLink" to "yourController/yourHandler". Of course, replace "yourController/yourHandler" with your URI segments.

rigAuthLoggedIn()

Check to see if a user is logged in.

This function returns TRUE if the user is logged in, otherwise it returns FALSE.

In case two-factor authentication is activated the function may return "pending" if the user logged in successfully but has still not transferred a valid one-time password. If the user logged in successfully and requested a QR code to set up two-factor authentication but still not transferred a valid one-time password the function returns "pendingOTPsetup". Please read about OTP in chapter One-Time Password Authentication.

Example:

# CHECK IF USER IS LOGGED IN
if rigAuthLoggedIn() is FALSE then
  rigRedirect "/auth/login"
end if

rigAuthIsAdmin( pID )

Check to see if the currently logged in user is an administrator.

Parameters

This function returns TRUE if the user is an admin, otherwise it returns FALSE.

Example:

# CHECK THE USER LEVEL
if rigAuthIsAdmin() is FALSE then
  # REDIRECT TO HOME PAGE BECAUSE USER IS NOT ALLOWED TO VIEW ADMIN CONTENT
  rigRedirect "/"
end if

rigAuthInGroup( pGroup, pID )

Check if user is a member of a specific group.

Parameters

This function returns TRUE if the user is a member of any given group, otherwise it returns FALSE.

Example:

# SINGLE GROUP (BY NAME)
put "other" into tGroup
if rigAuthInGroup(tGroup) then
  rigSetSessFlashdata "message", "You must be a member of group other to view this page."
  rigRedirect "/"
end if

# SINGLE GROUP (BY ID)
put 1 into tGroup
if rigAuthInGroup(tGroup) then
  rigSetSessFlashdata "message", "You must be a member of group 1 to view this page."
  rigRedirect "/"
end if

# MULTIBLE GROUPS (BY NAME)
put "members" into tGroups[1]
put "other" into tGroups[2]
if rigAuthInGroup(tGroups) then
  rigSetSessFlashdata "message", "You must be a member of group members or of group other to view this page."
  rigRedirect "/"
end if

# MULTIBLE GROUPS (BY ID)
put 2 into tGroups[1]
put 3 into tGroups[2]
if rigAuthInGroup(tGroups) then
  rigSetSessFlashdata "message", "You must be a member of group 2 or of group 3 to view this page."
  rigRedirect "/"
end if

# MULTIBLE GROUPS (BY NAME AND ID)
put 2 into tGroups[1]
put "other" into tGroups[2]
if rigAuthInGroup(tGroups) then
  rigSetSessFlashdata "message", "You must be a member of group 2 or of group other to view this page."
  rigRedirect "/"
end if

rigAuthUsernameCheck( pUsername )

Check if there is an entry in the DB regarding the username provided.

Parameters

This function returns TRUE if the user is registered, otherwise it returns FALSE.

Example:

# GET POST DATA
if $_POST is an array then
  put rigVarPOST("username") into tUsername
  put rigVarPOST("password") into tPassword
  put rigVarPOST("email") into tEmail

  put rigVarPOST("first") into tExtraData["firstName"]
  put rigVarPOST("last") into tExtraData["lastName"]
  put rigVarPOST("company") into tExtraData["company"]
  put rigVarPOST("phone") into tExtraData["phone"]
end if

put 2 into tGroups["1"]
put 3 into tGroups["2"]

if rigAuthUsernameCheck(tUsername) is FALSE then
  put rigAuthRegister(tUserName, tPassword, tEmail, tExtraData, tGroups) into tRegistration
end if

rigAuthEmailCheck( pEmail )

Check if there is an entry in the DB regarding the email address provided.

Parameters

This function returns TRUE if the user is registered, otherwise it returns FALSE.

Example:

# GET POST DATA
if $_POST is an array then
  put rigVarPOST("username") into tUsername
  put rigVarPOST("password") into tPassword
  put rigVarPOST("email") into tEmail

  put rigVarPOST("first") into tExtraData["firstName"]
  put rigVarPOST("last") into tExtraData["lastName"]
  put rigVarPOST("company") into tExtraData["company"]
  put rigVarPOST("phone") into tExtraData["phone"]
end if

put 2 into tGroups["1"]
put 3 into tGroups["2"]

if rigAuthUsernameCheck(tEmail) is FALSE then
  put rigAuthRegister(tUserName, tPassword, tEmail, tExtraData, tGroups) into tRegistration
end if

rigAuthIdentityCheck( pIdentity )

Identity check for remembered users (auto-login).

Parameters

This function returns TRUE if the user is registered, otherwise it returns FALSE.

Example:

# GET USER DATA
put rigAuthUser(tID) into tQueryResult
if (tQueryResult <> FALSE) and (tQueryResult is an array) then
  put rigDbRow() into tUser
end if

put rigVarPOST("identity") into tData["identity"]
put rigVarPOST("first") into tData["firstName"]
put rigVarPOST("last") into tData["lastName"]

if (tData["identity"] is tUser["username"]) or (tData["identity"] is tUser["email"]) or (rigAuthIdentityCheck(tData["identity"]) is FALSE) then
  get rigAuthUpdate(tUser["id"], tData)
end if

rigAuthIsMaxLoginAttemptsExceeded( pIdentity )

If login attempt tracking is enabled, checks to see if the number of failed login attempts for this identity or ip address has been exceeded. Login attempt limits are not enforced in the library.

Parameters

This function returns TRUE if maximum login attempts is exceeded, FALSE if not or if login attempts not tracked.

Example:

put "rabit@revigniter.com" into tIdentity

if rigAuthIsMaxLoginAttemptsExceeded(tIdentity) is TRUE then
  rigSetSessFlashdata "message", "You have too many login attempts."
  rigRedirect "/"
end if

rigAuthGetAttemptsNum( pIdentity )

Get number of login attempts from a given ipAddress or identity.

Parameters

This function returns the number of failed login attempts for this identity or ip address.

Example:

put "rabit@revigniter.com" into tIdentity

put rigAuthGetAttemptsNum(tIdentity) into tNumAttempts

rigAuthIncreaseLoginAttempts( pIdentity )

If login attempt tracking is enabled, records another failed login attempt for this identity or ip address. This function is automatically called by the rigAuthLogin() function in case the login failed.

Parameters

This function returns TRUE if increasing the number was successful, otherwise it returns FALSE.

rigAuthClearLoginAttempts( pIdentity, pExpirePeriod )

Clears all failed login attempt records for this identity or this ip address. This function is automatically called by the rigAuthLogin() function if the login succeeded.

Parameters

rigAuthUser( pID )

Get a particular user.

Parameters

This function returns FALSE in case there is no user data with the given id, otherwise it returns the result of the database query as an array.

Example:

# GET USER DATA
put rigAuthUser() into tQueryResult
if (tQueryResult <> FALSE) and (tQueryResult is an array) then
  put rigDbRow() into tUser
end if

# NOW tUser CONTAINS THE USER RECORD
# tUser["id"], tUser["ipAddress"], tUser["username"], tUser["password"], tUser["email"],
# tUser["activationCode"], tUser["forgottenPasswordCode"], tUser["forgottenPasswordTime"],
# tUser["rememberCode"], tUser["createdOn"], tUser["lastLogin"], tUser["active"],
# tUser["firstName"], tUser["lastName"], tUser["company"], tUser["phone"]

rigAuthUsers( pGroupIDs )

Get the users.

Parameters

This function returns FALSE in case there is no user data with the given group id, otherwise it returns the users who are members of the groups specified by the parameter or all users if the parameter is empty.

Example:

# GET ALL ADMINS
put rigAuthUsers(1) into tAdmins

# tAdmins IS NOW A MULTIDIMENSIONAL NUMBERED ARRAY
# CONTAINING ALL USERS WHO ARE A MEMBER OF THE ADMIN GROUP

put 0 into tCounter
repeat for each key tRecord in tAdmins
  add 1 to tCounter

  put tAdmins[tCounter] into tUser

  put empty into tRowData

  put "Username:" && tUser[3] & ", " after tRowData
  put "First Name:" && tUser[13] & ", " after tRowData
  put "Last Name:" && tUser[14] & ", " after tRowData
  delete char -2  to -1 of tRowData

  put tRowData & "<br />" & return after tResultData
end repeat

rigAuthGroup( pID )

Get a specific group.

Parameters

This function returns FALSE in case there is no group data with the given id, otherwise it returns a group, the result of the database query as a numbered array.

Example:

# GET MEMBERS GROUP
put rigAuthGroup(2) into tGroup

# tGroup IS NOW A MULTIDIMENSIONAL NUMBERED ARRAY
# CONTAINING 1 GROUP RECORD

put tGroup[1] into tGroupRow

put "Group ID:" && tGroupRow[1] & ", " after tRowData
put "Group Name:" && tGroupRow[2] & ", " after tRowData
put "Group Description:" && tGroupRow[3] & ", " after tRowData
delete char -2  to -1 of tRowData

rigAuthGroups()

Get the groups.

This function returns FALSE in case there are no groups, otherwise it returns all groups, the result of the database query as a numbered array.

Example:

# GET GROUPS
put rigAuthGroups() into tGroups

# tGroups IS NOW A MULTIDIMENSIONAL NUMBERED ARRAY
# CONTAINING ALL GROUP RECORDS

put 0 into tCounter
repeat for each key tRecord in tGroups
  add 1 to tCounter

  put tGroups[tCounter] into tGroupRow

  put empty into tRowData

  put "Group ID:" && tGroupRow[1] & ", " after tRowData
  put "Group Name:" && tGroupRow[2] & ", " after tRowData
  put "Group Description:" && tGroupRow[3] & ", " after tRowData
  delete char -2  to -1 of tRowData

  put tRowData & "<br />" & return after tResultData
end repeat

rigAuthUserGroups( pID )

Get groups of a specific user.

Parameters

This function returns FALSE in case the user with the given id is not a member of any group, otherwise it returns all groups the user is a member of, the result of the database query as a numbered array.

Example:

# GET ALL GROUPS THE ADMIN IS A MEMBER OF
put rigAuthUserGroups(1) into tUserGroups

# tUserGroups IS NOW A MULTIDIMENSIONAL NUMBERED ARRAY
# CONTAINING GROUP RECORDS

put 0 into tCounter
repeat for each key tRecord in tUserGroups
  add 1 to tCounter

  put tUserGroups[tCounter] into tGroupRow

  put empty into tRowData

  put tGroupRow[2] into tRowData

  put tRowData & "," after tResultData
end repeat
if char -1 of tResultData is "," then
  delete char -1 of tResultData
end if

rigAuthAddToGroup pGroupID, pUserID

Add user to a group.

Parameters

Example:

# GET USER ID
put rigFetchSegment(3) into tUserID

# CHECK POST ARRAY DATA
if $_POST is an array then
  # VALIDATE THE REQUEST
  if tUserID <> rigVarPOST("hiddenUserID") then
    rigLogMessage "error", "This form post did not pass the security check.", TRUE
  else
  
    rigAuthAddToGroup 3, tUserID
  end if
end if

rigAuthRemoveFromGroup( pGroupIDs, pUserID )

Remove user from group.

Parameters

This function returns TRUE if the user was successfully removed from the group(s), otherwise it returns FALSE.

Example:

# PASS AN ARRAY OF GROUP ID's AND A USER ID
put 2 into tGroups[1]
put 5 into tGroups[2]
put 7 into tGroups[3]
get rigAuthRemoveFromGroup(tGroupIDs, tUserID)

# PASS A SINGLE ID AND USER ID
get rigAuthRemoveFromGroup(tGroupID, tUserID)

# PASS AN EMPTY GROUP ID TO REMOVE THE USER FROM ALL GROUPS
get rigAuthRemoveFromGroup(, tUserID)

rigAuthMessages( pPrefix, pSuffix )

Get authentication messages.

Parameters

This function returns all authentication messages as a string.

Example:

# IF REGISTRATION WAS SUCCESSFUL REDIRECT TO AUTHENTICATION PAGE
if tRegistration <> FALSE then    
  put rigAuthMessages() into tMessages
  rigSetSessFlashdata "message", tMessages
  rigRedirect "/auth"
end if

rigAuthSetMessageDelimiters pStartDelimiter, pEndDelimiter

Set the message delimiters.

Parameters

Example:

# IF REGISTRATION WAS SUCCESSFUL REDIRECT TO AUTHENTICATION PAGE
if tRegistration <> FALSE then
  rigAuthSetMessageDelimiters "<p><strong>", "</strong></p>"
    
  put rigAuthMessages() into tMessages
  rigSetSessFlashdata "message", tMessages
  rigRedirect "/auth"
end if

rigAuthErrors( pPrefix, pSuffix )

Get authentication errors.

Parameters

This function returns authentication errors as a string.

get rigAuthLogin(rigVarPost("identity"), rigVarPost("password"), tRemember)

# IF LOGIN IS UNSUCCESSFUL REDIRECT BACK TO THE LOGIN PAGE
if it is FALSE then
  put rigAuthErrors() into tErrors
  rigSetSessFlashdata "message", tErrors
  rigRedirect "auth/login"
end if

rigAuthSetErrorDelimiters pStartDelimiter, pEndDelimiter

Set the message delimiters.

Parameters

Example:

rigAuthSetErrorDelimiters "<p><strong>", "</strong></p>"
  
get rigAuthLogin(rigVarPost("identity"), rigVarPost("password"), tRemember)

# IF LOGIN IS UNSUCCESSFUL REDIRECT BACK TO THE LOGIN PAGE
if it is FALSE then
  put rigAuthErrors() into tErrors
  rigSetSessFlashdata "message", tErrors
  rigRedirect "auth/login"
end if

rigAuthFetchConfigItem( pItem, pIndex )

Get a value from the configuration settings array.

Parameters

Example:

# GET MIN / MAX PASSWORD LENGTH
put rigAuthFetchConfigItem("minLengthPassword") into tMinPasswordLength
put rigAuthFetchConfigItem("maxLengthPassword") into tMaxPasswordLength

# CHANGE PASSWORD
put rigAuthFetchConfigItem("identityColumn") into tIdentityCol
put tUser[tIdentityCol] into tIdentity
put rigAuthResetPassword(tIdentity, rigVarPOST("newPassword")) into tChange

# GET THE NAME OF THE USERS TABLE
put rigAuthFetchConfigItem("tables", "users") into tUsersTableName

rigAuthActivate( pID, pCode )

Activate a user account.

Parameters

This function returns TRUE in case user activation was successful, otherwise it returns FALSE.

Example:

# GET USER ID AND ACTIVATION CODE
put rigFetchSegment(3) into tID
put rigFetchSegment(4) into tCode
put FALSE into tActivation

# ACTIVATE USER
if tCode <> FALSE then
  put rigAuthActivate(tID, tCode) into tActivation
  
else if rigAuthIsAdmin() is TRUE then
  put rigAuthActivate(tID) into tActivation
end if    

rigAuthDeactivate( pID )

Deactivate a user.

Parameters

This function returns TRUE in case user deactivation was successful, otherwise it returns FALSE.

Example:

if (rigAuthLoggedIn() is TRUE) and (rigAuthIsAdmin() is TRUE) then
  put rigAuthDeactivate(tID) into tDeactivated
end if

rigAuthForgottenPasswordCheck( pCode )

Check the code used to reset a password.

Parameters

This function returns user data as an array in case the provided code was checked successfully, otherwise it returns FALSE.

Example:

put rigFetchSegment(3) into tForgottenPasswordCode

if tForgottenPasswordCode is FALSE then
  rigShow404
end if

put rigAuthForgottenPasswordCheck(tForgottenPasswordCode) into tUser

rigAuthClearForgottenPasswordCode( pCode )

Delete the forgotten password code.

Parameters

This function returns TRUE in case the code used to reset a password was deleted successfully, otherwise it returns FALSE.

Example:

if tUser["id"] <> rigVarPOST("hiddenUserID") then
  get rigAuthClearForgottenPasswordCode(tForgottenPasswordCode)
  rigLogMessage "error", "This reset password form post did not pass the security check.", TRUE
end if

rigAuthResetPassword( pIdentity, pNewPassword )

Replace password with a new one.

Parameters

This function returns TRUE in case the old password was replaced successfully, otherwise it returns FALSE.

Example:

# RESET THE PASSWORD
put rigAuthFetchConfigItem("identityColumn") into tIdentityCol
put tUser[tIdentityCol] into tIdentity

put rigAuthResetPassword(tIdentity, rigVarPOST("newPassword")) into tChange

rigAuthChangePassword( pIdentity, pOldPassword, pNewPassword )

Validate and change a password.

Parameters

This function returns TRUE in case the password was changed successfully, otherwise it returns FALSE.

Example:

put rigAuthFetchConfigItem("identityColumn") into tIdentityCol
put rigSessUserdata(tIdentityCol) into tIdentity

put rigAuthChangePassword(tIdentity, rigVarPOST("oldPassword"), rigVarPOST("newPassword")) into tChange