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 ​AuthComponent and it provides full back compatibly. If the application is developed on ​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 ​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 (​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 ​AuthComponent to verify the users.

Shibboleth Module

This module supports ​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:

$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 ​AuthComponent properties.

Note

Change the Security.level to low in core.php if using external authentication module

 Configure::write('Security.level', 'low');

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

Doing Stuff After User login

To do stuff after login, make sure the route /login is in the app/config/routes.php

Router::connect('/login', array('controller' => 'users', 'action' => 'login'));

Disable the autoRedirect in app_controller.php

public function beforeFilter()
{
    $this->Auth->autoRedirect = false;
     .....
}

Create a login action in users controller (the controller and action can be change by changing the value in the route created above:

class UsersController extends AppController
{
    .....
    function login()
    {
         if ($this->Auth->isAuthorized()) {
              // after login stuff
         }   
    }
}

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:

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

FAQs

• When I enabled an external auth module, it goes into a redirection loop after authenticated back from external module.

Change the Security.level to low in core.php. If Security.level is high or medium, cakephp checks the referral link. It will invalid the session if referral link is from external source. (​http://www.php.net/manual/en/session.configuration.php#ini.session.referer-check)