[[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+ == Available Authentication Methods == * CakePHP internal * Shibboleth * LDAP == Download == {{{ git clone https://github.com/xcompass/CakePHP-Guard-Plugin.git 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. === LDAP Module === LDAP module is used to authenticate against the existing LDAP server. The configuration parameters for LDAP are: {{{ #!php $config['Guard.AuthModule.Ldap'] = array( 'host' => 'ldaps://ldapcons.stg.id.ubc.ca/', 'port' => 636, 'serviceUsername' => 'uid=USERNAME, ou=Special Users, o=school.ca', // username to connect to LDAP 'servicePassword' => 'PASSWORD', // password to connect to LDAP 'baseDn' => 'ou=Campus Login, o=school.ca', 'usernameField' => 'username', 'attributeSearchFilters' => array( // 'uid', ), 'attributeMap' => array( // 'username' => 'uid', ), ); }}} * host: The LDAP server address * port: The LDAP server port * serviceUsername: The username used to connect to LDAP server * servicePassword: The password used to connect to LDAP server * baseDn: The base DN * usernameField: Change it if the key name of the username is not "username" in the LDAP directory * attributeSearchFilters: The filters is used to search for attributes. The values of those filters come from the first ldap search (using the username) * attributeMap: Mapping the attributes to the $this->data === Note === Change the Security.level to low in core.php if using external authentication module {{{ #!php 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 {{{ #!php Router::connect('/login', array('controller' => 'users', 'action' => 'login')); }}} Disable the autoRedirect in app_controller.php {{{ #!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: {{{ #!php 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: {{{ #!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 == 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)