[[PageOutline]]

== Overview ==

The GuardPlugin is a CakePHP plugin to provide flexible authentication framework. With this plugin, developers are able to write their own authentication module easily and fast. The plugin also provides some build-in authentication module, such as Shibboleth and default (original). This plugin is build based on CakePHP 1.3 [http://api13.cakephp.org/class/auth-component AuthComponent] and it provides full back compatibly. If the application is developed on [http://api13.cakephp.org/class/auth-component AuthComponent], no change is required for the existing code. 

== Requirements ==
 * CakePHP 1.3+

== Download ==
{{{
svn co http://ipeerdev.olt.ubc.ca/svn/plugins/guard/trunk/ guard
}}}

== Install ==

The GuardPlugin should be install into app/plugins/guard

The tree structure should look like this:

{{{
app/plugins/guard
|-- config
|   `-- guard_default.php
|-- controllers
|   |-- components
|   |   |-- auth_module.php
|   |   |-- default_module.php
|   |   |-- guard.php
|   |   `-- shibboleth_module.php
|   `-- guard_controller.php
`-- views
    |-- elements
    |   |-- login_default.ctp
    |   `-- login_shibboleth.ctp
    `-- guard
        `-- login.ctp
}}}

After the installation of the files, the initial copy of the configuration file should be copy from app/plugins/guard/config/guard_default.php to app/config/guard.php.

{{{
cp app/plugins/guard/config/guard_default.php app/config/guard.php
}}}

The last step is to change the application to load Guard component instead of Auth component. It is usually in app/app_controller.php. Because Guard component is subclass of Auth component, all the parameters accepted by Auth are also accepted by Guard component. Guard component will also define Auth as the alisas of Guard component. So there is no need to change all the Auth reference in the application. 

{{{
class AppController extends Controller
{
  var $components = array('Guard.Guard', 'Other_Compoment');
...
}}}

== Configuration ==

The plugin configuration file is located in app/config/guard.php. It is a standard CakePHP configuration file reading by [http://book.cakephp.org/view/42/The-Configuration-Class#load-415 Configuration::load] method. All the configurations are defined in $config array.

To change which module to use for authentication:

{{{
$config['Guard.AuthModule.Name'] = "Default" //options are Default and Shibboleth
}}}

Some of the !AuthComponent properties can be override through the configuration file.

== Using Existing Modules ==
Currently, the authentication modules that come with the plugin are:

 * Default: CakePHP build-in authentication module ([http://api13.cakephp.org/class/auth-component AuthComponent])
 * Shibboleth: Shibboleth authentication module. It needs the HTTP server to be configured as service provider (SP)

=== Default Module ===
This module is using CakePHP build-in authentication component [http://api13.cakephp.org/class/auth-component AuthComponent] to verify the users. 

=== Shibboleth Module ===
This module supports [http://shibboleth.internet2.edu/ Shibboleth] as the external authentication method. It requires the HTTP server to be set up as the service provider (SP). The users will be redirected to an external (central) login page when they click on login button. Once they logged in successfully, they will be verified against the internal database to see if they have the valid account and permission to access the resources in the application. The user table and fields can be defined in the configuration file.

The configuration parameters for Shibboleth are:
{{{
#!php
$config['Guard.AuthModule.Shibboleth'] = array('sessionInitiatorURL' => 'https://%HOST%/Shibboleth.sso/Login',
                                               'logoutURL'           => 'https://%HOST%/Shibboleth.sso/Logout',
                                               'fieldMapping'        => array('eppn'        => 'username',
                                                                              'affiliation' => 'role',
                                                                             ),
                                               'mappingRules'        => array('eppn'        => array('/@ubc.ca/' => ''),
                                                                              'affiliation' => array('/staff@ubc.ca/' => 'admin'),
                                                                             ),
                                               'loginError'          => 'You have successfully logged through Shibboleth. But you do not have access this appliction.',
                                              ); 
}}}
* sessionInitiatorURL: The URL for the Shibboleth login. %HOST% will be replaced to the actual host name
* logoutURL: The URL for Shibboleth logout. %HOST% will be replaced to the actual host name
* fieldMapping: The array to map the attributes from Shibboleth to database fields. The keys are the Shibboleth attributes and values are the fields in database.
* mappingRules: The array of rules for how to convert the values. The rules are regular expressions.
* loginError: The error message when user logged in successfully through Shibboleth but do not have an valid account or permission in the application. This is an example to override the [http://api13.cakephp.org/class/auth-component AuthComponent] properties. 


== Customize Modules ==

By default, the existing modules come with a simple login template under app/plugins/guard/views/guard. Each module has its own element for the login template under app/plugins/guard/views/elements, e.g. text input for Default and login button for Shibboleth. 

If you want to customize the template or elements:
 * Create app/views/plugins/guard/guard/login.ctp for template
 * Create app/views/plugins/guard/elements/login_MODULENAME.ctp for elemets
 * The MODULENAME is the authentication module you want to customize, e.g. Shibboleth or Default
 * Now CakePHP will render your template or elements instead of default ones


== Developing New Module ==
All the authentication modules extend !AuthModule, which provides some default properties and methods required by the authentication module. 
Every authentication must implement  authenticate() method to verify the user. The authentication module should like look this:
{{{
#!php
class MyAuthModule extends AuthModule {
  var $name         = 'MyAuth';
  var $hasLoginForm = true;
  function authenticate() {
    // return true if user is verified and false if not.
  }
}
}}}

 * $name: The name of the authentication module.
 * $hasLoginForm: If this module has login form

The new module should be placed in app/libs with the name like: MODULENAME_module.php