Changes between Version 1 and Version 2 of GuardPlugin

Timestamp:

2010-08-19T17:58:20Z (14 years ago)

Author:

Pan Luo

Comment:

--

GuardPlugin

@@ -5 +5 @@
 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 ==
 
 == 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
+}}}
+
 == 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 Authentication 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.
 
-== Develop New Authentication Module ==
+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. 
+
+== Developing New Authentication 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
+
+