Information Technology

Programming API

In addition to the basic new account, login and password changing scripts that we've already seen, aLogin2 supports additional methods and properties designed to be invoked by the web application’s JavaScript.  The collection of API’s is fairly limited at this point, but additional calls will be added as needed and as time and interest allows. Most of the functions require the name of a callback function to invoke when complete. The application code will continue immediately after making the call rather than waiting for the called function to be complete, but the results of the call will not be known or available until the callback function is run. For illustration purposes, we're assuming that the aLoginAppObject was created with the variable name of logApp.

logApp.scriptLogin(user,pass)

scriptLogin allows a script to change the current logged in user.  The routine takes the username and password given, runs the authentication checks, and calls the routine passed to it as callback.  It works exactly like the standard login function except that it omits the user interface. This can be useful if a completely different interface is desired or if the application wishes to force the use of a particular user account.  The application programmer will have to write a callback routine and include in in the configuration object for the aLogin object.   The callback function will be called when the login is complete and return it an array with the following values,

['status'] - True if user/password found.  False if missing or incorrect password.  All other array values will be missing or meaningless.

['user'] - Same as username passed to routine.

['password'] - Same as password passed to routine.

['authority_level'] - Authority level for the user.

See the page on adding aLogin2 to an application for more information on what's required on the callback function (right below the table).

logApp.logout()

This function returns the system to the condition it was in before anybody logged in.  This means that if there was an initial username and password in the configuration object, they will be return as the active values.  If changing passwords is allowed, this will remove this option until someone logs in.

logApp.resetLanguage(language)

resetLanguage resets the display language to be used for the interface.  Language is a text string.  It causes the setLanguage function in the appropriate language file to run.  If the language isn't know to aLogin, the current language will remain in effect.

loginApp.languages

The languages property of that aLoginAppObject is an array of possible languages.  This is automatically generated based on the languages in the ./languages folder. It can be used to create an interface allowing a user to switch languages.  A language selection interface needs to be added to the API but isn’t ready yet.

logApp.checkAuthority(username,password)

This function checks aLogin for the authority level associated with the username/password.  It returns the authority level as a single value to the provided callback function.  If the username/password aren't found in the system, it returns -1.

logApp.serverLoginCheck(username,password)

This function checks the username and password against the aLogin database and returns the information about the user in a single array.  The array contains up to four values,

['status'] - True if user/password found.  False if missing or incorrect password.  All other array values will be missing or meaningless.

['user'] - Same as username passed to routine.

['password'] - Same as password passed to routine.

['authority_level'] - Authority level for the user.

logApp.addUser(user,pass,email,authorityLevel,defaultLevel,managerEmail,reason)

This function adds a new user to the aLogin system database using the values provided.  If the authorityLevel requested is higher that the defaultLevel, then the default level is assigned and a message is sent to the manager's email.

A defaultLevel of 80 or above is not allowed.  The only way to create an administrator account is through the administrative functions.

This function returns a single value.  If the new account can not be created that value is 0.  Otherwise the value has no meaning to the callback function except for the fact that it will be unique for every user.

This function was originally designed to allow for a web application to create accounts with a meaningless password in situations were the aLogin system is being used in conjunction with another authentication system and the only information we need from aLogin is the authority level.

logApp.updateAccount(user,oldPassword,newPassword,email)

logApp.updatePassword(user,oldPassword,newPassword)

This function changes a user's password.  It assumes that the calling application has already verified that the user is authorized to do this.  The updatePassword form is for compatibility with old code and should be avoided.  If either the newPassword or email fields are missing or blank, then those values will not be changed.

The function returns a single value  to the callback function.  The value has the following possible values,

  • 1    password updated.
  • 0   user and oldpassword don't agree in aLogin database, password not changed.
  • -1  attempt to update password failed.  Email update worked.
  • -2  attempt to update email failed. Password update worked.
  • -3  attempts to update email and password both failed.
  • -4  no new values were provided.  Nothing done.
  • -5  current user not authorized to update passwords.

logApp.changePassword()

This function changes a user's password.  Unlike updatePassword, this function uses a form to collect the new and old password and updates the database.

   It is the first of the three basic API calls.

logApp.login()

This function brings up the login interface.  When done it calls the callback function with an array. The array contains up to four values,  When completely the callback routine defined in the aLogin configuration file will be called and passed an array as a parameter.  The array will contain four values as defined below,

['status'] - True if user/password found.  False if missing or incorrect password.  All other array values will be missing or meaningless.

['user'] - Same as username passed to routine.

['password'] - Same as password passed to routine.

['authority_level'] - Authority level for the user.

This is the second of the three basic API calls.

logApp.newAccount()

This function brings up the new account interface.  It doesn't return anything.  It is the third of the three basic API calls.