Extension:OpenID

The extension lets users log in to MediaWiki using their OpenID (http://www.openid.net/) which is a special URL instead of username/password combination. In this case, the MediaWiki acts as OpenID consumer. If expressly enabled, the extension can also allow the MediaWiki installation to act as OpenID provider, so that users with an account on that wiki can use their userpage url as OpenID to log in to other OpenID-aware web sites.

The extension is only useful if you've got a MediaWiki installation and can only be installed by the administrator of the site.

Typical uses of OpenID are:
 * 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 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 does not prove that they are 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 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 section below for info on how to report problems.

License
Copyright 2006-2008 Internet Brands (http://www.internetbrands.com/) Copyright 2008-2010 Evan Prodromou (http://evan.prodromou.name/)

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  Patches for YADIS support and FileStore storage by Jonathan Daugherty  Provider UI and some other changes by Sergey Chernyshev Changes, bugfixes for MediaWiki 1.16+ and PHP 5.3.5 and new parameters by Wikinaut

Pre-requisites
This software has been tested in production with MediaWiki 1.11.x and 1.16.1. 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 Extension:OpenID has been tested to work with php-openid 2.2.0.

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.

You probably need to install a few additional PHP extensions (if they are not part of yur standard PHP installation e.g. when running a server with OpenSUSE)
 * gmp
 * curl
 * mcrypt

Usually, these and possibly other missing extensions can be easily added one by one to your PHP installation by using YaST and installing the required php5-modules or recompiling PHP until the configure command finishes without errors..

See the OpenIDEnabled documentation for details. The php-openid README is helpful.

Installation issues for Debian

 * How to get GMP working on Debian
 * In Debian Lenny (5.0) there is a php5-gmp package ready for use. In Debian Etch (4.0) there is no php5-gmp package, but you can build your own by following these instructions (take care not to break your server, though) or downloading an unofficial i386 binary package (note that i386 is not amd64).
 * You may need to recompile php with the option: --with-gmp
 * Note that the php-openid library works ok with bcmath (available on etch) but this eats a lot of CPU, so unless your server is not used a lot you will want to install gmp.
 * If you don't know whether you have gmp or bcmath or none of these, then download the php-openid library, untar it, and run php ./examples/detect.php or use phpinfo.


 * How to get php-openid working on Debian
 * Debian Lenny (5.0) has a php-openid package. No such package exists for Debian etch (4.0).
 * Download php-openid from its source and read README and README.Debian

Installation
1. Make sure that you have all the pre-requisites. 2. Create the "OpenID" subdirectory $IP/extensions/OpenID

3. Copy all files from php-openid archive you downloaded to the "OpenID" subdirectory 4. You should now have all the extracted files from php-openid and OpenID (this extension) in the directory $IP/extensions/OpenID 5. In your MediaWiki $IP/LocalSettings.php, at the beginning, add the path , "$IP/extensions/OpenID/" to the "OpenID" subdirectory in the MediaWiki $path statement: 6. In your MediaWiki $IP/LocalSettings.php, at the bottom of the file add

7. Run update.php script in in your MediaWiki maintenance folder $IP/maintenance to create necessary tables in MediaWiki database. $IP/maintenance# php update.php

It should work out of the box, but you'll almost definitely want to set the trust root and access controls (see Configuration below).

Installation when using sqlite
sqlite3  <<EOF CREATE TABLE /*$wgDBprefix*/user_openid ( uoi_openid varchar(255) NOT NULL PRIMARY KEY,  uoi_user int(5) NOT NULL ) /*$wgDBTableOptions*/;

CREATE INDEX /*$wgDBprefix*/user_openid_user ON /*$wgDBprefix*/user_openid(uoi_user); EOF

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 (MediaWiki as OpenID consumer)
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 (MediaWiki as OpenID Server)
MediaWikis with the extension act as OpenID consumers (clients). They also can work as OpenID server, but only if the Wiki adminstrator has enabled this feature.

To log in to other OpenID-aware sites (consumer) with your MediaWiki account (OpenID server):
 * if, and only if you have a user account, and
 * if the user page exists (has some content)

then your OpenID identity URL is the full URL of your non-empty MediaWiki user page

http://www.server.org/wiki/index.php/User:MySelf

It does not have one of the following forms; these are not the OpenID identities you want http://www.server.org/wiki/index.php/Special:OpenIDXRDS/User:MySelf http://www.server.org/wiki/index.php/Special:OpenIDXRDS/MySelf http://www.server.org/wiki/index.php/Special:OpenIDServer/User:MySelf

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 (by cookie, or by session).

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.

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.


 * $wgOpenIDUseEmailAsNickname
 * defaults to false; when first-time logging-in with OpenID, use the part before the @ in any given e-mail address as the username if a nickname is not given by the OpenID. This works well with $wgOpenIDConsumerForce where all users have a unique e-mail address at the same domain.


 * $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


 * $wgOpenIDAllowManualUsername
 * defaults to true; when first-time logging in with OpenID, show option to enter and to allow a manually chosen username


 * $wgOpenIDAllowAutomaticUsername
 * defaults to true; when first-time logging in with OpenID, show option to choose and to allow an automatically generated username


 * $wgOpenIDConsumerStoreType
 * $wgOpenIDServerStoreType
 * strings denoting the type of storage to be used to store OpenID association data when acting as an OpenID relying party (consumer) and server, respectively. Only valid value is "file"; "memc" no long valid.


 * $wgOpenIDConsumerStorePath
 * $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
 * 'never' (default)
 * 'user' (let the users decide in their preferences)
 * 'always'


 * $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.


 * $wgOpenIDOnly
 * defaults to false. With this enabled, the default login peronal_urls will be removed. Additionally the options for linking your OpenID to an existing account will be removed from the registration form.


 * $wgOpenIDConsumerForce
 * Url of required OpenID provider. When this is set it bypasses the OpenID provider selection form.


 * $wgOpenIDAllowServingOpenIDUserAccounts
 * defaults to false. With this enabled, it allows to use User pages as OpenIDs even if user is using OpenID already. Users can use their user page URLs of this site A as OpenID on another site B even if user is using OpenID on A already. Some users might want to do that for vanity purposes or whatever. If false, prevent serving OpenID accounts (this was an TODO list item)

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 servers (where you can register an OpenID)
These are some OpenID services the extension is known to be compatible, all have free signup for identities.
 * http://www.myopenid.com/ -- uses Simple Registration Extension
 * http://getopenid.com/
 * http://www.typekey.com/
 * http://www.claimid.com/
 * http://pip.verisignlabs.com/
 * http://openid.35.com/
 * http://certifi.ca/

Bugs, common misunderstandings and pitfalls when testing and debugging
Please submit bugs into Bugzilla under OpenID extension component (full list of bugs).

tinyurl shortcut links are:
 * openid-bugs
 * openid-filebug
 * openid-codereview


 * one MediaWiki acting as OpenID server Bob does not work with another or same MediaWiki acting as OpenID consumer Alice on the same server. Advice for the moment: use two different servers while playing with the extension
 * when you want to log in to your OpenID-consuming MediaWiki Alice as user X:
 * make sure that your are not logged in to the OpenID identity server Bob as another user Z ; otherwise you will see an error, which is intended.
 * I recommend you log out every personality you may have on server Bob while testing the extension
 * clear your browser chache of all Bob-related cookies, and session cookie.
 * The OpenID authentication process flow will redirect you from Alice to Bob. Bob will then prompt you to log in and hopefully everything works.