fannie/auth/doc/index.html
<html>
<head><title>Auth Module API Documentation</title></head>
<body>
<!-- 20Oct12 EL Added h2 -->
<h2>Auth Module API Documentation</h2>
This document is to detail the API and functionality of the Auth module.
The requirements and workings will be explained, followed by function documentation.
<p />
<h3>Requirements</h3>
<li>PHP and a webserver</li>
<li>A SQL database (currently uses Sybase; code would need tweaking to use something else)</li>
<br />
<b>Database Layout</b>
There are 4 database tables used by Auth. There is no install script, so these would need to be
created manually.
<ol>
<li><i>users</i> - contains basic information about users. Columns as follows:
<ul>
<li><i>name</i> [varchar 50, primary key] - the user's name</li>
<li><i>password</i> [varchar 50] - the password, stored crypt-ed</li>
<li><i>salt</i> [varchar 10] - a timestamp used as a salt value for crypt-ing the password</li>
<li><i>uid</i> [varchar 4] - a numeric user id, randomly generated and non-sequential</li>
<li><i>session_id</i> [varchar 50] - a random key generated when a user logs in and stored in a cookie on the client side</li>
<li><i>real_name</i> [varchar 75] - the user's real name</li>
</ul>
</li>
<li><i>userPrivs</i> - 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.
<ul>
<li><i>uid</i> [varchar 4] - identifies the user</li>
<li><i>auth_class</i> [varchar 50] - names the allowed task</li>
<li><i>sub_start</i> [varchar 50] - defines the beginning of a subclass</li>
<li><i>sub_end</i> [varchar 50] - defines the end of a subclass</li>
</ul>
</li>
<li><i>userGroups</i> - defines groups of users. Each record indicates one member of one group.
<ul>
<li><i>gid</i> [int 4] - a group id number. Sequential.</li>
<li><i>name</i> [varchar 50] - the name of the group</li>
<li><i>username</i> [varchar 50] - the name of the user</li>
</ul>
</li>
<li><i>userGroupPrivs</i> - similar to <i>userPrivs</i>, but for groups. See that table for details.
<ul>
<li><i>gid</i> [int 4]</li>
<li><i>auth</i> [varchar 50]</li>
<li><i>sub_start</i> [varchar 50]</li>
<li><i>sub_end</i> [varchar 50]</li>
</ul>
</li>
</ol>
<h3>API</h3>
<b>auth/login.php</b> - this is the main file. Include this to use the auth module.<p />
bool <b>changePassword</b> ( string username, string oldpassword, string newpassword )<br />
Updates the users password. Returns true on success, false on failure.
<p />
mixed <b>checkLogin</b> ( )<br />
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.
<p />
bool <b>createLogin</b> ( string name, string password )<br />
Enters a new username / password combination into the database. Returns true on success, false
on failure. Requires 'admin' authorization.
<p />
bool <b>deleteLogin</b> ( string name )<br />
Deletes the given user. Returns true on success, false on failure. Requires 'admin' authorization.
<p />
bool <b>login</b> ( string name, string password )<br />
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.
<p />
bool <b>logout</b> ( )<br />
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.
<p />
mixed <b>validateUser</b> ( string authorization [, string subclass ] )<br />
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 <i>prints error messages</i> AND
returns false on failure.
<p />
mixed <b>validateUserQuiet</b> ( string authorization [, string subclass ] )<br />
Identical to above except no error messages are printed.
<p />
<hr />
<b>auth/privileges.php</b>
<p />
bool <b>addAuth</b> ( string username, string authorization [, string subclass_start, string subclass_end ] )<br />
Adds the given authorization for the given user. Returns true on success, false on failure.
Requires 'admin' authorization.
<p />
bool <b>checkAuth</b> ( string username, string authorization [, string subclass ] )<br />
Checks if the given user has the specified authorization. Returns true or false accordingly.
<p />
bool <b>deleteAuth</b> ( string username, string authorization )<Br />
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.
<p />
bool <b>showAuths</b> ( string username )<br />
Prints a table of authorization information for the given user. Returns true on success, false on failure.
Requires 'admin' authorization.
<p />
<hr />
<b>auth/groups.php</b>
<p />
bool <b>addAuthToGroup</b> ( string groupname, string authorization [, string subclass_start, string subclass_end ] )<br />
Adds the authorization to the given group. Returns true on success, false on failure.
<p />
bool <b>addGroup</b> ( string groupname, string username )<Br />
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.
<p />
bool <b>addUserToGroup</b> ( string groupname, string username )<Br />
Adds the given user to the given group. Returns true on success false on failure.
<p />
bool <b>checkGroupAuth</b> ( string groupname, string authrization [, string subclass ] )<br />
Checks if the group has the given authorization and returns true or false accordingly.
<p />
bool <b>deleteAuthFromGroup</b> ( string groupname, string authorization )<br />
Deletes ALL instances of the given authorization from the given group. Returns true on success,
false on failure.
<p />
bool <b>deleteGroup</b> ( string groupname )<br />
Deletes the given group. Returns true on success, false on failure.
<p />
bool <b>deleteUserFromGroup</b> ( string groupname, string username )<br />
Deletes the given user from the given group. Returns true on success, false on failure.
<p />
void <b>detailGroup</b> ( string groupname )<br />
Prints tabled information about the given group including users and authorizations.
<hr />
<b>auth/utilities.php</b> - useful functions that don't belong anywhere else
<p />
resource <b>dbconnect</b> ( )<Br />
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.
<p />
mixed <b>getGID</b> ( string groupname )<br />
Returns the group id number of the given group if it exists, otherwise returns false.
<p />
mixed <b>getUID</b> ( string username )<br />
Returns the user id number of the given user if it exists, otherwise returns false.
<p />
bool <b>isAlphanumeric</b> ( string input )<br />
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.
<p />
<hr />
<b>auth/doc</b> This. You're reading it.
<p />
<hr />
<b>auth/ui</b> - A user interface for logging in and out and administering the system. Mostly straightforward.
Notably, the auth module is self enforcing. A user must have the authorization 'admin' to perform many of the
administrative tasks, enforced on the base level or the user interface level (or both). I <i>think</i> that adding
a user with an empty password field to the table <i>users</i> and giving that user an 'admin' 'all' 'all' authorization
in the table <i>userPrivs</i> would give you an intial admin to login with, but I haven't actually tried it. It depends
how crypt deals with an empty string.
<p />
<b>auth/ui/loginform.php</b> - 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.
<p />
<b>auth/ui/index.php</b> - 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.
<p />
<h3>Usage</h3>
Or, how do I plug this thing into my code? Well, just use <i>validateUser</i> or <i>validateUserQuiet</i> to
check your user's permissions. Use <b>auth/ui/loginform.php</b> with the 'redirect' get parameter to provide users
with a login link that will take them back to the current page - or where ever you want them to go. You could also
zap them there automagically with <?php header("Location: /path/to/auth/ui/loginform.php?redirect=...") ?>
And that's about that.
</body>
</html>