MediaWiki OAuth Library Documentation

mwoauth is an open licensed (MIT) library designed to provide a simple means to performing an OAuth handshake with a MediaWiki installation with the OAuth Extension installed.

Compatible with python 2.7 and 3.x

Install with pip: pip install mwoauth

There are two ways to use this library:

  • Handshaker – an object oriented handshake manager
  • A set of stateless functions: intitiate(), complete() and identify().

Both of strategies make use of the same set of tokens (ConsumerToken, RequestToken and AccessToken) and are totally inter-operable (if you like to mixing things up).

There’s also a flask.Blueprint handler. See mwoauth.flask.

The OAuth Handshaker

A client for managing an OAuth handshake with MediaWiki.

Example:
from mwoauth import ConsumerToken, Handshaker
from six.moves import input # For compatibility between python 2 and 3

# Consruct a "consumer" from the key/secret provided by MediaWiki
import config
consumer_token = ConsumerToken(
    config.consumer_key, config.consumer_secret)

# Construct handshaker with wiki URI and consumer
handshaker = Handshaker(
    "https://en.wikipedia.org/w/index.php", consumer_token)

# Step 1: Initialize -- ask MediaWiki for a temporary key/secret for
# user
redirect, request_token = handshaker.initiate()

# Step 2: Authorize -- send user to MediaWiki to confirm authorization
print("Point your browser to: %s" % redirect) #
response_qs = input("Response query string: ")

# Step 3: Complete -- obtain authorized key/secret for "resource owner"
access_token = handshaker.complete(request_token, response_qs)
print(str(access_token))

# Step 4: Identify -- (optional) get identifying information about the
# user
identity = handshaker.identify(access_token)
print("Identified as {username}.".format(**identity))
class mwoauth.Handshaker(mw_uri, consumer_token, callback='oob', user_agent=None)[source]
Parameters:
mw_uri
: str

The base URI of the wiki (provider) to authenticate with. This uri should end in "index.php".

consumer_token
: ConsumerToken

A token representing you, the consumer. Provided by MediaWiki via Special:OAuthConsumerRegistration.

callback
: str

Callback URL. Defaults to ‘oob’.

initiate(callback=None)[source]

Initiate an OAuth handshake with MediaWiki.

Parameters:
callback
: str

Callback URL. Defaults to ‘oob’.

Returns:

A tuple of two values:

  • a MediaWiki URL to direct the user to
  • a RequestToken representing an access request
complete(request_token, response_qs)[source]

Complete an OAuth handshake with MediaWiki by exchanging an

Parameters:
request_token
: RequestToken

A temporary token representing the user. Returned by initiate().

response_qs
: bytes

The query string of the URL that MediaWiki forwards the user back after authorization.

Returns:

An AccessToken containing an authorized key/secret pair that can be stored and used by you.

identify(access_token, leeway=10.0)[source]

Gather identifying information about a user via an authorized token.

Parameters:
access_token
: AccessToken

A token representing an authorized user. Obtained from complete().

leeway
: int | float

The number of seconds of leeway to account for when examining a tokens “issued at” timestamp.

Returns:

A dictionary containing identity information.

Tokens

A set of tokens (key/secret pairs) used to identify actors during and after an OAuth handshake.

class mwoauth.ConsumerToken(key, secret)

Represents a consumer (you). This key/secrets pair is provided by MediaWiki when you register an OAuth consumer (see Special:OAuthConsumerRegistration). Note that Extension:OAuth must be installed in order in order for Special:OAuthConsumerRegistration to appear.

Parameters:
key
: str

A hex string identifying the user

secret
: str

A hex string used to sign communications

key

Alias for field number 0

secret

Alias for field number 1

class mwoauth.RequestToken(key, secret)

Represents a request for access during authorization. This key/secret pair is provided by MediaWiki via Special:OAuth/initiate. Once the user authorize you, this token can be traded for an AccessToken via complete().

Parameters:
key
: str

A hex string identifying the user

secret
: str

A hex string used to sign communications

key

Alias for field number 0

secret

Alias for field number 1

class mwoauth.AccessToken(key, secret)

Represents an authorized user. This key and secret is provided by MediaWiki via Special:OAuth/complete and later used to show MediaWiki evidence of authorization.

Parameters:
key
: str

A hex string identifying the user

secret
: str

A hex string used to sign communications

key

Alias for field number 0

secret

Alias for field number 1

Stateless functions

A set of stateless functions that can be used to complete various steps of an OAuth handshake or to identify a MediaWiki user.

Example:
from mwoauth import ConsumerToken, initiate, complete, identify
from six.moves import input # For compatibility between python 2 and 3

# Consruct a "consumer" from the key/secret provided by MediaWiki
import config
consumer_token = ConsumerToken(
    config.consumer_key, config.consumer_secret)
mw_uri = "https://en.wikipedia.org/w/index.php"

# Step 1: Initialize -- ask MediaWiki for a temporary key/secret for
# user
redirect, request_token = initiate(mw_uri, consumer_token)

