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: 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: The base URI of the MediaWiki installation. Note that the URI should end in "index.php".
consumer_token: A token representing you, the consumer. Provided by MediaWiki via Special:OAuthConsumerRegistration.
callback: 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!

MediaWiki OAuth Library Documentation¶

The OAuth Handshaker¶

Tokens¶

Stateless functions¶

Flask Blueprint¶

About¶

Contributors¶

Indices and tables¶

Table Of Contents

Related Topics

This Page