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: 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