Download the PHP package centertap/discourse-sso-consumer without Composer

On this page you can find all versions of the php package centertap/discourse-sso-consumer. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package discourse-sso-consumer

Discourse SSO Consumer for MediaWiki

DiscourseSsoConsumer is a MediaWiki extension which allows a MediaWiki site to authenticate users via a Discourse discussion forum, using the forum's Single Sign-On (SSO) provider functionality. This extension aims to facilitate seamless integration between a wiki and a discussion forum.

The DiscourseSsoConsumer extension is itself a plugin for MediaWiki's PluggableAuth extension.

Notable features of this DiscourseSsoConsumer are:


Brought to you by...

This extension is developed by the Center for Transparent Analysis and Policy, a 501(c)(3) non-profit organization. If this extension is useful for your wiki, consider making a donation to support CTAP. You can be a provider for Discourse SSO Consumer!



Prerequisites

To make use of DiscourseSsoConsumer, you will need:


Installation

The recommended installation method is to use composer. This will automatically install any dependencies, e.g., PluggableAuth.

You can install this extension by hand (e.g., git clone this repository into your site's extensions/ directory), but then you will have to manage its dependencies by hand as well.


Configuring Discourse

There are three independent aspects of Discourse which you may need to configure, depending on what DiscourseSsoConsumer functionality you want to use.

DiscourseConnect Provider for SSO Authentication

If you want MediaWiki to actually authenticate users via Discourse, you will need to enable the "DiscourseConnect Provider" on your Discourse server functionality and set up a shared-key.

Go to Admin -> Settings -> Login and:

Discourse API Key for Global Logout

If you want to allow MediaWiki to trigger global logouts on Discourse (i.e., log a user out of all devices), then you will also need to create an API key on Discourse for its log_out API.

Go to Admin -> API and:

Make sure your MediaWiki server can connect directly to your Discourse server. The log_out API request is made directly by the MediaWiki server to the Discourse server (unlike SSO requests for logging in, which are redirected through the user's browser).

Webhook for User Events

If you want MediaWiki to get updated user information in real-time (not just when a user logs in), you can configure a webhook on Discourse, telling it to send user events to MediaWiki.

First:

Next, go to Admin -> API on Discourse and:

Make sure your Discourse server can connect directly to your MediaWiki server. The webhook requests are made directly by the Discourse server to the MediaWiki server (unlike SSO requests for logging in, which are redirected through the user's browser).


Configuring MediaWiki

Setting up DiscourseSsoConsumer involves setting its configuration parameters, as well as parameters for PluggableAuth and MediaWiki in general.

Configure PluggableAuth and MediaWiki in General

At a minimum, you will need to tell PluggableAuth, that it should use DiscourseSsoConsumer, by providing an entry in $wgPluggableAuth_Config:

Replace MY-BUTTON-LABEL with whatever string you would like to see in the wiki's login button. (Even if $wgPluggableAuth_EnableLocalLogin is disabled, the wiki login page may still appear in certain situations. So, it is worth choosing a sensible value for this.)

You will probably want to tune the configuration of PluggableAuth, in particular:

As mentioned in the PluggableAuth documentation, you will likely want to configure the MediaWiki permissions to allow extensions to automatically create new wiki accounts for authenticated users. Add something like this to LocalSettings.php:

You will likely want to tune these MediaWiki parameters as well:

See Logging-in Automatically for more details on these last three.

Configure DiscourseSsoConsumer using a hook function ⚠️

Instead of directly setting a global variable in LocalSettings.php, the preferred way to configure DiscourseSsoConsumer parameters is by using the DiscourseSsoConsumer_Configure hook, as in the example below:

Your hook function will be called with the array $config pre-populated with the built-in defaults of the extension, which you may then modify as you see fit. It is recommended to modify this array, instead of completely replacing it, in order to benefit from any new default parameters added to the extension in future versions.

Be sure to include the ampersand & in the function's signature: function ( array &$config )! ⚠️

Why use a hook function?
MediaWiki attempts to merge default values into an extension's config variables after executing LocalSettings.php. The first problem with this is that there is no way to access the default values when LocalSettings.php is executed. The second problem is that none of the available, hard-coded "merge strategies" work for our nested config structure. Using a hook solves both of these problems; within the hook function, the admin gets access to the default parameters and can modify those defaults and build on top of them however they want.

Catalog of Configuration Parameters

Technically, the DiscourseSsoConsumer extension has only a single configuration parameter: $wgDiscourseSsoConsumer_Config. This is an array, though, and the entire configuration goes into that single array. By setting the configuration via a hook function (see above), one never needs to care about the actual variable name of the array.

The configuration is hierarchical, expressed via nested arrays. Hence, some values are at the top-level --- $config['key'] --- and some are deeper --- $config['key1']['key2'].

Here is a summary of the available parameters; details follow below.

parameter default value
['DiscourseUrl'] no default, always required
['Sso']['Enable'] false
['Sso']['ProviderEndpoint'] '/session/sso_provider'
['Sso']['SharedSecret'] null (no default)
['Sso']['EnableAutoRelogin'] false
['Sso']['EnableSeamlessLogin'] false
['User']['LinkExistingBy'] []
['User']['ExposeName'] false
['User']['ExposeEmail'] false
['User']['GroupMaps'] null (optional, no default)
['DiscourseApi']['Username'] system
['DiscourseApi']['Key'] null (no default)
['DiscourseApi']['LogoutEndpoint'] '/admin/users/{id}/log_out.json'
['DiscourseApi']['EnableLogout'] false
['Webhook']['Enable'] false
['Webhook']['SharedSecret'] null (no default)
['Webhook']['AllowedIpList'] []
['Webhook']['IgnoredEvents'] ['user_created']
['Logout']['OfferGlobalOptionToUser'] false
['Logout']['ForwardToDiscourse'] false
['Logout']['HandleEventFromDiscourse'] false

Here are the details:


Tips, Hints, More Details

Logging-out

Logging out was a bit of an afterthought in the "DiscourseConnect" design, so a complete single sign-out integration of MediaWiki with Discourse is not possible yet. But, we can get about 3/4's of the way there.

There are two scopes of logout:

There are two possible directions of logout flow:

There are four combinations, of which we can accomplish three:

direction local via... global via...
MediaWiki → Discourse ...SSO logout request ...Discourse API request
Discourse → MediaWiki ...¯\_(ツ)_/¯ ...Webhook event

That one thing that we cannot do is to have a local logout from Discourse (user clicks Discourse logout button) cause a local logout from MediaWiki (same browser is logged out from MediaWiki).

['Logout']['HandleEventFromDiscourse'] controls whether or not a global logout will be invoked in response to a user_logged_out event from Discourse. If this is enabled, then you must also enable ['Webhook']['Enable'] and, of course, set up the webhook with Discourse. (See Webhook for User Events.)

['Logout']['ForwardToDiscourse'] controls whether or not any logout events on MediaWiki are forwarded to Discourse. If this is enabled, then you must also enable ['Sso']['Enable'] and, of course, set up SSO with Discourse. (See DiscourseConnect Provider for SSO Authentication.) You may also need to enable ['DiscourseApi']['EnableLogout']; keep reading.

['Logout']['OfferGlobalOptionToUser'] controls whether or not the user is given the option to perform a global logout. If this is enabled and ['Logout']['ForwardToDiscourse'] is enabled, then you must also enable ['DiscourseApi']['EnableLogout'], because that is the mechanism that will be used for the global logout. (See Discourse API Key for Global Logout, as well.)

Cautions about Discourse user_logged_out events

Discourse emits a global user_logged_out webhook event in these situations:

However, even though the following conditions do cause a global logout on Discourse, it does not emit user_logged_out events when:

This inconsistency is probably a bug in Discourse.

MediaWiki Session Lifetimes

By default, Discourse will try to keep users logged-in forever. (See its persistent sessions and maximum session age settings, which default to enabled and 60 days, respectively.)

MediaWiki does have a "Keep me logged in" option. However:

  1. If a user does choose to log out of Discourse, there is no good way to automatically log the user out of MediaWiki also.
  2. If $wgPluggableAuth_EnableLocalLogin is disabled, users will usually never see the page with the "Keep me logged in" checkbox. But, under certain error conditions, they will see that page, and seeing that checkbox will likely be confusing.

So, you may want to disable "Keep me logged in" on MediaWiki entirely. On MW 1.35, this can be accomplished by setting $wgExtendedLoginCookieExpiration to zero.

If this is disabled, then all inactive MediaWiki sessions will expire after the timeout set by $wgObjectCacheSessionExpiry, which defaults to 1 hour.

DiscourseSsoConsumer can be configured to conveniently automatically reauthenticate expired sessions; read about AutoRelogin below.

Logging-in Automatically

There are three "automatic login" modes available with DiscourseSsoConsumer. They affect what happens when a user navigates to a page on the wiki.

PluggableAuth (PA) AutoLogin is intended to be used on wikis which only allow logged-in users. Since PA's AutoLogin does not permit anonymous page visits at all, there is no reason to enable the other modes alongside it. (E.g., if a user's session expires, PA's AutoLogin will by itself ensure they become authenticated again on the next visit.) So, if you do enable PA's AutoLogin, then do not enable either of the DiscourseSsoConsumer modes.

DiscourseSsoConsumer's AutoRelogin is intended to try to keep an already logged-in user logged-in in case their session expires, e.g., due to timing-out from being idle. When a previously logged-in user visits the wiki, AutoRelogin mode will probe Discourse (via browser redirects) for the user's authentication status. If they are still logged-in to Discourse, they will get a new wiki session. If not, they will remain anonymous, and AutoRelogin will not try again --- if the user wants to, they can hit the login button and be redirected to Discourse to explicitly login.

The purpose of AutoRelogin is to provide a user experience more similar to Discourse itself, i.e., as long as the user is logged-in to Discourse, they will stay logged-in to MediaWiki. Without this enabled, the user will be silently logged out of MediaWiki after a period of inactivity when their current session times out. If you enable this option, you will probably want to disable $wgPluggableAuth_EnableLocalLogin, otherwise users will have to see the Userlogin interstitial page, and click through to Discourse SSO, every time a relogin occurs.

DiscourseSsoConsumer's SeamlessLogin is intended to allow a user, already logged-in to Discourse, to navigate to MediaWiki and be logged-in as soon as they get there. In other words, it tries to provide a seamless transition from Discourse to MediaWiki. SeamlessLogin only affects a user's very first visit to the wiki (per device/browser), however. If they are not already logged-in to Discourse on that first visit, they will need to log-in to the wiki explicitly.

It never makes sense to use PA's AutoLogin with either of the DiscourseSsoConsumer modes, but it can certainly make sense to use the DiscourseSsoConsumer together:

SeamlessLogin AutoRelogin rationale
on on MW sessions should track Discourse sessions
off on Require explicit MW login, but then try to stay logged in
on off ¯\_(ツ)_/¯
off off MW sessions managed independently of Discourse

Webhook, User Records, and the Extension API

When webhook processing is enabled and a user event is received, then DiscourseSsoConsumer will receive a fairly complete record of user data from Discourse. DiscourseSsoConsumer will store this record in the MediaWiki database, along with information about the event itself (timestamp, event type, event id).

This data is stored verbatim as received from Discourse. The mappings defined by the ['User'] configuration are not applied here.

Other extensions/functions can fetch and use this data by using a public API provided by DiscourseSsoConsumer. Look for ApiV1/Connector.php in the source code for more details.

For example:

For a description of the Discourse user data itself, your best bet is to set up a webhook and use Discourse's webhook log to examine the JSON contents of some events. (Discourse conveniently logs the Request and Response for each event of every webhook.)


Release Notes

See RELEASE-NOTES.md.


Known Bugs/Issues


License

This work is licensed under GPL 3.0 (or any later version).

SPDX-License-Identifier: GPL-3.0-or-later

Copyright 2024 Matt Marjanovic


All versions of discourse-sso-consumer with dependencies

PHP Build Version
Package Version
Requires php Version >=7.4
ext-curl Version *
ext-json Version *
composer/installers Version ^1.0.1
mediawiki/pluggable-auth Version ~6.3
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package centertap/discourse-sso-consumer contains the following files

Loading the files please wait ....