# Step 2: Authorize -- send user to MediaWiki to confirm authorization
print("Point your browser to: %s" % redirect) #
response_qs = input("Response query string: ")

# Step 3: Complete -- obtain authorized key/secret for "resource owner"
access_token = complete(
    mw_uri, consumer_token, request_token, response_qs)
print(str(access_token))

# Step 4: Identify -- (optional) get identifying information about the
# user
identity = identify(mw_uri, consumer_token, access_token)
print("Identified as {username}.".format(**identity))
mwoauth.initiate(mw_uri, consumer_token, callback='oob', user_agent='python-mwoauth default user agent')[source]

Initiate an oauth handshake with MediaWiki.

Parameters:
mw_uri
: str

The base URI of the MediaWiki installation. Note that the URI should end in "index.php".

consumer_token
: ConsumerToken

A token representing you, the consumer. Provided by MediaWiki via Special:OAuthConsumerRegistration.

callback
: str

Callback URL. Defaults to ‘oob’.

Returns:

A tuple of two values:

  • a MediaWiki URL to direct the user to
  • a RequestToken representing a request for access
mwoauth.complete(mw_uri, consumer_token, request_token, response_qs, user_agent='python-mwoauth default user agent')[source]

Complete an OAuth handshake with MediaWiki by exchanging an

Parameters:
mw_uri
: str

The base URI of the MediaWiki installation. Note that the URI should end in "index.php".

consumer_token
: ConsumerToken

A key/secret pair representing you, the consumer.

request_token
: RequestToken

A temporary token representing the user. Returned by initiate().

response_qs
: bytes

The query string of the URL that MediaWiki forwards the user back after authorization.

Returns:

An AccessToken containing an authorized key/secret pair that can be stored and used by you.

mwoauth.identify(mw_uri, consumer_token, access_token, leeway=10.0, user_agent='python-mwoauth default user agent')[source]

Gather identifying information about a user via an authorized token.

Parameters:
mw_uri
: str

The base URI of the MediaWiki installation. Note that the URI should end in "index.php".

consumer_token
: ConsumerToken

A token representing you, the consumer.

access_token
: AccessToken

A token representing an authorized user. Obtained from complete()

leeway
: int | float

The number of seconds of leeway to account for when examining a tokens “issued at” timestamp.

Returns:

A dictionary containing identity information.

Flask Blueprint

class mwoauth.flask.MWOAuth(host, consumer_token, user_agent=None, default_next='index', render_logout=None, render_indentify=None, render_error=None, **kwargs)[source]

Implements a basic MediaWiki OAuth pattern with a set of routes

  • /mwoauth/initiate – Starts an OAuth handshake
  • /mwoauth/callback – Completes an OAuth handshake
  • /mwoauth/identify – Gets identity information about an authorized user
  • /mwoauth/logout – Dicards OAuth tokens and user identity

There’s also a convenient decorator provided authorized(). When applied to a routing function, this decorator will redirect non-authorized users to /mwoauth/initiate with a ”?next=” that will return them to the originating route once authorization is completed.

Example:
from flask import Flask
import mwoauth
import mwoauth.flask

app = Flask(__name__)

@app.route("/")
def index():
    return "Hello world"

flask_mwoauth = mwoauth.flask.MWOAuth(
    "https://en.wikipedia.org",
    mwoauth.ConsumerToken("...", "..."))
app.register_blueprint(flask_mwoauth.bp)

@app.route("/my_settings/")
@mwoauth.flask.authorized
def my_settings():
    return flask_mwoauth.identity()
Parameters:
host
: str

The host name (including protocol) of the MediaWiki wiki to use for the OAuth handshake.

consumer_token
: mwoauth.ConsumerToken

The consumer token information

user_agent
: str

A User-Agent header to include with requests. A warning will be logged is this is not set.

default_next
: str

Where should the user be redirected after an OAuth handshake when no ‘?next=’ param is provided

render_logout
: func

A method that renders the logout page seen at /mwoauth/logout

render_identify
: func

A method that renders the identify page seen at /mwoauth/identify. Takes one positional argument – the identity dictionary returned by MediaWiki.

render_error
: func

A method that renders an error. Takes two arguements:

  • message : str (The error message)
  • status : int (The https status number)
**kwargs
: dict

Parameters to be passed to flask.Blueprint during its construction.

mwapi_session(*args, **kwargs)[source]

Create mwapi.Session that is authorized for the current user.

args and kwargs are passed directly to mwapi.Session

requests_session(*args, **kwargs)[source]

Create requests.Session that is authorized for the current user.

args and kwargs are passed directly to requests.Session

mwoauth.flask.authorized(route)[source]

Wrap a flask route. Ensure that the user has authorized via OAuth or redirect the user to the authorization endpoint with a delayed redirect back to the originating endpoint.

About

authors:Aaron Halfaker (http://halfaker.info) • Filippo Valsorda (https://filippo.io)
repository:mwoauth @ GitHub
documentation:mwoauth @ pythonhosted

Contributors

Pull requests are encouraged!

Indices and tables