wsgi-oauth2

_images/oauth2.png

This module provides a simple WSGI middleware that requires the user to authenticate via the specific OAuth 2.0 service e.g. Facebook, Google.

Prerequisites

It requires Python 2.6 or higher. (Not tested on Python 3 or higher.) It has no dependencies for non standard libraries, but if there is an installed simplejson library, it will be used instead of the standard json package.

Installation

You can install the package via downloading from PyPI:

$ pip install wsgi-oauth2

If you want to use the bleeding edge, install it from the Git repository:

$ pip install git+git://github.com/StyleShare/wsgi-oauth2.git

Predefined services

There are some predefined services.

wsgioauth2.google = <wsgioauth2.Service object at 0x1061f5750>

(Service) The predefined service for Google.

wsgioauth2.facebook = <wsgioauth2.Service object at 0x1061f5690>

(Service) The predefined service for Facebook.

wsgioauth2.github = <wsgioauth2.GitHubService object at 0x1061f5790>

(GitHubService) The predefined service for GitHub.

Basic usage

from myapp import app
from wsgioauth2 import github

client = github.make_client(client_id='...', client_secret='...')
app = client.wsgi_middleware(app, secret='hmac*secret')

wsgioauth2 — API references

class wsgioauth2.Service(authorize_endpoint, access_token_endpoint)

OAuth 2.0 service provider e.g. Facebook, Google. It takes endpoint urls for authorization and access token gathering APIs.

Parameters:
  • authorize_endpoint (basestring) – api url for authorization
  • access_token_endpoint (basestring) – api url for getting access token
access_token_endpoint = None

(basestring) The API URL for getting access token.

authorize_endpoint = None

(basestring) The API URL for authorization.

is_user_allowed(access_token)

Check if the authenticated user is allowed to access the protected application. By default, any authenticated user is allowed access. Override this check to allow the Service to further-restrict access based on additional information known by the service.

Parameters:access_token – a valid AccessToken
load_username(access_token)

Load a username from the service suitable for the REMOTE_USER variable. A valid AccessToken is provided to allow access to authenticated resources provided by the service. If the service supports usernames this method must set the ‘username’ parameter to access_token.

Parameters:access_token – a valid AccessToken
make_client(client_id, client_secret, **extra)

Makes a Client for the service.

Parameters:
  • client_id (basestring, int, long) – a client id
  • client_secret (basestring) – client secret key
  • **extra – additional arguments for authorization e.g. scope='email,read_stream'
Returns:

a client for the service

Return type:

Client

class wsgioauth2.Client(service, client_id, client_secret, **extra)

Client for Service.

Parameters:
  • service – service the client connects to
  • client_id (basestring, int, long) – client id
  • client_secret (basestring) – client secret key
  • **extra – additional arguments for authorization e.g. scope='email,read_stream'
client_id = None

(basestring) The client id.

client_secret = None

(basestring) The client secret key.

load_username(access_token)

Load a username from the configured service suitable for the REMOTE_USER variable. A valid AccessToken is provided to allow access to authenticated resources provided by the service. For GitHub the ‘login’ variable is used.

Parameters:access_token – a valid AccessToken
make_authorize_url(redirect_uri, state=None)

Makes an authorize URL.

Parameters:
  • redirect_uri (basestring) – callback url
  • state (basestring) – optional state to get when the user returns to callback
Returns:

generated authorize url

Return type:

basestring

request_access_token(redirect_uri, code)

Requests an access token.

Parameters:
  • redirect_uri (basestring) – redirect_uri that was passed to make_authorize_url()
  • code (code) – verification code that authorize endpoint provides
Returns:

access token and additional data

Return type:

AccessToken

service = None

(Service) The service the client connects to.

wsgi_middleware(*args, **kwargs)

Wraps a WSGI application.

class wsgioauth2.AccessToken(*args, **kwargs)

Dictionary that contains access token. It always has 'access_token' key.

access_token

(basestring) Access token.

get(url, headers={})

Requests url as GET.

Parameters:headers (collections.Mapping) – additional headers
post(url, form={}, headers={})

Requests url as POST.

Parameters:
class wsgioauth2.WSGIMiddleware(client, application, secret, path=None, cookie='wsgioauth2sess', set_remote_user=False, forbidden_path=None, forbidden_passthrough=False)

WSGI middleware application.

Parameters:
  • client (Client) – oauth2 client
  • application (callable object) – wsgi application
  • secret (basestring) – secret key for generating HMAC signature
  • path (basestring) – path prefix used for callback. by default, a randomly generated complex path is used
  • cookie (basestring) – cookie name to be used for maintaining the user session. default is DEFAULT_COOKIE
  • set_remote_user (bool) – Set to True to set the REMOTE_USER environment variable to the authenticated username (if supported by the Service)
  • forbidden_path (basestring) – What path should be used to display the 403 Forbidden page. Any forbidden user will be redirected to this path and a default 403 Forbidden page will be shown. To override the default Forbidden page see the forbidden_passthrough option.
  • forbidden_passthrough (bool) – Should the forbidden page be passed-through to the protected application. By default, a generic Forbidden page will be generated. Set this to True to pass the request through to the protected application.

(basestring) The default name for cookie.

application = None

(callable object) The wrapped WSGI application.

client = None

(Client) The OAuth2 client.

cookie = None

(basestring) The cookie name to be used for maintaining the user session.

forbidden(start_response)

Respond with an HTTP 403 Forbidden status.

forbidden_passthrough = None

(bool) Whether the forbidden page should be passed-through to the protected application. By default, a generic Forbidden page will be generated. Set this to True to pass the request through to the protected application.

forbidden_path = None

(basestring) The path that is used to display the 403 Forbidden page. Any forbidden user will be redirected to this path and a default 403 Forbidden page will be shown. To override the default Forbidden page see the forbidden_passthrough option.

path = None

(basestring) The path prefix for callback URL. It always starts and ends with '/'.

secret = None

(basestring) The secret key for generating HMAC signature.

class wsgioauth2.GitHubService(allowed_orgs=None)

OAuth 2.0 service provider for GitHub with support for getting the authorized username.

Parameters:allowed_orgs (basestring, collections.Container of basestring) – What GitHub Organizations are allowed to access the protected application.
is_user_allowed(access_token)

Check if the authenticated user is allowed to access the protected application. If this GitHubService was created with a list of allowed_orgs, the user must be a memeber of one or more of the allowed_orgs to get access. If no allowed_orgs were specified, all authenticated users will be allowed.

Parameters:access_token – a valid AccessToken
load_username(access_token)

Load a username from the service suitable for the REMOTE_USER variable. A valid AccessToken is provided to allow access to authenticated resources provided by the service. For GitHub the ‘login’ variable is used.

Parameters:access_token – a valid AccessToken

Source code

The source code is available under MIT license. Check out from the GitHub:

$ git clone git://github.com/StyleShare/wsgi-oauth2.git

We welcome pull requests as well!

Bugs

If you found bugs or want to propose some improvement ideas, use the issue tracker.

Author

The package is written by Hong Minhee for StyleShare.

Changelog

Version 0.1.3

Released on June 19, 2013.

Version 0.1.2

Released on March 22, 2013.

Version 0.1.1

Released on May 2, 2012.

  • Set cookie with expires option if the response contains expires_in parameter. [pull request #2 by mete0r]

Version 0.1.0

Released on November 4, 2011. First version.