Authentication Handler Reference
Please find OTP specific handlers in chapter One-Time Password Authentication.
rigAuthLogin( pIdentity, pPassword, pRemember )
Logs the user in.
Parameters
- pIdentity: is a string to identify the user. Usually this is an email address or a username
- pPassword: is a password string
- pRemember: (optional) is a boolean which determines if the user wants to be remembered
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
- pUsername: is a username
- pPassword: is the user's password
- pEmail: is the user's email address
- pExtraData: (optional) is an array containing additional data like first name, last name etc
- pGroupname: (optional) is a numbered array used to define which groups the user belongs to
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
- pID: is the user's ID
- pData: is an array containing the update data
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
- pID: is the user's ID
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
- pIdentity: is a string which represents the user's identity as defined in the authentication.lc config file
- pExtraData: (optional) is an array containing additional data. Currently the function processes solely one parameter array key which is called "passwordResetLink". This is the URI included with the forgotten password email used to reset a password
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
- pID: (optional) is the user's ID. If a user id is not passed the id of the currently logged in user will be used
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
- pGroup: is an integer (the group ID) or a string (the group name) or an array of strings and integers
- pID: (optional) is the user's ID. If a user id is not passed the id of the currently logged in user will be used
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
- pUsername: is the user's username
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
- pEmail: is the user's email address
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
- pIdentity: is a string which represents the user's identity as defined in the authentication.lc config file
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
- pIdentity: is a string which represents the user's identity as defined in the authentication.lc config file
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
- pIdentity: is a string which represents the user's identity as defined in the authentication.lc config file
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
- pIdentity: is a string which represents the user's identity as defined in the authentication.lc config file
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
- pIdentity: is a string which represents the user's identity as defined in the authentication.lc config file
- pExpirePeriod: (optional) is the number of seconds after which all the entries of login attempts should be cleared. If set to empty, a value of 86400 ( 1 day) is used
rigAuthUser( pID )
Get a particular user.
Parameters
- pID: (optional) is the user's id (integer). If a user id is not passed the id of the currently logged in user will be used
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
- pGroupIDs: (optional) is an array of group IDs or a single ID
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
- pID: is a group id
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
- pID: (optional) is a user's id
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
- pGroupID: is an integer, the ID of the group a user should be added to
- pUserID: is the user's ID
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
- pGroupIDs: is an array of group IDs or a single group ID
- pUserID: is the user's id
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
- pPrefix: (optional) is a starting delimiter for authentication related messages. If none is specified the delimiter as defined in application/config/authentication.lc is used
- pSuffix: (optional) is an ending delimiter for authentication related messages. If none is specified the delimiter as defined in application/config/authentication.lc is used
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
- pStartDelimiter: is the starting delimiter
- pEndDelimiter: is the ending delimiter
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
- pPrefix: (optional) is the starting delimiter. If none is specified the delimiter as defined in application/config/authentication.lc is used
- pSuffix: (optional) is the ending delimiter. If none is specified the delimiter as defined in application/config/authentication.lc is used
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
- pStartDelimiter: is the starting delimiter
- pEndDelimiter: is the ending delimiter
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
- pItem: is the array key
- pIndex: (optional) is the second array key
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
- pID: is the user's id
- pCode: (optional) is the activation code
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
- pID: is the user's id
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
- pCode: is the "forgotten password" code
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
- pCode: is the code used to reset a password
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
- pIdentity: is the user's email address or whatever is used to identify a user
- pNewPassword: is the new password
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
- pIdentity: is the user's email address or whatever is used to identify a user
- pOldPassword: is the old password
- pNewPassword: is the new password
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