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. We have 16 wikis that work together for Wikitravel, and users can login to different Wikitravel wikis with their home wiki account.
 * Single-signon across the Internet. OpenID isn't that well known yet, but theoretically someone could login to their OpenID identity server in the morning and not have to login to another site  for the rest of the day.

This is an early version of the extension and it's almost sure to have bugs. (Don't despair, though: this is running in production on Wikitravel, a fairly big MW installation.) See the BUGS section below for info on how to report problems.

Note: version 0.6.1 fixes a bug with databases that use a table prefix.

License
Copyright 2006,2007 Internet Brands (http://www.internetbrands.com/)

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 

Patches for YADIS support and FileStore storage by Jonathan Daugherty .

Pre-requisites
This software was tested with MediaWiki 1.6.x - 1.8.x (which is what Wikitravel was running at the time.) It may or may not work with earlier or later versions, but please test it.

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/openid/libraries/php
 * http://www.openidenabled.com/yadis/libraries/php

The OpenID should install the Yadis library as well, if you install it using Pear. There are also some required extensions; see the OpenIDEnabled documentation for details. This software has been tested with the gmp and curl extension installed, and it's recommended that you install them, too.

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. If you are using $wgSharedDB, file should be run on that database, not your default wiki database. 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 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.php");

If you installed the OpenID and Yadis PHP libraries via PEAR, your LocalSettings.php file may have a include_path override that prevents the PEAR libraries from being found. If your LocalSettings.php includes this line:

ini_set( "include_path", ".:$IP:$IP/includes:$IP/languages" );

Change it to this:

ini_set( "include_path", ".:/usr/share/php:/usr/share/pear:$IP:$IP/includes:$IP/languages" );

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).

Caching
The extension stores some semi-persistent data in the $wgMemc object. Where that object stores its data is configured by $wgMainCacheType in LocalSettings.php. Often this is set at installation time by the MediaWiki configuration script.

Typically for big wiki sites $wgMemc is a front-end for memcached (http://www.danga.com/memcached/), so $wgMainCacheType = CACHE_MEMCACHED.

For smaller sites, $wgMemc typically uses eAccelerator to do both data caching and bytecode caching. In this case, $wgMainCacheType = CACHE_ACCEL.

In case you don't have either installed, try $wgMainCacheType = CACHE_ANYTHING. There's usually some fallback mechanism to store this data for you.

If none of that works, you can use a filesystem-based storage; see the Configuration options below.

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.

If you've already got an account on the wiki, you can convert it to use OpenID to log in using the Special:OpenIDConvert page.

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. Valid values are "file" and "memc".  If the value for  one or both is "file", $wgOpenIDConsumerStorePath or $wgOpenIDServerStorePath must be set, respectively (see below).  If  either of these variables is set to an invalid value, an error page  will be displayed.


 * $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.
 * Question: If file is used, is it okay to share this with other MediaWiki installations on the same machine?

PHP Libraries
You will need the following PHP libraries configured for this functionality to work:
 * gmp or bcmath

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.

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://mylid.net/ -- OpenID, Yadis and LID support

Bugs and enhancements
Bugs or feature requests can be sent to the author at evan@wikitravel.org. 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:


 * Snazzier UI -- better HTML, sexier forms
 * Configure some stuff through Special:Preferences
 * Auto-login if you've logged in before with an OpenID, and are logged into that account now

Probably a ways down the line:


 * Allow delegation

MediaWiki sites supporting OpenID

 * http://wikitravel.org/ - each language version supports OpenID
 * http://wikevent.org/ - supports OpenID
 * http://www.wikihow.com
 * http://wiki.gregarius.net

Lessons learned during an installation
There were a couple of things I learned during my implementation of OpenID on a MediaWiki pear PEAR Auth Auth Services Yadis OpenID I had to move these directories to the following... pear PEAR Auth OpenID (directory) OpenID.php Services Yadis
 * I used the web front end for the Pear installer, which made some strange placements. The installer originally created the following file structure:


 * When you create the mySQL table (using the openid_table.sql file included with the MediaWiki-OpenID-0.6.1 release) be sure that the table that is created incorporates the prefix used for the rest of the wiki tables. Look in LocalSettings.php for $wgDBprefix - your table needs to start with that prefix.
 * My LocalSettings.php included the following settings:

require_once("$IP/extensions/OpenID/OpenID.php"); $wgTrustRoot = 'http://www.yourdomainhere.com/'; $wgOpenIDConsumerDenyByDefault = false; $wgOpenIDConsumerStoreType = 'file'; $wgOpenIDServerStoreType = 'file'; $wgOpenIDConsumerStorePath = '/tmp/openid-consumer'; $wgOpenIDServerStorePath = '/tmp/openid-server'; # To change the default login/create account screen with the OpenId prompt. $wgSpecialPages['Userlogin'] = array('SpecialPage', 'OpenIDLogin');


 * Another useful resource is http://dev.inames.net/wiki/How_to_Setup_an_I-Name-Enabled_Mediawiki