MediaWiki OpenID extension
version 0.8.2
12 Mar 2008
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. We
have almost 20 wikis that work together for Wikitravel, and users
can login to different Wikitravel wikis with their home wiki
account.
* 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.x 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
== Author ==
Evan Prodromou <evan@vinismo.com>
Patches for YADIS support and FileStore storage by Jonathan Daugherty
<cygnus@janrain.com>.
== Pre-requisites ==
This software has been tested in production with MediaWiki 1.11.x. It
may or may not work with earlier or later versions, but I'm interested
in making later versions work, and I'd be happy to make minor changes
to make older, unsupported versions work too.
The software depends on the OpenIDEnabled.com PHP library for OpenID,
which in turn depends on the OpenIDEnabled.com PHP library for YADIS.
At the time of this writing, info on installing these libraries was
available here:
http://www.openidenabled.com/php-openid/
The last version tested with is 2.0.1; '''versions below 2.0 will not
work'''. If you must use version 1.x of the openidenabled.com library,
you can use the unsupported version 0.7.0 or below of this extension.
There are also some required PHP extensions; see the OpenIDEnabled
documentation for details. This software has been tested with the gmp
and curl PHP extensions installed, and it's recommended that you
install them, too.
Note that some versions of MediaWiki overwrite the PHP library path in
LocalSettings.php. 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 ==
To install, copy all the files in the archive you downloaded to the
OpenID subdirectory of the extensions subdirectory of your MediaWiki
installation. Note that the software depends on having its code all in
the "OpenID" sub-directory; naming it "OpenID-Test" or "newextension1"
or whatever won't work.
You must create a table in your MediaWiki database to hold the OpenID
URL mappings. The openid_table.sql script in this directory should do
the trick. Typically you do this using the mysql command-line client,
like so:
mysql -h yourdbhost -u youradminuser -p yourwikidb < openid_table.sql
Version 0.3 and below of this extension used a different database
structure that was pretty inefficient. If you installed this extension
before, you should copy the optionToTable.php script to your MediaWiki
"maintenance" directory and run it from the command line. This will
copy the OpenID mappings from the user table to the new table (but it
doesn't erase the old data... just in case).
In your MediaWiki LocalSettings.php, add the following line some place
towards the bottom of the file:
require_once("$IP/extensions/OpenID/OpenID.setup.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 ==
'''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 2.x version of the openidenabled.com PHP OpenID library.
* Check that your consumer and server stores are correct. I 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
.setup.php file.
* 'openidlogininstructions' is now wikitext, not HTML. If you've
customized it, you may need to re-customize it. Also, it's now
shown '''below''' the login box, so if you say ''the box below'',
you may want to change that to ''the box above''.
* 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. So, for
example, the author's identity URL is:
http://wikitravel.org/en/User:Evan
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 ==
The administrator can configure these variables in the
LocalSettings.php file. Please read carefully.
* $wgTrustRoot -- 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 "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/#".
* $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. Only valid value is "file"; "memc" no long valid.
* $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.
* $wgHideOpenIDLoginLink -- 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 -- Url of the OpenID login logo. Defaults to
'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'.
== Skins ==
If you are customizing a skin, and you want to show the OpenID
identity for a user (say, on their user page), use the function
OpenIDGetUserUrl($user). It takes a User object (not a name or an id!)
and returns the user's OpenID identity if it exists, or null if it
doesn't.
== Translation ==
The user interface strings for this extension are configurable through
the same Special:Allmessages page as MediaWiki itself. They all start
with "openid", and they're no more or less cryptic than MediaWiki's.
You can look at OpenID.i18n.php for some details.
== 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 ==
Bugs or feature requests can be sent to the author at
evan@vinismo.com. The TODO file in this distribution has stuff I
think needs to be todone; + marks show things I've already done, and -
shows things that are yet to be done.
The big changes for the future:
* Configure some stuff through Special:Preferences or a dedicated
control panel
* Auto-login if you've logged in before with an OpenID, and are logged
into that account now
