includes/AuthPlugin.php

   1 <?php
   2 /**
   3  */
   4 # Copyright (C) 2004 Brion Vibber <brion@pobox.com>
   5 # http://www.mediawiki.org/
   6 #
   7 # This program is free software; you can redistribute it and/or modify
   8 # it under the terms of the GNU General Public License as published by
   9 # the Free Software Foundation; either version 2 of the License, or
  10 # (at your option) any later version.
  11 #
  12 # This program is distributed in the hope that it will be useful,
  13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15 # GNU General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU General Public License along
  18 # with this program; if not, write to the Free Software Foundation, Inc.,
  19 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  20 # http://www.gnu.org/copyleft/gpl.html
  21
  22 /**
  23  * Authentication plugin interface. Instantiate a subclass of AuthPlugin
  24  * and set $wgAuth to it to authenticate against some external tool.
  25  *
  26  * The default behavior is not to do anything, and use the local user
  27  * database for all authentication. A subclass can require that all
  28  * accounts authenticate externally, or use it only as a fallback; also
  29  * you can transparently create internal wiki accounts the first time
  30  * someone logs in who can be authenticated externally.
  31  */
  32 class AuthPlugin {
  33         /**
  34          * Check whether there exists a user account with the given name.
  35          * The name will be normalized to MediaWiki's requirements, so
  36          * you might need to munge it (for instance, for lowercase initial
  37          * letters).
  38          *
  39          * @param $username String: username.
  40          * @return bool
  41          * @public
  42          */
  43         function userExists( $username ) {
  44                 # Override this!
  45                 return false;
  46         }
  47
  48         /**
  49          * Check if a username+password pair is a valid login.
  50          * The name will be normalized to MediaWiki's requirements, so
  51          * you might need to munge it (for instance, for lowercase initial
  52          * letters).
  53          *
  54          * @param $username String: username.
  55          * @param $password String: user password.
  56          * @return bool
  57          * @public
  58          */
  59         function authenticate( $username, $password ) {
  60                 # Override this!
  61                 return false;
  62         }
  63
  64         /**
  65          * Modify options in the login template.
  66          *
  67          * @param $template UserLoginTemplate object.
  68          * @public
  69          */
  70         function modifyUITemplate( &$template ) {
  71                 # Override this!
  72                 $template->set( 'usedomain', false );
  73         }
  74
  75         /**
  76          * Set the domain this plugin is supposed to use when authenticating.
  77          *
  78          * @param $domain String: authentication domain.
  79          * @public
  80          */
  81         function setDomain( $domain ) {
  82                 $this->domain = $domain;
  83         }
  84
  85         /**
  86          * Check to see if the specific domain is a valid domain.
  87          *
  88          * @param $domain String: authentication domain.
  89          * @return bool
  90          * @public
  91          */
  92         function validDomain( $domain ) {
  93                 # Override this!
  94                 return true;
  95         }
  96
  97         /**
  98          * When a user logs in, optionally fill in preferences and such.
  99          * For instance, you might pull the email address or real name from the
 100          * external user database.
 101          *
 102          * The User object is passed by reference so it can be modified; don't
 103          * forget the & on your function declaration.
 104          *
 105          * @param User $user
 106          * @public
 107          */
 108         function updateUser( &$user ) {
 109                 # Override this and do something
 110                 return true;
 111         }
 112
 113
 114         /**
 115          * Return true if the wiki should create a new local account automatically
 116          * when asked to login a user who doesn't exist locally but does in the
 117          * external auth database.
 118          *
 119          * If you don't automatically create accounts, you must still create
 120          * accounts in some way. It's not possible to authenticate without
 121          * a local account.
 122          *
 123          * This is just a question, and shouldn't perform any actions.
 124          *
 125          * @return bool
 126          * @public
 127          */
 128         function autoCreate() {
 129                 return false;
 130         }
 131
 132         /**
 133          * Can users change their passwords?
 134          *
 135          * @return bool
 136          */
 137         function allowPasswordChange() {
 138                 return true;
 139         }
 140
 141         /**
 142          * Set the given password in the authentication database.
 143          * As a special case, the password may be set to null to request
 144          * locking the password to an unusable value, with the expectation
 145          * that it will be set later through a mail reset or other method.
 146          *
 147          * Return true if successful.
 148          *
 149          * @param $user User object.
 150          * @param $password String: password.
 151          * @return bool
 152          * @public
 153          */
 154         function setPassword( $user, $password ) {
 155                 return true;
 156         }
 157
 158         /**
 159          * Update user information in the external authentication database.
 160          * Return true if successful.
 161          *
 162          * @param $user User object.
 163          * @return bool
 164          * @public
 165          */
 166         function updateExternalDB( $user ) {
 167                 return true;
 168         }
 169
 170         /**
 171          * Check to see if external accounts can be created.
 172          * Return true if external accounts can be created.
 173          * @return bool
 174          * @public
 175          */
 176         function canCreateAccounts() {
 177                 return false;
 178         }
 179
 180         /**
 181          * Add a user to the external authentication database.
 182          * Return true if successful.
 183          *
 184          * @param User $user - only the name should be assumed valid at this point
 185          * @param string $password
 186          * @param string $email
 187          * @param string $realname
 188          * @return bool
 189          * @public
 190          */
 191         function addUser( $user, $password, $email='', $realname='' ) {
 192                 return true;
 193         }
 194
 195
 196         /**
 197          * Return true to prevent logins that don't authenticate here from being
 198          * checked against the local database's password fields.
 199          *
 200          * This is just a question, and shouldn't perform any actions.
 201          *
 202          * @return bool
 203          * @public
 204          */
 205         function strict() {
 206                 return false;
 207         }
 208
 209         /**
 210          * Check if a user should authenticate locally if the global authentication fails.
 211          * If either this or strict() returns true, local authentication is not used.
 212          *
 213          * @param $username String: username.
 214          * @return bool
 215          * @public
 216          */
 217         function strictUserAuth( $username ) {
 218                 return false;
 219         }
 220
 221         /**
 222          * When creating a user account, optionally fill in preferences and such.
 223          * For instance, you might pull the email address or real name from the
 224          * external user database.
 225          *
 226          * The User object is passed by reference so it can be modified; don't
 227          * forget the & on your function declaration.
 228          *
 229          * @param $user User object.
 230          * @param $autocreate bool True if user is being autocreated on login
 231          * @public
 232          */
 233         function initUser( $user, $autocreate=false ) {
 234                 # Override this to do something.
 235         }
 236
 237         /**
 238          * If you want to munge the case of an account name before the final
 239          * check, now is your chance.
 240          */
 241         function getCanonicalName( $username ) {
 242                 return $username;
 243         }
 244 }
 245
 246