====== Introduction ======
This will explain how I configured Dokuwiki (2009-02-14) to authenticate against a CAS server while still using internal configuration for Groups.  This solution also requires a few edits to the core files, which is not ideal, but necessary for now.

This requires [[http://www.dokuwiki.org|Dokuwiki]]((duh)), a CAS server, [[http://www.ja-sig.org/wiki/display/CASC/phpCAS|phpCAS 0.6.0-1]]((plus the dependencies for phpCAS. 1.0.1 might also work, but I already had 0.6.0-1 installed for another CAS syncing project.)) and the [[http://www.dokuwiki.org/auth:ggauth|ggauth Dokuwiki Pluggin]].

I've built my solution based on two other solutions that did not completely work for me:
  * [[http://www.esup-portail.org/display/PROJDOCUWIKICAS/CASification+de+Docuwiki]]
  * [[http://www.middleware.vt.edu/doku.php?id=middleware:dokuwiki#cas_support]]

<note>Both of these seem to use LDAP as their primary method, or LDAP for groups, but that would not work in my case.</note>

====== Step 0: Install Dependencies ======
First, you need to install Dokuwiki and phpCAS.  Both sites have instructions on how to do this.

====== Step 1: Install ggauth ======
If you just want people to log into your wiki, and everyone have full access to everything, then you may not need to configure this.  But if you need to have ANY user permissions at all (like administration) then I had to use ggauth to make this work.

Download the files to your server, and then unzip them to the top level of your dokuwiki installation.  It will populate the //inc/auth/ // directory for you.  So: 
<code console>
thomas@thomas-desktop:~/web/wiki3$ wget http://lastweekend.com.au/ggauth.zip
--2009-05-20 16:56:11--  http://lastweekend.com.au/ggauth.zip
Resolving lastweekend.com.au... 203.26.41.131
Connecting to lastweekend.com.au|203.26.41.131|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 19781 (19K) [application/zip]
Saving to: `ggauth.zip'

100%[=======================================================================================>] 19,781      22.4K/s   in 0.9s    

2009-05-20 16:56:13 (22.4 KB/s) - `ggauth.zip' saved [19781/19781]

thomas@thomas-desktop:~/web/wiki3$ unzip ggauth.zip
Archive:  ggauth.zip
  inflating: inc/auth/chained.class.php  
  inflating: inc/auth/htaccess.class.php  
  inflating: inc/auth/httpbasic.class.php  
  inflating: inc/auth/http.class.php  
  inflating: inc/auth/pam.class.php  
  inflating: inc/auth/simple.class.php  
  inflating: inc/auth/split.class.php  
  inflating: inc/auth/split.class.php~ 
</code>

Once this is done, ggauth is installed but not configured.  I'll leave the configuration until later.

====== Step 2: Install CAS Authentication ======
There is no pretty package for the cas authentication.  Basically, you need to go to the DOKUWIKI/inc/auth folder and create a file called __//cas.class.php//__ and paste the following code in there:
<code php 1 |h cas.class.php >
<?php
require_once(DOKU_INC.'inc/auth/plain.class.php');
include_once('cas/source/CAS.php'); //This is the path to your phpCAS library.  In my test it is installed in the auth folder, but this could also be a reference to an absolute path on the server, or it could be in the php include path.

phpCAS::client(CAS_VERSION_2_0, '{YOUR CAS SERVER}', 443, '{YOUR CAS DIRECTORY}');

class auth_cas extends auth_plain {
    function auth_cas() {
        global $conf;
        $this->cando['external'] = true;
        $this->auth_plain();
    }

    function trustExternal($user,$pass,$sticky=false){
        global $USERINFO;
        global $conf;
        $sticky ? $sticky = true : $sticky = false; //sanity check

        $session = $_SESSION[$conf['title']]['auth'];

        phpCAS::setNoCasServerValidation(); //I had to set this to avoid an error an authentication.

        if(phpCAS::isAuthenticated()) {
            $user = phpCAS::getUser();

            if(isset($session)) {
                $_SERVER['REMOTE_USER'] = $user;
                $USERINFO = $session['info'];
                $_SESSION[$conf['title']]['auth']['user'] = $user;
                $_SESSION[$conf['title']]['auth']['pass'] = $session['pass'];
                $_SESSION[$conf['title']]['auth']['info'] = $USERINFO;
                $_SESSION[$conf['title']]['auth']['buid'] = $session['buid'];
            }
            else {
                $USERINFO = $this->getUserData($user);
                $_SERVER['REMOTE_USER'] = $user;
                $_SESSION[$conf['title']]['auth']['user'] = $user;
                $_SESSION[$conf['title']]['auth']['pass'] = $pass;
                $_SESSION[$conf['title']]['auth']['info'] = $USERINFO;
                $_SESSION[$conf['title']]['auth']['buid'] = auth_browseruid();
            }

            return true;
        }

        return false;
    }
}
?>
</code>

To figure out what {YOUR CAS SERVER} and {YOUR CAS DIRECTORY} are, you should contact your CAS admin.  Usually they are part of the url that you normally hit for CAS.  So if you go to: http://login.company.com/cas/login to login, your URL is //login.company.com// and your directory is //cas//

====== Step 3: Change Core Files ======
Here are the changes to the core files that you will need to make for CAS to work.  While you are making these changes, no one will be able to use the wiki.

//**doku.php**//
This change is required to intercept the login/logout actions of dokuwiki to forward them to our CAS server.  

After Line 63:
<code php |h doku.php>
if ($ACT == 'login') {
    phpCAS::setFixedServiceURL(
      'http://{YOUR CAS LOGIN SERVICE}?service={YOUR WIKI URL}/doku.php?' . $_SERVER["QUERY_STRING"]);
    phpCAS::forceAuthentication();
}

if($ACT == 'logout') {
    phpCAS::logout();
}
</code>

The (partially) complete code should look like this:
<code php |h doku.php>
.......
  //send 404 for missing pages if configured or ID has special meaning to bots
  if(!$INFO['exists'] &&
     ($conf['send404'] || preg_match('/^(robots\.txt|sitemap\.xml(\.gz)?|favicon\.ico|crossdomain\.xml)$/',$ID)) &&
     ($ACT == 'show' || substr($ACT,0,7) == 'export_') ){
    header('HTTP/1.0 404 Not Found');
  }

if ($ACT == 'login') {
    phpCAS::setFixedServiceURL(
      'http://{YOUR CAS LOGIN SERVICE}?service={YOUR WIKI URL}/doku.php?' . $_SERVER["QUERY_STRING"]);
    phpCAS::forceAuthentication();
  }

  if($ACT == 'logout') {
    phpCAS::logout();
  }


  //prepare breadcrumbs (initialize a static var)
  breadcrumbs();

  // check upstream
  checkUpdateMessages();
......
</code>

Your CAS URL might look something like: http://login.company.com/cas/login?service=http://awesomewiki.company.com/doku.php

====== Step 4: Configuring Dokuwiki for CAS ======
In this final step, we configure the config files with the correct authentication settings to use CAS.  I'll jump back and cover all of the configuration changes in all files for completeness.

===== inc/auth/cas.class.php Config =====
In cas.class.php we need to configure a few lines.

  - Line 2 should point to your //plain.class.php//.  This should be fine if you copied from above.
  - Line 3 needs to point to your phpCAS library.  If it is in your PHP include path, just pointing to //CAS.php// should be fine.  In the example above, I installed phpCAS below the auth directory, so that's why the path flows down from there.  On my production server, this will point to ///usr/local/phpincludes/CAS.php//.

===== dokuwiki.php Config =====
For //$ACT == 'login'// we need to specify the URL for our CAS server:
<code php |h dokuwiki.php>
if ($ACT == 'login') {
    phpCAS::setFixedServiceURL(
      'http://{YOUR CAS LOGIN SERVICE}?service={YOUR WIKI URL}/doku.php?' . $_SERVER["QUERY_STRING"]);
</code>

Your CAS URL might look something like: http://login.company.com/cas/login?service=http://awesomewiki.company.com/doku.php

The first part being where you go to log into CAS normally, and the service= tells the CAS server where to redirect the user back to.

===== conf/local.php or conf/local.protected.php =====
You can make these changes in either of these files (although local.protected.php is probably a better idea).

You need to configure your authentication to use split, and then cas for authentication and plain for groups.

<code php 1|h conf/local.php or conf/local.protected.php>
<?php
/**
 * Dokuwiki's Main Configuration File - Local Settings
 * Auto-generated by install script
 * Date: Wed, 20 May 2009 15:12:42 -0230
 */
$conf['title'] = 'CAS Test Wiki';
$conf['lang'] = 'en';
$conf['useacl'] = 1;
$conf['superuser'] = '@admin';


$conf['authtype']    = 'split';
$conf['auth']['split']['login_auth'] = 'cas';    # the auth backend for authentication
$conf['auth']['split']['groups_auth'] = 'plain';  # the auth backend that supplies groups
$conf['auth']['split']['merge_groups'] = false;   # should groups from login auth also be included
$conf['auth']['split']['use_login_auth_for_users'] = false; # Should login auth be used for supplying the list of users for usermanager
$conf['auth']['split']['use_login_auth_for_name'] = false; # Should login auth supply user name, or only used if groups auth provides an empty name
$conf['auth']['split']['use_login_auth_for_mail'] = false; # Should login auth supply email address, or only used if groups auth provides empty email.
$conf['profileconfirm'] = false;
</code>

Once you save this file, you should be good to go.  When you log into your wiki, you should automatically bounce to CAS, and then bounce back to the wiki.