Author: Mark D. Anderson (mda@discerning.com)
Date: 2006-11-15
License: MIT

This directory contains changes necessary for two independent
Flyspray and a Dokuwiki instances on the same domain to have
single sign on, using the Flyspray database.

IMPORTANT NOTES and LIMITATIONS:

  This is only known to work with Flyspray 0.9.9-devel and Dokuwiki snapshot 2006-11-06.
  It will certainly not work with Flyspray 0.9.8, and probably not with Flyspray 1.0.

  This has nothing to do with the use of Dokuwiki as a wiki system for
  editing Flyspray task descriptions. The Flyspray install may or may not
  have a Dokuwiki plugin for editing of task descriptions, but that is unrelated.

  This does not provide any patches for "interwiki" links between tasks and 
  wiki pages.

  It provides no integration between task projects and wiki namespaces.

  This only provides a solution for Flyspray using mysql. A postgres version
  would be very similar, but is not provided.

DOKUWIKI CHANGES:

DW has pluggable authentication while FS does not (currently), 
so we are changing DW to rely on FS for authentication.
The first step is just a a common authentication database.
This does *not* achieve SSO (single sign-on); it just means that the
same users can login separately in the two apps.

To achieve that much, copy the file flyspray_mysql.conf.php from
this directory into dokuwiki/conf/ and edit dokuwiki/conf/local.php to have:

  $conf['passcrypt'] = same as 'passwdcrypt' in flyspray.conf.php ('md5' or 'crypt')
  $conf['authtype'] = 'mysql';
  $conf['auth']['mysql']['server']   = FS database conf 'dbhost'
  $conf['auth']['mysql']['user']     = FS database conf 'dbuser'
  $conf['auth']['mysql']['password'] = FS database conf 'dbpass'
  $conf['auth']['mysql']['database'] = FS database conf 'dbname'

You also need to add this at the end of your local.php (or in local.protected.php
if you are using the Configuration Manager plugin):

  require_once(DOKU_CONF.'flyspray_mysql.conf.php');

At this point, if things are working, your DW will be using the FS database for login.

To also get SSO, copy the file flyspray_mysql.class.php from
this directory into dokuwiki/inc/auth/ and then edit dokuwiki/conf/local.php
to instead have:

  $conf['authtype'] = 'flyspray_mysql';

(Note that with SSO, the $conf['passcrypt'] value in DW is now irrelevant.
You can also remove the $conf['auth'] stuff from local.php because flyspray_mysql.conf.php
does it automatically.)
This step will cause DW to use the flyspray_mysql.class.php which is a subclass
of the provided mysql.class.php.
You may need to edit the value of FS_ROOT in flyspray_mysql.class.php 
to match your install.

FLYSPRAY CHANGES:

First of all, it is necessary to have the flyspray-auth-patch.txt file applied
to your 0.9.9-devel (unless you are using a version where it is already
applied). This patch accomplishes:

  allow DW to load necessary FS files without hitting conflicts from any DW plugin
  make it so FS won't always set error_reporting(E_ALL) (which DW doesn't like)
  fix a bug in Flyspray::setcookie (passing 0 instead of NULL to mean browser lifetime)
  add support for $conf['general']['cookiepath'] so FS cookies are visible in whole path

In addition to that patch you need to edit flyspray/flyspray.conf.php to have:

     [general]
     cookiepath = "/"

GROUPS and ACLS:

DW and FS have complete different sets of permission names. Also, DW organizes its
ACLs by a hierarchy of namespaces, while FS has a two-level hierarchy of
individual project, and global.

However, this integration can arrange for them to use the same sets of
group names. The management of what permissions are given to each of those
groups will still have to be managed in each admin app, but at least group/user
membership will be shared.

To accomplish this, in dokuwiki/conf/local.php:

  $conf['useacl'] = 1;
  $conf['defaultgroup'] = a FS group name for new users, such as 'Developers'
  $conf['superuser'] = either: a FS user with all rights, or '@' + the FS admin group name (e.g. '@Admin')

The DW Access Control List Management plugin (unlike the User Manager plugin) does
not use the pluggable authentication system; you have to manually enter explicit
group names. You can do that with the ACL plugin page, or by editing
dokuwiki/conf/acl.auth.php directly. Don't touch "ALL" as that is special.

BACKGROUND NOTES:

see:
  http://wiki.mantisbugtracker.com/doku.php/mantisbt:issue:7075:integration_with_dokuwiki
  http://wiki.splitbrain.org/wiki:discussion:bugtracking [incorrect information]
  http://wiki.splitbrain.org/wiki:auth:mysql_flyspray

flyspray:
  maintains cookies: 
    flyspray_userid flyspray_passhash flyspray_project
  authentication:
    scripts/authenticate.php sets cookies upon success.
  verification on each request: 
    index.php verifies using $user->check_account_ok() in includes/class.user.php 
  logout:
    $user->logout() clears cookies
  groups:
    when $user is created it fetches groups and permissions from those groups
    has permissions at project and/or global level

dokuwiki:
  maintains cookies:
    DOKU_COOKIE, which is defined to be 'DW'.md5(DOKU_URL) in inc/init.php
  authentication:
    inc/auth.php loads plugin such as inc/auth/mysql.class.php  
    mantis suggests writing a whole separate inc/auth/mantis.class.php with trustExternal.
    but still need to integrate management of groups and users...
  verification on each request:
    in inc/auth.php, if $auth->trustExternal, then that does everything.
    otherwise auth_login() does a login if param 'u' is set, otherwise verifies cookie
      if login is successful, it sets cookie and session variables.
  logout:
    auth_logoff
  groups:
    acls are a bit mask of AUTH_READ=1,AUTH_EDIT=2, etc.
    has permissions at the page, namespace, or global level
    has a special group '@ALL'
    has a superuser group