diff options
Diffstat (limited to 'libglue/README')
| -rw-r--r-- | libglue/README | 393 |
1 files changed, 393 insertions, 0 deletions
diff --git a/libglue/README b/libglue/README new file mode 100644 index 00000000..b847586b --- /dev/null +++ b/libglue/README @@ -0,0 +1,393 @@ +libglue - 8/17/03 + +libglue provides a set of libraries for use with applications +developed here at Oregon State University. + +This set of libraries includes: +- mysql session handling, +- MySQL/LDAP/'shared' authentication methods +- a database handler + +Contents: +1 Authentication Methods + 1.1 LDAP Authentication + 1.2 MySQL Authentication + 1.3 Shared Authentication +2 Database schemas + 2.1 For Session management + 2.2 For LDAP Authentication + 2.3 For MySQL Authentication + 2.4 For Shared Authentication +3 The Config file + 3.1 Formatting + 3.2 Subsections + 3.3 Arrays + 3.3 Retrieving options +4 Session management +5 Libglue in action + +6 Help, FAQs + + +1 Authentication Methods +-------------------------------------------------------------------------------- + Libglue currently supports 3 authentication methods: LDAP, MySQL, and + 'Shared.' It can support any combination of these concurrently, by falling + through in the order you specify (see Section 3.3). + + 1.1 LDAP Authentication + ------------------------------------------------------------------------------ + To use LDAP authentication, you must have LDAP support for PHP. + See http://php.net/manual/en/ref.ldap.php for how to configure php with LDAP. + + You must provide credentials for your LDAP server in the config file. + Anonymous LDAP authentication is possible, but not with libglue today. + + libglue has two functions for ldap authentication, both in 'LIBGLUE/auth.php': + + mixed get_ldap_user($username [,$fields]) + + object auth_ldap($username,$password) + + 'auth_ldap' is intended for internal use, while 'get_ldap_user' is a utility + for app developers to use. Both have similar layouts: + + - connect to ldap service + - bind to ldap with credential from config file + - search for '$username' in the space specified in the config file + - attempt to bind with supplied user credentials (auth_ldap only) + + 'get_ldap_user' returns an array of fields on success (if '$fields' is + not specified, it will return all the information for the specified user), + and an error string on failure. + + 'auth_ldap' returns an 'auth_response' object, with success indicated by + the value of auth_response->success. (This class is defined in 'auth.php'). + + 'auth_ldap' is typically only going to be called from a login script. + 'get_ldap_user' could be used when granting access to a new user. + + Config Options: + ldap_host + ldap_auth_dn + ldap_user_dn + ldap_filter + ldap_pass + ldap_fields + ldap_version + + + 1.2 MySQL Authentication + ------------------------------------------------------------------------------ + MySQL Authentication (like all of libglue) requires MySQL support in PHP. + It defaults to using the MySQL PASSWORD() function to check passwords, but + can also use PHP crypt() for compatability with other applications + (pam_mysql for example). + + MySQL Authentication assumes the local database specified in the config file + is being used. It is possible to support a different database, but that + begins to duplicate functionality from Share Authentication (Section 1.3). + + Config Options: + mysql_host + mysql_db + mysql_username + mysql_passwd + mysql_table + mysql_usercol + mysql_passcol + mysql_other + mysql_fields + + 'mysql_other' is an optional clause appended to the query. + Ex: mysql_other = "access = 'admin'" + + 'mysql_fields' is a comma separated list of the fields to return from + 'mysql_table' + Ex: mysql_fields = 'id,username,email,homedir' + + 1.3 Shared Authentication + ------------------------------------------------------------------------------ + Because libglue uses a mysql database to store session info, it is possible + to share session information between applications, creating a "Single Sign + On" (SSO) framework for web applications. libglue supports this out of + the box, with the following assumptions: + 1) The initial authentication is being handled elsewhere + 2) "SSO" session data is stored in a mysql database. + 3) The SSO database uses the schema described in Section 2.3. + + libglue keeps track of the 'type' of authentication each session uses, so + can still use LDAP or MySQL authentication when also using SSO. + + Config options: + sso_host + sso_db + sso_username + sso_pass + sso_table + sso_sid + sso_usercol + sso_expirecol + sso_length + sso_dbh_name + + +2 Database schemas +-------------------------------------------------------------------------------- + + Below are sample schemas for use with libglue. Mandatory fields are + indicated with a '*'. Unless stated otherwise, field NAMES can be set in + the config file. + + 2.1 For Session Management + ------------------------------------------------------------------------------ + CREATE TABLE session_data ( + * id varchar(32) NOT NULL default '', + * username varchar(16) NOT NULL default '', + * expire int(10) unsigned NOT NULL default '0', + * type enum('sso','mysql','ldap') NOT NULL default 'sso', + * data text, + PRIMARY KEY (id)) + + This session table should work for any type of authentication you do. + 'id' is an md5sum by default (as generated by php) but you can make + something else up if you've got the spare entropy. 'Type' obviously + only applies if you're using more than 1 type of authentication, + but the code assumes that it's present. + + 'data' is the field where serialized php data (from $_SESSION) is stored. + If you overflow this field, weird things may happen. + + + 2.2 For LDAP Authentication + ------------------------------------------------------------------------------ + + Basic LDAP authentication with libglue doesn't require a mysql database, + only session management. However, you will most likely need to store + some user information locally, in which case the table definition in + Section 2.3 is a good starting point. + + 2.3 For MySQL Authentication + ------------------------------------------------------------------------------ + + CREATE TABLE user ( + * id int(11) NOT NULL default '0', + * username varchar(255) NOT NULL default '', + * password varchar(255) default NULL, + fullname varchar(255) NOT NULL default '', + email varchar(255) default NULL, + status enum('disabled','enabled','dev') NOT NULL default 'enabled', + expire date default NULL, + phone varchar(255) NOT NULL default '', + PRIMARY KEY (id), + UNIQUE KEY username (username), + UNIQUE KEY id (id) + } + + Feel free to add columns to this table and then specify them in + 'mysql_fields' to make them part of your session data. + + 2.3 For Shared Authentication + ------------------------------------------------------------------------------ + + If you need to store user data locally, see the definition in Section 2.3. + + +3 The Config file +-------------------------------------------------------------------------------- + + 3.1 Formatting + ------------------------------------------------------------------------------ + The libglue config file is a lot like the smb.cnf file if you've ever used + samba (it's really easy to parse). Options are specified like + + option = value + + 'option' is a letter followed by any number of letters or numbers. + The spaces between 'option' and 'value' are optional. + 'value' may be single quoted, double quoted, or not quoted at all. + semicolons at the end of the line are ignored. + '#' is the single-line comment character. + + 3.2 Subsections + ------------------------------------------------------------------------------ + The config file parser can generate subsections in the config: + + > [libglue] + > option1 = value; + > option2 = 'value'; + > option3 = "value" + > [conf] + > option1 = value; + > otheroption = othervalue; + > [other] + > foo = "bar"; + + The parser then returns: + array( + 'libglue' => ('option1' => 'value', + 'option2' => 'value', + 'option3' => 'value'), + 'conf' => ('option1' => 'value', + 'otheroption' => 'othervalue'), + 'other' => ('foo' => 'bar') + ); + + 3.3 Arrays + ------------------------------------------------------------------------------ + You can create arrays of values in the config file by declaring an option + multiple times: + + [libglue] + ldap_fields = 'cn' + ldap_fields = 'homedirectory' + ldap_fields = 'uidnumber' + ldap_fields = 'uid' + ldap_fields = 'osuuid' + + would return the following: + array( + 'libglue' => ('ldap_fields' => ( + 0 => 'cn', + 1 => 'homedirectory', + 2 => 'uidnumber', + 3 => 'uid', + 4 => 'osuuid') + ) + ) + + + 3.3 Retrieving options + ------------------------------------------------------------------------------ + LIBGLUE/config.php defines two functions, conf() and libglue_param() for + retrieving values from the config file. See "Libglue in action" below. + + +4 Session Data and Management +-------------------------------------------------------------------------------- + + Libglue should relieve some of the burden of session management from your app + once a user is authenticated. The config file has the following parameters, + + user_data_name - Name of the array to store authentication session data in. + Ex: + user_data_name = 'user' + + Libglue then puts all the account information it retrieves + into $_SESSION['user'] + + user_id - fieldname for userid, + stored in $_SESSION[user_data_name][user_id] + user_username - fieldname for username, + stored in $_SESSION[user_data_name][user_username] + + Then for each of your authentication methods: + + ldap_uidfield = 'uidnumber' + ldap_usernamefield = 'uid' + mysql_uidfield = 'id' + mysql_usernamefield = 'username' + + Note that in this case, 'sso' isn't really an authentication method + (the info has to be looked up either in ldap or mysql). + + What this lets you do is ignore account type in your application, since + every session will have the same field names. + + +5 Libglue in action +-------------------------------------------------------------------------------- + + Libglue assumes there are three basic types of files in your application: + 1) Login/Authentication page + 2) Restricted pages + 3) Logout/Cleanup page + + Example login and logout pages are in the LIBGLUE/examples directory. + + For (2), you'll be calling the same code over and over. It is a good idea + to create an init file to take care of these common tasks in your application. + In each file, you'll do a + + > $restricted = 1; + > require_once('/path/to/init.php'); + + right off the bat; libglue needs to run before anything else so it can send + HTTP headers for cookies and redirection if necessary. + + Here is a sample init.php: + + + <?php + //config defines readconfig(), libglue_param(), and conf() + require_once("/data/libglue/config.php"); + // 1st parameter is the path to the config file + // 2nd parameter is DEBUG (1 or 0) + // '$config' will hold the parsed config data + $config = read_config("/data/app/conf/config.conf",0); + + // Register subsection 'libglue' in libglue_param() + libglue_param($config['libglue']); + + //Register subsection 'app' in conf() + conf($config['app']); + //Require the rest of the libglue code: + // Authentication methods: + require_once('/data/libglue/auth.php'); + // Session handling code: + require_once('/data/libglue/session.php'); + // Common database handle: + require_once('/data/libglue/dbh.php'); + + // This is optional, if you have some pages where session data and + // authentication aren't relevant. Otherwise just do check_session(). + if($restricted === 1) check_session(); + ?> + + libglue_param() and conf() make use of static member variables and + tests on paramter types to register/retrieve config data. When passed an + array, these functions assume you're registering config options. If given + a string, as in: + + $database_name = libglue_param('local_db'); + + the function will look for the key 'local_db' in the values that have been + previously registered with it. This is a little bit hokey, but objects + don't yet support static members in php so it's about the best we can do. + + + Session management is just taken care of; anything you put in $_SESSION in + your app is serialized, stored in the db when the page is done redering, + and retrieved on page load. + + + Database handle management is nice with libglue; if you've defined + 'dbh' in the config file, you can call dbh() to use that database handle again: + + $dbh = dbh(); + mysql_query($sql, $dbh); + + or + + mysql_query($sql, dbh()); + + +6 Help, FAQs +-------------------------------------------------------------------------------- + + Libglue is distributed at: + + http://oss.oregonstate.edu/libglue/ + + as it becomes more mature and widely used, this page may include more help + documentation. + + For now, feel free to email + + cws-prog@lists.orst.edu + + with any questions or bug reports. + +-- Central Web Services, + Oregon State University + |