Overview¶

django-sanction is a Django app for the sanction Python package. As its parent package, the intention of this package is to provide an incredibly easy-to-use Django OAuth 2.0 authorization/authentication app that is easy to grok.

This package makes no assumption as to what persistence mechanism you use. As such, no default custom user models (or abc’s) are implemented. Duck-typing is taken advantage of here and a specific API is required of the custom user model. This is defined below under User API. Integrating this package, defining the user model is likely where you’ll spend most of your time.

Configuration¶

First, django_sanction must be added to your INSTALLED_APPS:

INSTALLED_APPS = (
    # ...
    'django_sanction',
    # ...
)

The URLs defined by django_sanction must be added and anchored to a root path. In your applications’ urls.py:

urlpatterns = patterns('',
    url(r'^o/', include('django_sanction.urls')),
)

The above will define the URLs 'login/<provider>' and 'logout' under the path /o. For example: http://example.com/o/login/google.

AUTH_USER_MODEL = 'example.User'

SANCTION_PROVIDERS = {
    'google': {
        'auth_endpoint': 'https://accounts.google.com/o/oauth2/auth',
        'token_endpoint': 'https://accounts.google.com/o/oauth2/token',
        'resource_endpoint': 'https://www.googleapis.com/oauth2/v1',
        'client_id': '421833888173.apps.googleusercontent.com',
        'client_secret': 'VueqKFZyz-aoL4rQFleEIT1j',
        'redirect_uri': 'http://localhost:8080/o/login/google',
        'scope': ('email', 'https://www.googleapis.com/auth/userinfo.profile',),
        'auth_params': {'access_type': 'offline'}
    },
    'facebook': {
        'auth_endpoint': 'https://www.facebook.com/dialog/oauth',
        'token_endpoint': 'https://graph.facebook.com/oauth/access_token',
        'resource_endpoint': 'https://graph.facebook.com',
        'scope': ('email',),
        'parser': lambda data: dict(parse_qsl(data)),
        'client_id': '152107704926343',
        'client_secret': '80c81e4d7d5bc68ecc8cf1da0213382e',
        'redirect_uri': 'http://localhost:8080/o/login/facebook',
    }
}

AUTHENTICATION_BACKENDS = (
    'django_sanction.backends.AuthenticationBackend',
    'django.contrib.auth.backends.ModelBackend',
)

LOGIN_URL = '/'
LOGIN_REDIRECT_URL = '/profile'

User API¶

As django-sanction does not make any assumptions about how you’re going to persist your data, there is not a generic way to provide an interface. As such, we rely on duck typing. The following API must be implemented by your user object:

class User(object):
    def current_provider(self, request):
        """ Get the current provider

        Returns the current provider used by the current request's user
        """
        pass

    @staticmethod
    def fetch_user(provider, client):
        """ Fetches the user from the OAuth 2.0 provider

        This should return an instance of a ``User`` based on data from the
        provider resource.
        """
        pass

    @staticmethod
    def get_user(user_id)
        """ Returns a user object

        Retrieves an instance of a ``User`` (or ``None``) given the
        application-specific ``user_id``.
        """
        pass

Implementing the User class will likely be where you’ll spend the most of your time while integrating django_sanction.

Refreshing Tokens¶

Depending on how you use the OAuth 2.0-authorized user content, you may or may not have to worry about refreshing tokens. If you’re simply using it to generate user accounts with data such as email addresses and name, then you likely won’t have to worry about refreshing it. However, if your app interacts with an OAuth 2.0 provider after a token has expired (i.e post to a users’ Facebook wall), then this is something that you’ll have to worry about.

Refreshing tokens is entirely up to the application (there are far too many deviations or simply non-conformance among the providers to provide a general solution). Token refreshes themselves are outside the scope of this document. Please consult the documentation provided by the OAuth 2.0 provider.

Other¶