Extension:GoogleLogin

From MediaWiki.org
Jump to: navigation, search

Other languages:
English
MediaWiki extensions manualManual:Extensions
Crystal Clear action run.png
GoogleLogin

Release status:Extension status beta

Googlelogin.PNG
ImplementationTemplate:Extension#type User identity, Special page
DescriptionTemplate:Extension#description Provides login with your Google account.
Author(s)Template:Extension#username Florian Schmidt (Florianschmidtwelzowtalk)
Latest versionTemplate:Extension#version see the version lifecycle
MediaWikiTemplate:Extension#mediawiki 1.28+
PHPTemplate:Extension#php 5.5+
Database changesTemplate:Extension#needs-updatephp Yes
LicenseTemplate:Extension#license MIT License
Download
Extension:GoogleLogin/Changelog
Hooks usedTemplate:Extension#hook
UserLogoutCompleteManual:Hooks/UserLogoutComplete
LoadExtensionSchemaUpdatesManual:Hooks/LoadExtensionSchemaUpdates

Translate the GoogleLogin extension if it is available at translatewiki.net

Check usage and version matrix.

IssuesPhabricator

Open tasks · Report a bug

The GoogleLogin extension allows wiki users to login with their Google account. The extension uses the Google API to request basic profile information from Google (such as the account ID, the full name and the e-mail address).

Requirements[edit]

To use this extension you need at least:

  • MediaWiki 1.27+
  • MySQL (no PostgreSQL or SQLite support for now!)
  • PHP 5.5+
  • Google Developer Access
  • Google+ API access
  • API Credentials for Webapplication (Client ID and Client Secret)
  • Able to run composer update

Installation[edit]

  • Download and place the file(s) in a directory called GoogleLogin in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
    require_once "$IP/extensions/GoogleLogin/GoogleLogin.php";
    
  • Run the update script which will automatically create the necessary database tables that this extension needs.
  • Configure the required parameters
  • Make sure ./wiki/extensions/GoogleLogin/cache is writeable for the Webserver's user
  • YesY Done - Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration[edit]

Note Note: Ensure that all settings reside under the "require_once" directive added for this plugin. Otherwise any custom settings will be overwritten by the default settings, as referenced here: Topic:Si6ituq6hmxb07xm

The extension provides two configuration variables to set the Client ID and Client Secret (you get this pair in the Google Developer Console, remove "<" and ">").

$wgGLSecret = '<your-client-secret>';
$wgGLAppId = '<your-client-id>';

Additional Configuration parameter[edit]

Configuration variable since version Default value Description
$wgGLAllowedDomains[gerrit 1] v0.1.1 '' An array of mail domains, which are allowed to use with GoogleLogin, e.g. array( 'example.com' );. Default: all domains are allowed.
$wgGLAllowedDomainsDB[gerrit 2] v0.4.0 false If set to true, GoogleLogin uses the database to check, if an e-mail domain of the primary e-mail-address of a Google account is allowed to login.
$wgGLAllowedDomainsStrict[gerrit 1] v0.1.1 false Only observed, if $wgGLAllowedDomains is an array. If set to true, the email domain will be checked completely against the allowed domains (instead of only the TLD), e.g.:

test.example.com isn't allowed if $wgGLAllowedDomainsStrict is true and example.com is an allowed domain.
test.example.com is allowed if $wgGLAllowedDomainsStrict is false and example.com is an allowed domain.

$wgGLAPIKey[gerrit 3] v0.2.1 '' Key for public API access. Used only for admin actions to check, if the user has a Google Plus profile or not.

Settings in Google Developer Console[edit]

To use this extension you need a Google developer account and access to the developer console. This is a simple (a very simple!) step-by-step guide (use Step 1 of the official step-by-step example with these settings):

  1. Open Google developer console
  2. Read and accept the terms of service
  3. Create your first project
  4. Go to APIS & AUTH
  5. Go to APIs and enable Google+ API (read and accept the terms)
  6. Go to Credentials
  7. In Section OAuth click Create new Client ID
  8. Select as Web application as APPLICATION TYPE, as Authorized JavaScript origins type in your domain name (no wildcards and directories allowed!)
  9. Type in your Authorized redirect URI like this example:
    If your domain is example.com and you have installed MediaWiki in Root of your domain, the redirect URI is as follows: http://example.com/index.php/Special:GoogleLoginReturn
  10. Click create and copy the Client ID and Client Secret to the configuration variables in LocalSettings.php

"Special:GoogleLoginReturn" or (in german for example) "Spezial:GoogleLoginReturn"[edit]

The allowed redirect URI in Google developer console must be in the content language. So, if your wiki has german as the content language, then use Spezial:GoogleLoginReturn. If you used the wrong language, all authentication requests will fail with the error code redirect uri mismatch.

Debug[edit]

Normally, you can see the error message on all generic error pages. Sometimes there are Internal Errors, called Exceptions. In this case, please add $wgShowExceptionDetails with value true in LocalSettings.php to see the complete Exception message. For a support request, please provide always the lines of the Exception.

Use on a private wiki[edit]

If you have set your Wiki to private with

$wgGroupPermissions['*']['read'] = false;

you have to whitelist the "Special:GoogleLoginReturn" page, so that anonymous users can access the callback URL after being redirected from the authentication provider. You can do this by adding the following line to your LocalSettings.php:

$wgWhitelistRead = array( 'Special:GoogleLoginReturn' );

Administrate allowed domains on-wiki[edit]

The user interface to manage the list of allowed domains.

