3 * StatusNet, the distributed open-source microblogging tool
5 * Superclass for plugins that do authentication and/or authorization
9 * LICENCE: This program is free software: you can redistribute it and/or modify
10 * it under the terms of the GNU Affero General Public License as published by
11 * the Free Software Foundation, either version 3 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU Affero General Public License for more details.
19 * You should have received a copy of the GNU Affero General Public License
20 * along with this program. If not, see <http://www.gnu.org/licenses/>.
24 * @author Craig Andrews <candrews@integralblue.com>
25 * @copyright 2009 Free Software Foundation, Inc http://www.fsf.org
26 * @license http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
27 * @link http://status.net/
30 if (!defined('GNUSOCIAL')) { exit(1); }
33 * Superclass for plugins that do authentication
37 * @author Craig Andrews <candrews@integralblue.com>
38 * @license http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
39 * @link http://status.net/
41 abstract class AuthenticationPlugin extends Plugin
43 //is this plugin authoritative for authentication?
44 public $authoritative = false;
46 //should accounts be automatically created after a successful login attempt?
47 public $autoregistration = false;
49 //can the user change their email address
50 public $password_changeable=true;
52 //unique name for this authentication provider
53 public $provider_name;
55 //------------Auth plugin should implement some (or all) of these methods------------\\
57 * Check if a nickname/password combination is valid
60 * @return boolean true if the credentials are valid, false if they are invalid.
62 function checkPassword($username, $password)
68 * Automatically register a user when they attempt to login with valid credentials.
69 * User::register($data) is a very useful method for this implementation
70 * @param username username (that is used to login and find the user in the authentication provider) of the user to be registered
71 * @param nickname nickname of the user in the SN system. If nickname is null, then set nickname = username
72 * @return mixed instance of User, or false (if user couldn't be created)
74 function autoRegister($username, $nickname = null)
76 if(is_null($nickname)){
77 $nickname = $username;
79 $registration_data = array();
80 $registration_data['nickname'] = $nickname;
81 return User::register($registration_data);
85 * Change a user's password
86 * The old password has been verified to be valid by this plugin before this call is made
90 * @return boolean true if the password was changed, false if password changing failed for some reason
92 function changePassword($username,$oldpassword,$newpassword)
98 * Given a username, suggest what the nickname should be
99 * Used during autoregistration
100 * Useful if your usernames are ugly, and you want to suggest
101 * nice looking nicknames when users initially sign on
102 * All nicknames returned by this function should be valid
103 * implementations may want to use common_nicknamize() to ensure validity
105 * @return string nickname
107 function suggestNicknameForUsername($username)
109 return common_nicknamize($username);
112 //------------Below are the methods that connect StatusNet to the implementing Auth plugin------------\\
113 function onInitializePlugin(){
114 if(!isset($this->provider_name)){
115 throw new Exception("must specify a provider_name for this authentication provider");
120 * Internal AutoRegister event handler
122 * @param provider_name
123 * @param user - the newly registered user
125 function onAutoRegister($nickname, $provider_name, &$user)
127 if($provider_name == $this->provider_name && $this->autoregistration){
128 $suggested_nickname = $this->suggestNicknameForUsername($nickname);
129 $test_user = User::getKV('nickname', $suggested_nickname);
131 //someone already exists with the suggested nickname, so used the passed nickname
132 $suggested_nickname = common_nicknamize($nickname);
134 $test_user = User::getKV('nickname', $suggested_nickname);
136 //someone already exists with the suggested nickname
137 //not much else we can do
139 $user = $this->autoRegister($nickname, $suggested_nickname);
140 if ($user instanceof User) {
141 User_username::register($user,$nickname,$this->provider_name);
148 function onStartCheckPassword($nickname, $password, &$authenticatedUser){
149 //map the nickname to a username
150 $user_username = new User_username();
151 $user_username->username=$nickname;
152 $user_username->provider_name=$this->provider_name;
153 if($user_username->find() && $user_username->fetch()){
154 $authenticated = $this->checkPassword($user_username->username, $password);
156 $authenticatedUser = User::getKV('id', $user_username->user_id);
160 //$nickname is the username used to login
161 //$suggested_nickname is the nickname the auth provider suggests for that username
162 $suggested_nickname = $this->suggestNicknameForUsername($nickname);
163 $user = User::getKV('nickname', $suggested_nickname);
165 //make sure this user isn't claimed
166 $user_username = new User_username();
167 $user_username->user_id=$user->id;
168 $we_can_handle = false;
169 if($user_username->find()){
170 //either this provider, or another one, has already claimed this user
171 //so we cannot. Let another plugin try.
174 //no other provider claims this user, so it's safe for us to handle it
175 $authenticated = $this->checkPassword($nickname, $password);
177 $authenticatedUser = $user;
178 User_username::register($authenticatedUser,$nickname,$this->provider_name);
183 $authenticated = $this->checkPassword($nickname, $password);
185 if(! Event::handle('AutoRegister', array($nickname, $this->provider_name, &$authenticatedUser))){
186 //unlike most Event::handle lines of code, this one has a ! (not)
187 //we want to do this if the event *was* handled - this isn't a "default" implementation
188 //like most code of this form.
189 if($authenticatedUser){
196 if($this->authoritative){
199 //we're not authoritative, so let other handlers try
204 function onStartChangePassword($user,$oldpassword,$newpassword)
206 if($this->password_changeable){
207 $user_username = new User_username();
208 $user_username->user_id=$user->id;
209 $user_username->provider_name=$this->provider_name;
210 if($user_username->find() && $user_username->fetch()){
211 $authenticated = $this->checkPassword($user_username->username, $oldpassword);
213 $result = $this->changePassword($user_username->username,$oldpassword,$newpassword);
215 //stop handling of other handlers, because what was requested was done
218 // TRANS: Exception thrown when a password change fails.
219 throw new Exception(_('Password changing failed.'));
222 if($this->authoritative){
223 //since we're authoritative, no other plugin could do this
224 // TRANS: Exception thrown when a password change fails.
225 throw new Exception(_('Password changing failed.'));
227 //let another handler try
233 if($this->authoritative){
234 //since we're authoritative, no other plugin could do this
235 // TRANS: Exception thrown when a password change attempt fails because it is not allowed.
236 throw new Exception(_('Password changing is not allowed.'));
241 function onStartAccountSettingsPasswordMenuItem($widget)
243 if($this->authoritative && !$this->password_changeable){
244 //since we're authoritative, no other plugin could change passwords, so do not render the menu item
249 function onCheckSchema() {
250 $schema = Schema::get();
251 $schema->ensureTable('user_username', User_username::schemaDef());
255 function onUserDeleteRelated($user, &$tables)
257 $tables[] = 'User_username';