path: root/modules/libglue/README

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