rEOID/81f4037ca534master
/
README
MediaWiki OpenID extension README version 3.41 20131003
Homepage and manual http://www.mediawiki.org/wiki/Extension:OpenID
This is the README file for the OpenID extension for MediaWiki software. The extension is only useful if you've got a MediaWiki installation; it can only be installed by the administrator of the site.
The extension lets users log in with an OpenID (http://www.openid.net/) instead of a username and password. An OpenID is a special URL that people can use to log in to a Web site. The extension also lets users who have an account on the wiki log in to other OpenID-aware Web sites with their wiki user page as their OpenID.
Typical uses:
- Single-signon between multiple affiliated wikis and other sites.
- Single-signon across the Internet. Many, many sites now support OpenID, including "big names" like Yahoo!, Google, and AOL. Allowing users to login with OpenID means one less step for them to contribute to your wiki.
- Distributed reputation. Logging into a new wiki with the same username as you have on another wiki doesn't prove that they're the same person. Logging in with your OpenID from the old wiki does. Using OpenID can help build a distributed reputation across the wiki world.
The software supports OpenID 2.0 and '''requires''' the openidenabled.com 2.2.2 libraries. Users of previous versions should see #Upgrade for more information.
This extension has been in use for years on several large wikis without known security problems. However, no software is completely bug-free or secure, and there's no guarantee that this software will work as advertised. See #Bugs section below for info on how to report problems.
License
Copyright 2006,2007 Internet Brands (http://www.internetbrands.com/) Copyright 2008 Evan Prodromou (http://vinismo.com/en/User:Evan)
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Authors
Evan Prodromou <evan@vinismo.com> Patches for YADIS support and FileStore storage by Jonathan Daugherty <cygnus@janrain.com>. Thomas Gries
Pre-requisites
Always use latest MediaWiki and latest OpenID versions.
This software has been tested with all versions MediaWiki 1.19 rev. 88135 until MediaWiki 1.22alpha.
The software depends on the PHP library for OpenID https://github.com/openid/php-openid
Information: the original homepage for the library was http://www.openidenabled.com/php-openid/ but this page not maintained any more.
This software requires PHP being installed with gmp, mcrypt, curl, openssl, xml and certain other extensions. See http://www.mediawiki.org/wiki/Extension:OpenID for details.
/* FIXME: */ Note that some versions of MediaWiki overwrite the PHP library path in LocalSettings.php. Perhaps you may need to add the path to your PHP library directory to the $path variable, like "/usr/share/php" or "/usr/local/share/php".
Installation
Note that the software currently depends on having all its code in the "OpenID" sub-directory; naming it "OpenID-Test" or "newextension1" or whatever won't work.
In your MediaWiki LocalSettings.php, add the following line some place towards the bottom of the file:
require_once( "$IP/extensions/OpenID/OpenID.php" );
Run update.php script in in your MediaWiki maintenance folder to conditionally create a new table in MediaWiki database as required by the OpenID extension:
cd $IP/maintenance php update.php
Theoretically it should work out of the box, but you'll almost definitely want to set the trust root and access controls (see Configuration below).
Upgrade from OpenID versions before 3.x
'''This is an incompatible upgrade to the previous version of the MediaWiki OpenID library.''' In particular, the interfaces of the openidenabled.com libraries have changed from 1.x to 2.x, and no effort has been made to retain backwards compatibility with the 1.x versions of the library.
To upgrade, you'll need to do at least the following:
- Install the latest version of the PHP OpenID library https://github.com/openid/php-openid
- Check that your consumer and server stores are correct. The original maintainer got tired of maintaining the MemcStore that nobody seemed to want, so if you used that, you need to use the filestore now. See below for how to configure it.
- Change your require_once line in LocalSettings.php to use the openid.php file.
- The extension has been converted to use a clumsy and perverse OOP-like structure, with one class per special page. Most function names have been changed to methods of these classes. If you used them, look around for their replacements.
- The extension has been converted to use the autoloading features of MediaWiki, which means that you need to require() the files directly if you really want to use their code. Or you might get lucky and have autoloading work for you.
If you find other incompatibilities that I haven't mentioned here, please let me know.
Logging in using OpenID
To log in to the wiki using an OpenID, go to the Special:OpenIDLogin page on the wiki. Add the OpenID identity URL to the login box, and click "Verify".
This ''should'' take you to the OpenID server for your identity, where you can either log in (if you're not already) or approve allowing the wiki to use your OpenID for logging in. If the OpenID server supports the Simple Registration Extension ('sreg'), it may also ask you whether to share personal information like your preferred nickname, real name, email address, etc. Choose as you wish.
Once you're logged in to your OpenID server, and you've finished approving the login, you should return to the wiki from whence you came automatically.
Every user who logs in with an OpenID identity for the first time will be assigned a "fake" username in the local wiki. (This just makes things work better.)
If you've allowed your nickname to be passed to the wiki, and it's not already taken, and it's a legal MediaWiki user name, then it should use that for your login automatically.
If not, the extension will try to make up some good candidate usernames for you and present you with a choice. If you don't like any of them, you can make up your own.
After you're logged in, you can edit, read, write, and do all the other things that MediaWiki users do. Since you've got a "real" account, you'll also have a home page and a message page and such. It should also be possible to assign extra permissions ('sysop', 'bureaucrat') to the account. You can log out as normal.
To log back in, use the OpenIDLogin page again. Don't try to login using the regular login page, since it won't work.
You can log in with an Interwiki abbreviation of an URL right now, but that's experimental and may disappear in later versions. Don't fall in love with this convenient, useful feature. You may get hurt.
Using a MediaWiki account as an OpenID
To log in to other sites with your MediaWiki account, your OpenID identity URL is the full URL of your MediaWiki user page or the generic login page with a URL like http://www.example.org/wiki/Special:OpenIDServer/id .
When you use this OpenID with another site, logging in should take you to the wiki site. You may need to enter your password if you're not already logged in.
You'll then be asked if you want to let the other site log you in, and if you want the MediaWiki wiki to share your personal information (nickname, email, full name, language) with the other site. Choose what feels comfortable to you. For some sites, you may not be asked; see Configuration below.
Once you've finished deciding, the other site will finish the login.
You can't log in through OpenID on the same server. You can't use the user page for a fake account created for an OpenID login as an OpenID itself.
Configuration
FIXME THIS SECTION IS NOT UP TO DATE PLEASE VISIT http://www.mediawiki.org/wiki/Extension:OpenID FOR UP-TO-DATE INFORMATION
The administrator can configure these variables in the LocalSettings.php file. Please read carefully.
- $wgOpenIDTrustRoot -- This is an URL that identifies your site to OpenID servers. Typically, it's the "root" url of the site, like "http://en.wikipedia.org/" or with a path like "http://wikitravel.org/it/". If this is not set, the software will make a half-hearted guess, but it's not very good and you should probably just set it.
- $wgOpenIDConsumerDenyByDefault -- The administrator can decide which OpenIDs are allowed to login to their server. If this flag is true, only those OpenIDs that match one of the $wgOpenIDConsumerAllow and not one of the $wgOpenIDConsumerDeny patterns will be allowed to log in. If it is false, all OpenIDs are allowed to log in, unless they are matched by an $wgOpenIDConsumerDeny pattern and not an $wgOpenIDConsumerAllow. Typically you'll set this to true for testing and then false for general use.
- $wgOpenIDConsumerAllow -- an array of regular expressions that match OpenIDs you want to allow to log in. For example, "@^(http://)?wikitravel.org/@" will allow OpenIDs from the Wikitravel domain.
- $wgOpenIDConsumerDeny -- an array of regular expressions that match OpenIDs you want to deny access to. This is mostly useful for servers that are known to be bad. Example: "#^(http://)?example.com/#".
- $wgOpenIDForcedProvider -- (null or string) a name of a supported provider, or a fully qualified url of the Id selection page of an arbitrary provider, which will always be used, aka "forced provider".
Setting this value bypasses the extension's selection dialog and manual entry. It is useful for team wikis using a fixed (hard-coded) provider such as Google, or another MediaWiki as OpenID Provider for logging in to your wiki.
- $wgOpenIDProviders -- (array) names and parameters of OpenID Providers, which are supported by the extension.
The format is
array( 'providername' => array( <provider-parameters> ) )
Respected keys for provider parameters are:- 'openid-url': the url of the openid provider may contain '{username}' in order to display a form requesting a username that will be substitutde into the url before attempting authentication.
- 'large-provider': if true it will be displayed in the large buttons otherwise will be displayed in the small buttons
- 'label': If set this exact string will be the label when the provider is selected. If not present a localization message with a key of the 'openid-provider-label-$providerName' is used.
- $wgOpenIDDefaultProviderName -- (null or string) Defaults to null. The provider name in $wgOpenIDProviders that will be shown preselected as default to new users who never selected an provider before.
- $wgOpenIDUseEmailAsNickname -- designed for use with the above, parse the e-mail address provided by your provider and use the user component as the MediaWiki username.
- $wgOpenIDProposeUsernameFromSREG defaults to true; when first-time logging in with OpenID, propose and allow new account names from OpenID SREG data such as fullname or nickname
- $wgOpenIDAllowNewAccountname defaults to true; when first-time logging in with OpenID, show option to enter and to allow a manually chosen username for a new wiki account
- $wgOpenIDAllowExistingAccountSelection defaults to true; whether associating an existing account with OpenID is allowed
- $wgOpenIDAllowAutomaticUsername defaults to true; when first-time logging in with OpenID, show option to choose and to allow an automatically generated username
- $wgOpenIDTrustEmailAddress -- trust the e-mail address sent by the provider and don't require it to be verified. If false (the default), all new users will be required to validate their e-mail address.
- $wgOpenIDServerForceAllowTrust -- an array of regular expressions that match trust roots that you want to skip trust checks for when the user logs in from those sites. A typical example would be a closely federated cluster of sites (like Wikimedia, Wikia, or Wikitravel) where the personal data is available to the trusting server ''anyways''. Be very careful using this across organizational boundaries.
- $wgOpenIDConsumerStoreType and $wgOpenIDServerStoreType -- strings denoting the type of storage to be used to store OpenID assocation data when acting as an OpenID relying party (consumer) and server, respectively. Valid values are "file", "memcached" and "db".
- $wgOpenIDConsumerStorePath and $wgOpenIDServerStorePath -- strings specifying the paths where OpenID assocation data should be stored when acting as a relying party (consumer) or server, respectively. Each of these need only be set if the store type settings (above) are set to "file", respectively. These strings, if both are set, MUST NOT be equal. If the store type is "file", the default here is "/tmp/$wgDBname/openidconsumer/" and "/tmp/$wgDBname/openidserver/" respectively. The path will be automatically created if it doesn't exist at runtime.
- $wgOpenIDHideOpenIDLoginLink -- boolean that says whether or not to hide the OpenID login link in the personal URLs. Typically you'd use this if you've already got some other method for showing the OpenID login link, like in your skin. Note that it will *not* prevent login if the user navigates to Special:OpenIDLogin directly; it's simply cosmetic. This is mostly a backwards-compatibility option.
- $wgOpenIDLoginLogoUrl ($wgOpenIDSmallLogoUrl until v3.05)
- Url of the OpenID login logo. Defaults to a built-in logo like 'http://www.openid.net/login-bg.gif', but you may want to move it to a local URL, or an URL on a CDN, if that kind of thing floats your boat.
- $wgOpenIDShowUrlOnUserPage -- whether to show the OpenID identity URL on a user's home page. Possible values are 'always', 'never', or 'user' (lets the user decide). Default is 'user'.
- $wgOpenIDLoginOnly ($wgOpenIDOnly until 3.09)
- defaults to false. With this enabled, users can ''only'' log in with OpenID.
- $wgOpenIDConsumerAndAlsoProvider ($wgOpenIDClientOnly until version 3.11)
- defaults to false. With this enabled, users cannot use their accounts on the local wiki as OpenIDs on another site. Sucks for users, but some admins have emailed me about not wanting the responsibility of being an OpenID server, so this flag is for them.
- $wgOpenIDAllowServingOpenIDUserAccounts -- defaults to false. Having this enabled, it allows to use Urls of this wiki's users' pages as OpenID identities on other OpenID-aware sites even when OpenID(s) are associated with user accounts on this wiki. Some users might want to do that for vanity purposes or whatever.
False prevents the serving of User page URLs as OpenID accounts on other sites.
Remark:
User page urls can (currently) only act as OpenID if the user page really exists i.e. has content. The mere existence of a user account is (currently) not sufficient.
- $wgOpenIDMergeOnAccountMerge (default: false) When merging accounts with the UserMerge and Delete extension, should OpenIDs associated to the "from" account automatically be associated to the "to" account ?
- $wgOpenIDShowProviderIcons -- defaults to false due to potential brand issues. With this enabled, users will see button graphics instead of just links in OpenID provider UI.
Setups of standard scenarios
This section shows some settings for typical applications.
Example 1:
The following code in $IP/LocalSettings.php sets a MediaWiki for allowing user name account creations by Sysops only ("account creation by mail").
Sysop-defined users can then login to their accounts but only with an OpenID identity. They need to associate their OpenID identity with their user name and user account; this step is only required once.
The other setting allows user pages of this MediaWiki to serve as OpenID identities on another OpenID-aware site:
require( "$IP/extensions/OpenID/OpenID.php" ); $wgOpenIDLoginOnly = true; $wgOpenIDAllowServingOpenIDUserAccounts = true;
// Implicit group for all visitors $wgGroupPermissions['*' ]['createaccount'] = false; $wgGroupPermissions['*' ]['read'] = true; $wgGroupPermissions['*' ]['edit'] = false; $wgGroupPermissions['*' ]['createpage'] = false; $wgGroupPermissions['*' ]['createtalk'] = false;
Example 2:
The following setting configures a MediaWiki so that anyone can create an account and can log in with either their userid/password - or with their OpenID identity.
During first-time log-ins with OpenID, users see only a box where they can enter their wanted username for the account creation, or to be associated with the OpenID identity when they enter a username of an existing account (the corresponding account password must be then entered once).
Subsequent log-ins can be then done with either the userid/password method or simply with the OpenID, which does not require any further password sub- mission to the MediaWiki.
require_once("$IP/extensions/OpenID/OpenID.php"); /**
- when logging on:
- show only the option to enter and to allow a manually chosen username
- do not propose new account names from their OpenID SREG data (such as fullname or nickname on their OpenID server)
- do not propose an automatically generated username */
$wgOpenIDAllowManualUsername = true; $wgOpenIDProposeUsernameFromSREG = false; $wgOpenIDAllowAutomaticUsername = false;
OpenID services
These are some of the OpenID services I tested this extension with; all have free signup for identities if you want to test, too.
- http://www.myopenid.com/ -- uses Simple Registration Extension
- http://getopenid.com/
- http://www.typekey.com/
- http://www.claimid.com/
- http://pip.verisignlabs.com/
- http://certifi.ca/
Bugs
List of known bugs is
http://preview.tinyurl.com/openid-bugs
Bugs and important observations should be filed as Product: MediaWiki extensions, Component: OpenID in bugzilla via
http://preview.tinyurl.com/openid-filebug
CHANGES
see file CHANGES