MediaWiki OpenID extension README.OpenID-mediawiki-extension file
version 0.947-beta 20120205
Homepage and manual http://www.mediawiki.org/wiki/Extension:OpenID

Please check OpenID.setup.php for the current program version number

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 ==

This software has been tested with MediaWiki 1.19 rev. 88135

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/

Unfortunately, tt requires patches when running with PHP 5.3.x and later.
The download from the above Url and the patch will be automatically done
when you run "make" (see next section).

The version tested with is 2.2.2; '''versions below 2.0 will not work'''.

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.

/* FIXME: */
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 ==

The repository downloader can be accessed by:

   http://www.mediawiki.org/wiki/Special:ExtensionDistributor/OpenID

To install the MediaWiki extension, download the MediaWiki extension tarball
to your extensions subdirectory $IP/extensions of your MediaWiki installation,
$IP being the directory of your LocalSettings.php, and untar the package to
the subdirectory $IP/extensions/OpenID.

The following examples shows the step for extension revision r######:

   cd $IP/extensions
   wget http://upload.wikimedia.org/ext-dist/OpenID-trunk-r#####.tar.gz
   tar -xzf http://upload.wikimedia.org/ext-dist/OpenID-trunk-r#####.tar.gz

Remark:

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.

A makefile is included which now automates the second step, the installation of
the php-openid library (MediaWiki OpenID depends on the OpenIDEnabled.com PHP
library for OpenID, which in turn depends on the OpenIDEnabled.com PHP library
for YADIS).

Download and patch of openid library:

	cd $IP/extensions/OpenID
	make

The makefile downloads the openid-php library from http://www.openidenabled.com/php-openid/
and applies a patch to avoid PHP errors because Call-time pass-by-reference is deprecated
since PHP 5.3.x see https://github.com/openid/php-openid/issues#issue/8  and
the patch and fork of user kost https://github.com/openid/php-openid/pull/44/files
    
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" );

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 ==

'''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/#".

* $wgOpenIDConsumerForce -- a single provider which will always be used,
  bypassing the selection dialog and manual entry.  Useful for team wikis
  using a provider such as Google Apps for Your Domain.
  
* $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.

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

* $wgOpenIDOnly -- defaults to false. With this enabled, users can
  ''only'' log in with OpenID.

* $wgOpenIDClientOnly -- 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" );
$wgOpenIDOnly = 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;

== Translation ==

The user interface strings for this extension are configurable and all start
with "openid". See OpenID.i18n.php for details. Translation is done via
translatewiki.net, as usual.

== 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

== TODO ==

* Code review http://preview.tinyurl.com/openid-codereview
* Move TODO file and things below into Bugzilla

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

== CHANGES ==
* 0.947 using jQuery closure for redirect
* 0.946 fixed the problem of broken automatic redirect to OpenID provider login
        replaced hookEvent() by	jQuery( document ).ready( submitOpenIDForm )
* 0.945 improved Makefile: added the SHA1 checksum of php-openid library.tar.gz
* 0.944 improved the Makefile by adding a test if "patch" (program) exists
        some users reported that this is not standard in all distrubtions
* 0.942 code cosmetic db schema updater
* 0.940 changed database schema updater; tested for MySQL
* 0.939 function name changes
* 0.938 list uoi_user_registration timestamp if present in openid-preference tab
* 0.937 added uoi_user_registration timestamp field (bug30623)
* 0.934 fixes
  bug 29543 After logging in with OpenID, user page link in the personal toolbar
  pt portlet) still has the User:IP link (needs refresh to link to
  User:Username)
* [http://svn.wikimedia.org/viewvc/mediawiki/tags/extensions/OpenID/REL_0_8_4/ 0.8.4] (April 16, 2009) - Added provider buttons to the OpenID login page with optional icons ($wgOpenIDShowProviderIcons)
* [http://svn.wikimedia.org/viewvc/mediawiki/tags/extensions/OpenID/REL_0_8_4_1/ 0.8.4.1] (April 16, 2009) - Post-release fix to broken icon on user's page.
* 0.9.1 fixes for PHP > 5.3.x; fixed bugs
  bug 27419 OpenID extension: disallow new account creation for those users without "createaccount" permission
  bug 27581 3 new OpenID login page parameters: $wgOpenIDAllowManualUsername, AllowAutomaticUsername, ProposeUsernameFromSREG
  bug 18635 Allow to use User pages as OpenIDs even if user is using OpenID already