GoogleLogin provides a feature to restrict the login with Google to specific E-Mail address domains (such as gmail.com, googlemail.com or every other (own) domain). This feature is especially interesting for companies, who use their own domain names with Google Apps. The list of domains, which are allowed to login with Google, are managed in an array in the LocalSettings.php (the $wgGLAllowedDomains configuration option). Since version 0.4.0, GoogleLogin also provides a way to manage the list of allowed domains on the wiki itself. The allowed domains are saved in the database when this feature is enabled and can be change (remove/add) through a graphical user interface (a special page) or through the MediaWiki API.

Note: The list of allowed domains can not be managed in LocalSettings.php anymore, once the administration of the domains in the database is enabled.

To enable the feature to manage the allowed domains in the database, just set the $wgGLAllowedDomainsDB configuration variable to true in your LocalSettings.php. You also want to assign the new managegooglelogindomains user right to one group you're a member of (please keep in mind, that all users with this user right are allowed to change the list of allowed domains, so consider to add this right to an administrator-level group only!). An example configuration could look like:

$wgGLSecret = 'your-secret';
$wgGLAppId = 'your-app-id';
$wgGLAllowedDomainsDB = true;
$wgGroupPermissions['sysop']['managegooglelogindomains'] = true;

You now need to run the update.php script again, so that the necessary database changes are applied to your database. After the update process is completed, you can navigate to the special page Special:GoogleLoginAllowedDomains on your wiki. You'll get a page where you can add new domains, which are allowed to login with their Google account and you can remove them, once they was added.


Upgrade from 0.3.1 or older[edit]

With version 0.4.0, GoogleLogin implements a PrimaryAuthenticationProvider for the new authentication system of MediaWiki (called AuthManager). This makes it easier for the development of GoogleLogin and you can configure a lot more things in a standard way. However, upgrading from an older version of GoogleLogin may take some more time and effort as with upgrades in the past, as some configuration options in GoogleLogin were removed in the update (and mostly replaced by configurations of AuthManager). In the following sections you'll find some instructions about how you can configure your wiki to achieve the same goal as with the removed configuration options.

$wgGLShowCreateReason[edit]

Removed without replacement.

$wgGLShowKeepLogin[edit]

Removed without replacement (the Keep me logged in checkbox now applies to all authentication methods, including GoogleLogin).

$wgGLAllowAccountCreation[edit]

The whole account creation and login process is managed and covered by AuthManager. This means, if you don't want, that your users can create wiki accounts, you should disable it in your LocalSettings.php:

$wgGroupPermissions['*']['createaccount'] = false;

Currently, that would mean, that no one can create an account anymore (including GoogleLogin). There's also task T138678, which tracks the process of a login -> signup -> login workflow, where an account creation with a link provider (such as GoogleLogin) with a disabled account creation should be covered.

$wgGLReplaceMWLogin[edit]

You should simply remove any other authentication provider in your LocalSettings.php:

$wgAuthManagerAutoConfig['primaryauth'] = [];

GoogleLogin will automatically setup itself for AuthManager, so you don't need to do any further steps.

$wgGLForceKeepLogin[edit]

Obsolete, see #$wgGLShowKeepLogin.

$wgGLAPIKey[edit]

This configuration option still exists, but it's now used for more than just the Special:ManageGoogleLogin special page. It's now used to get the name of a user on Special:RemoveCredentials to make it easier to the user to identify the correct Google account (instead of just showing the Google ID). If the key isn't correct or isn't supplied, GoogleLogin will show the Google ID only. For a good user experience, it's highly suggested to supply this api key now.

$wgGLShowRight[edit]

Removed without replacement as the login and signup forms are now fully handled by AuthManager. If you still want to show the Login with Google at the right side of the login form, you should create a new extension (and probably share it with us ;)) which hooks into the form generation and accomplishes the form manipulation.

$wgGLNeedsConfirmEmail[edit]

Removed without replacement.

Google API PHP Client[edit]

This Extension uses the Google API PHP Client (included in versions before 0.2.1), distributed under the Apache 2.0 License. The Client can be downloaded from GitHub.

Version lifecycle[edit]

In the following table you'll find versions of the GoogleLogin extension, the corresponding MediaWiki version for which the GoogleLogin version was built for and if it's still supported (and until when) or not. Mostly the support of a version is nearly the same as the lifecycle of the corresponding MediaWiki version.

Version Corresponding MediaWiki version Status Release End-of-life
0.4.x 1.28.xMediaWiki 1.28 current version 2016-06-18 November 2017(2017-11)
0.4.0 1.27.xMediaWiki 1.27#Release schedule (LTS) current version 2016-07-20 June 2019(2019-06)
0.3.1 1.27.xMediaWiki 1.27#Release schedule (LTS) obsolete (replaced by 0.4.0) 2016-06-10 2017-07-20
0.3.0 1.26.xMediaWiki 1.26#Release schedule legacy version n/a November 2016(2016-11)
0.2.1 1.25.xMediaWiki 1.25#Release schedule discountinued n/a 2016-06-18
0.2.0 1.24.xMediaWiki 1.24#Release schedule discountinued n/a 2016-06-18
0.1.3 1.23.xMediaWiki 1.23#Release schedule (LTS) discountinued n/a 2016-06-18

Versions included in the above table that are marked as discontinued will not receive any fixes. They may contain critical security vulnerabilities and other major bugs, including the threat of possible data loss and/or corruption. The developer has also issued a strong recommendation that only versions listed above as current version or at least legacy version should be used in a production environment. Legacy versions will most likely get fixes for reported bugs that harms the core functionality of the extension, while current versions get fixes for most of the reported bugs (even if they're not part of the core functionality). New features will most likely be part of new versions. Backporting features to older versions of GoogleLogin is up to the developer(s).

References[edit]

Gerrit Code review[edit]