From ff4b053b6f02a76d062674aa46bd866b324abc13 Mon Sep 17 00:00:00 2001 From: Olivier Berger Date: Tue, 15 Mar 2011 14:06:42 +0000 Subject: [PATCH] Some more doc strings and comments --- src/common/include/AuthPlugin.class.php | 53 ++++++++++++++++++- .../common/AuthBuiltinPlugin.class.php | 10 ++++ .../authcas/include/AuthCASPlugin.class.php | 26 +++++++++ src/plugins/authcas/www/post-login.php | 7 ++- src/www/account/login.php | 2 + 5 files changed, 96 insertions(+), 2 deletions(-) diff --git a/src/common/include/AuthPlugin.class.php b/src/common/include/AuthPlugin.class.php index b590e0bc99..88b252eb2a 100644 --- a/src/common/include/AuthPlugin.class.php +++ b/src/common/include/AuthPlugin.class.php @@ -22,10 +22,16 @@ * USA */ +// See for details http://lists.fusionforge.org/pipermail/fusionforge-general/2011-February/001335.html + define('FORGE_AUTH_AUTHORITATIVE_ACCEPT', 1); define('FORGE_AUTH_AUTHORITATIVE_REJECT', 2); define('FORGE_AUTH_NOT_AUTHORITATIVE', 3); +/** + * Pluggable Authentication plugins base class + * + */ abstract class ForgeAuthPlugin extends Plugin { /** * ForgeAuthPlugin() - constructor @@ -35,7 +41,7 @@ abstract class ForgeAuthPlugin extends Plugin { $this->Plugin(); // Common hooks that can be enabled per plugin: // check_auth_session - is there a valid session? - // fetch_auth_info - what GFUser is logged in? + // fetch_authenticated_user - what GFUser is logged in? // display_auth_form - display a form to input credentials // display_create_user_form - display a form to create a user from external auth // sync_account_info - sync identity from external source (realname, email, etc.) @@ -56,12 +62,15 @@ abstract class ForgeAuthPlugin extends Plugin { $this->fetchAuthUser($params); break; case 'display_auth_form': + // no default implementation, but see AuthBuiltinPlugin::displayAuthForm() $this->displayAuthForm($params); break; case 'display_create_user_form': + // no default implementation $this->displayCreateUserForm($params); break; case 'sync_account_info': + // no default implementation $this->syncAccountInfo($params); break; case 'get_extra_roles': @@ -80,6 +89,10 @@ abstract class ForgeAuthPlugin extends Plugin { // Default mechanisms protected $saved_user; + /** + * Is there a valid session? + * @param unknown_type $params + */ function checkAuthSession(&$params) { if (isset($params['auth_token']) && $params['auth_token'] != '') { $user_id = $this->checkSessionToken($params['auth_token']); @@ -104,12 +117,21 @@ abstract class ForgeAuthPlugin extends Plugin { } } + /** + * What GFUser is logged in? + * @param unknown_type $params + */ function fetchAuthUser(&$params) { if ($this->saved_user && $this->isSufficient()) { $params['results'] = $this->saved_user; } } + /** + * Terminate an authentication session + * @param unknown_type $params + * @return boolean + */ function closeAuthSession($params) { if ($this->isSufficient() || $this->isRequired()) { $this->unsetSessionCookie(); @@ -118,10 +140,18 @@ abstract class ForgeAuthPlugin extends Plugin { } } + /** + * Add new roles not necessarily stored in the database + * @param unknown_type $params + */ function getExtraRoles(&$params) { // $params['new_roles'][] = RBACEngine::getInstance()->getRoleById(123); } + /** + * Filter out unwanted roles + * @param unknown_type $params + */ function restrictRoles(&$params) { // $params['dropped_roles'][] = RBACEngine::getInstance()->getRoleById(123); } @@ -143,6 +173,11 @@ abstract class ForgeAuthPlugin extends Plugin { session_set_cookie($this->cookie_name, $cookie, "", forge_get_config('session_expire')); } + /** + * TODO: Enter description here ... + * @param string $username + * @return boolean + */ function login($username) { if ($this->isSufficient() || $this->isRequired()) { $params = array(); @@ -161,14 +196,27 @@ abstract class ForgeAuthPlugin extends Plugin { session_set_cookie($this->cookie_name, ''); } + /** + * TODO: Enter description here ... + * @return Ambigous + */ public function isRequired() { return forge_get_config('required', $this->name); } + /** + * TODO: Enter description here ... + * @return Ambigous + */ public function isSufficient() { return forge_get_config('sufficient', $this->name); } + /** + * TODO: Enter description here ... + * @param unknown_type $event + * @return boolean + */ public function syncDataOn($event) { $configval = forge_get_config('sync_data_on', $this->name); $events = array(); @@ -191,6 +239,9 @@ abstract class ForgeAuthPlugin extends Plugin { return in_array($event, $events); } + /** + * TODO: Enter description here ... + */ protected function declareConfigVars() { forge_define_config_item ('required', $this->name, 'yes'); forge_set_config_item_bool ('required', $this->name) ; diff --git a/src/plugins/authbuiltin/common/AuthBuiltinPlugin.class.php b/src/plugins/authbuiltin/common/AuthBuiltinPlugin.class.php index 0a942551fb..8da5727b82 100644 --- a/src/plugins/authbuiltin/common/AuthBuiltinPlugin.class.php +++ b/src/plugins/authbuiltin/common/AuthBuiltinPlugin.class.php @@ -22,6 +22,11 @@ * USA */ +/** + * Default authentication mechanism based on DB user's password storage + * + */ + class AuthBuiltinPlugin extends ForgeAuthPlugin { /** * AuthBuiltinPlugin() - constructor @@ -45,6 +50,11 @@ class AuthBuiltinPlugin extends ForgeAuthPlugin { $this->declareConfigVars(); } + /** + * Display a form to input credentials : default login dialog + * @param unknown_type $params + * @return boolean + */ function displayAuthForm($params) { if (!$this->isRequired() && !$this->isSufficient()) { return true; diff --git a/src/plugins/authcas/include/AuthCASPlugin.class.php b/src/plugins/authcas/include/AuthCASPlugin.class.php index 95a7a051f5..ca816a272c 100644 --- a/src/plugins/authcas/include/AuthCASPlugin.class.php +++ b/src/plugins/authcas/include/AuthCASPlugin.class.php @@ -21,8 +21,14 @@ */ require_once $GLOBALS['gfcommon'].'include/User.class.php'; + +// from phpCAS (https://wiki.jasig.org/display/CASC/phpCAS) require_once 'CAS.php'; +/** + * Authentication manager for FusionForge CASification + * + */ class AuthCASPlugin extends ForgeAuthPlugin { function AuthCASPlugin () { global $gfconfig; @@ -63,6 +69,11 @@ class AuthCASPlugin extends ForgeAuthPlugin { self::$init = true; } + /** + * Display a form to input credentials + * @param unknown_type $params + * @return boolean + */ function displayAuthForm($params) { if (!$this->isRequired() && !$this->isSufficient()) { return true; @@ -81,6 +92,10 @@ class AuthCASPlugin extends ForgeAuthPlugin { ' ; } + /** + * Is there a valid session? + * @param unknown_type $params + */ function checkAuthSession(&$params) { $this->initCAS(); @@ -112,6 +127,10 @@ class AuthCASPlugin extends ForgeAuthPlugin { } } + /** + * What GFUser is logged in? + * @param unknown_type $params + */ function fetchAuthUser(&$params) { if ($this->saved_user && $this->isSufficient()) { $params['results'] = $this->saved_user; @@ -123,12 +142,19 @@ class AuthCASPlugin extends ForgeAuthPlugin { if ($this->isSufficient() || $this->isRequired()) { $this->unsetSessionCookie(); + // logs user out from CAS + // TODO : make it optional to not mess with other apps' SSO sessions with CAS phpCAS::logoutWithRedirectService(util_make_url('/')); } else { return true; } } + /** + * Terminate an authentication session + * @param unknown_type $params + * @return boolean + */ protected function declareConfigVars() { parent::declareConfigVars(); diff --git a/src/plugins/authcas/www/post-login.php b/src/plugins/authcas/www/post-login.php index 27e976bfc5..1d98f4109e 100644 --- a/src/plugins/authcas/www/post-login.php +++ b/src/plugins/authcas/www/post-login.php @@ -1,12 +1,13 @@ initCAS(); if (phpCAS::isAuthenticated()) { diff --git a/src/www/account/login.php b/src/www/account/login.php index 62aae3060b..50640c9b2f 100644 --- a/src/www/account/login.php +++ b/src/www/account/login.php @@ -50,6 +50,8 @@ if ($triggered) { } echo '

'; +// see AuthBuiltinPlugin::displayAuthForm() that should do the work by default + $params = array(); $params['return_to'] = $return_to; plugin_hook('display_auth_form', $params); -- 2.30.2