Auth Module API Documentation

Requirements

1. users - contains basic information about users. Columns as follows:
   • name [varchar 50, primary key] - the user's name
   • password [varchar 50] - the password, stored crypt-ed
   • salt [varchar 10] - a timestamp used as a salt value for crypt-ing the password
   • uid [varchar 4] - a numeric user id, randomly generated and non-sequential
   • session_id [varchar 50] - a random key generated when a user logs in and stored in a cookie on the client side
   • real_name [varchar 75] - the user's real name
2. userPrivs - a list of permissions for users. Each record essentiallys says user X may do Y. The subclass start and end allow finer tuned control; i.e., user X may do Y provided Z falls within the acceptable range. Thus anything can be used for these values so long as it is comparable on the SQL server being used. The keyword 'all' is reserved for indicating that there is no subclass.
   • uid [varchar 4] - identifies the user
   • auth_class [varchar 50] - names the allowed task
   • sub_start [varchar 50] - defines the beginning of a subclass
   • sub_end [varchar 50] - defines the end of a subclass
3. userGroups - defines groups of users. Each record indicates one member of one group.
   • gid [int 4] - a group id number. Sequential.
   • name [varchar 50] - the name of the group
   • username [varchar 50] - the name of the user
4. userGroupPrivs - similar to userPrivs, but for groups. See that table for details.
   • gid [int 4]
   • auth [varchar 50]
   • sub_start [varchar 50]
   • sub_end [varchar 50]

API

bool changePassword ( string username, string oldpassword, string newpassword )
Updates the users password. Returns true on success, false on failure.

mixed checkLogin ( )
Examines cookies to determine if any user is logged in. Returns the name of the logged in user if there is one, otherwise returns false.

bool createLogin ( string name, string password )
Enters a new username / password combination into the database. Returns true on success, false on failure. Requires 'admin' authorization.

bool deleteLogin ( string name )
Deletes the given user. Returns true on success, false on failure. Requires 'admin' authorization.

bool login ( string name, string password )
Checks the username and password, then logs in the user if credentials are correct. Returns true on success, false on failure. Note this function sets a cookie, so no output can be sent to the browser prior to calling it.

bool logout ( )
Logs out the currently logged in user and returns true. Note this function sets a cookie, so no output can be sent to the browser prior to calling it.

void showUsers ( )
Prints out a table of information about current users. Requires 'admin' authorization.

mixed validateUser ( string authorization [, string subclass ] )
Determines who, if anyone, is logged in, and checks to see whether that user has the given authorization. Returns the logged in user's name on success, or prints error messages AND returns false on failure.

mixed validateUserQuiet ( string authorization [, string subclass ] )
Identical to above except no error messages are printed.

bool addAuth ( string username, string authorization [, string subclass_start, string subclass_end ] )
Adds the given authorization for the given user. Returns true on success, false on failure. Requires 'admin' authorization.

bool checkAuth ( string username, string authorization [, string subclass ] )
Checks if the given user has the specified authorization. Returns true or false accordingly.

bool deleteAuth ( string username, string authorization )
Deletes ALL matching authorizations for the user. There is currently no way to delete just a single subclass span within an authorization. Returns true on success, false on failure. Requires 'admin' authorization.

bool showAuths ( string username )
Prints a table of authorization information for the given user. Returns true on success, false on failure. Requires 'admin' authorization.

bool addAuthToGroup ( string groupname, string authorization [, string subclass_start, string subclass_end ] )
Adds the authorization to the given group. Returns true on success, false on failure.

bool addGroup ( string groupname, string username )
Creates a group AND adds the user to it. Because of the database structure, a group without users isn't feasible, but such a group isn't particularly useful. Returns true on success, false on failure.

bool addUserToGroup ( string groupname, string username )
Adds the given user to the given group. Returns true on success false on failure.

bool checkGroupAuth ( string groupname, string authrization [, string subclass ] )
Checks if the group has the given authorization and returns true or false accordingly.

bool deleteAuthFromGroup ( string groupname, string authorization )
Deletes ALL instances of the given authorization from the given group. Returns true on success, false on failure.

bool deleteGroup ( string groupname )
Deletes the given group. Returns true on success, false on failure.

bool deleteUserFromGroup ( string groupname, string username )
Deletes the given user from the given group. Returns true on success, false on failure.

void detailGroup ( string groupname )
Prints tabled information about the given group including users and authorizations.

bool showGroups ( )
Prints a table of group information. Returns true.

resource dbconnect ( )
Connects to the database and returns a MS SQL link identifier. Doesn't do any error checking. This is really only useful for moving the database, since the location and database are specified in the one spot. Actual code doesn't abstract other calls, so the mssql_* functions would have to all be replaced to switch DB providers.

mixed getGID ( string groupname )
Returns the group id number of the given group if it exists, otherwise returns false.

mixed getUID ( string username )
Returns the user id number of the given user if it exists, otherwise returns false.

bool isAlphanumeric ( string input )
Verifies that the string doesn't contain anything other than letters, numbers, and underscores. All user input should really be checked with this before being sent to the database to prevent SQL injection. Returns true or false accordingly.

auth/ui/loginform.php - the big kahuna for the GUI. This logs in users, but does a couple other tricks via GET. Giving a get parameter of logout=yes will logout the user. A get parameter of redirect=[url] will automatically send the user to the specified url after a successful login. Note the redirect url itself can only contain one get parameter because the ampersand would end 'redirect'; this is a known limitation.

auth/ui/index.php - auto-redirects users to either the login page or the menu based on whether or not they're logged in. Handy in that just 'auth/ui' can be given to users as a single, all purpose bookmark.

Usage