<commit_before>.. image:: https://secure.travis-ci.org/demianbrecht/django_sanction.png?branch=master 
   :target: http://travis-ci.org/#!/demianbrecht/django_sanction


.. contents::
   :depth: 3


Overview
========

``django_sanction`` is a Django wrapper for the sanction_ module, 
making OAuth2 authentication and resource requests as easy to implement 
as possible. The goals of the project are to be:

Provider agnostic
-----------------

There is no assumption made about what providers should be accounted for 
(as in the core sanction_ module). This means that while providers that 
follow the `OAuth2 spec`_ should be handled by default, deviant providers
may have to have custom implementations for certain handlers (see
stackexchange and facebook examples in the examples directory). This also
means that the user will need to have at least a basic understanding of
OAuth2 and provider implementations. However, the upside is that the library
is flexible in that library maintenance does not need to occur in order to
support new OAuth2 providers.


Persistence agnostic
--------------------

``django_sanction`` doesn't care if you use the provided 
``django_sanction.models.User`` model (which is an extension of the 
contrib.auth ``User`` model) or a custom nonrel user class, as long
as a few required attributes exist on the model:

* ``access_token``
  Resource access token granted by the OAuth2 provider
* ``expires``
  The token expiry date (if applicable, will be set to -1 if non-expiring)
* ``provider_id``
  The user ID as specified by the OAuth2 provider. This is a required
  field in the OAuth2 spec (while e-mail addresses are not).
* ``provider_key``
  The key (or name) or the provider used for a given user. This is used
  in order to look up the provider in the application's ``settings.py``
  file.


Flexible
--------

While most functionality is accounted for and provided out of the box,
``django_sanction`` is flexible where it makes sense to be. See the settings
section for more details.


Usage
=====

Required settings
-----------------

Define a list of providers in your settings.py file::

    OAUTH2_PROVIDERS = { 
        "google": { 
            "client_id": "421833888173.apps.googleusercontent.com",
            "client_secret": "<KEY>",
            "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",
            "scope": ("email", "https://www.googleapis.com/auth/userinfo.profile",)
        },
        "facebook": {
            "client_id": "152107704926343",
            "client_secret": "80c81e4d7d5bc68ecc8cf1da0213382e",
            "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": parse_url
        },
    }

As ``django_sanction`` and its parent module ``sanction`` are provider-
agnostic, you must supply the relevant data for each.

Required provider fields
````````````````````````

* ``client_id``

  The client id as provided by the resource provider

* ``client_secret``

  The client secret as provided by the resource provider

* ``auth_endpoint``

  The providers' auth dialog endpoint to which users will be redirected for authorization

* ``token_endpoint``

  The endpoint used to swap the grant code for an access token

* ``resource_endpoint``

  The endpoint used to access user resources

Optional provider fields
````````````````````````

* ``scope``
  
  A list of scope parameters to request extended permissions from a user

* ``redirect_uri``

  The registered URL that the user will be redirected back to upon authorization

* ``parser``

  The parser to use for returned provider data


:note: If a provider deviates from the OAuth 2.0 spec in how it returns user
       data, client code must provide a supporting parser. See Facebook and 
       StackExchange implementations in the example project.


Authentication
--------------

Implement an authentication routine (see the example project for implementation
details) and add it to your settings file::

    OAUTH_AUTH_FN = "example.auth.authenticate"


Backend
-------

Add the authentication backend to your settings::

    AUTHENTICATION_BACKENDS = (
        "django_sanction.backends.AuthenticationBackend",
    )

``django_sanction`` will play nicely with authentication backends, so it's
perfectly valid to have multiple backends listed here.

<commit_msg>fixed typo in README<commit_after>.. image:: https://secure.travis-ci.org/demianbrecht/django_sanction.png?branch=master 
   :target: http://travis-ci.org/#!/demianbrecht/django_sanction


.. contents::
   :depth: 3


Overview
========

``django_sanction`` is a Django wrapper for the sanction_ module, 
making OAuth2 authentication and resource requests as easy to implement 
as possible. The goals of the project are to be:

Provider agnostic
-----------------

There is no assumption made about what providers should be accounted for 
(as in the core sanction_ module). This means that while providers that 
follow the `OAuth2 spec`_ should be handled by default, deviant providers
may have to have custom implementations for certain handlers (see
stackexchange and facebook examples in the examples directory). This also
means that the user will need to have at least a basic understanding of
OAuth2 and provider implementations. However, the upside is that the library
is flexible in that library maintenance does not need to occur in order to
support new OAuth2 providers.


Persistence agnostic
--------------------

``django_sanction`` doesn't care if you use the provided 
``django_sanction.models.User`` model (which is an extension of the 
contrib.auth ``User`` model) or a custom nonrel user class, as long
as a few required attributes exist on the model:

* ``access_token``
  Resource access token granted by the OAuth2 provider
* ``expires``
  The token expiry date (if applicable, will be set to -1 if non-expiring)
* ``provider_id``
  The user ID as specified by the OAuth2 provider. This is a required
  field in the OAuth2 spec (while e-mail addresses are not).
* ``provider_key``
  The key (or name) or the provider used for a given user. This is used
  in order to look up the provider in the application's ``settings.py``
  file.


Flexible
--------

While most functionality is accounted for and provided out of the box,
``django_sanction`` is flexible where it makes sense to be. See the settings
section for more details.


Usage
=====

Required settings
-----------------

Define a list of providers in your settings.py file::

    OAUTH2_PROVIDERS = { 
        "google": { 
            "client_id": "421833888173.apps.googleusercontent.com",
            "client_secret": "<KEY>",
            "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",
            "scope": ("email", "https://www.googleapis.com/auth/userinfo.profile",)
        },
        "facebook": {
            "client_id": "152107704926343",
            "client_secret": "80c81e4d7d5bc68ecc8cf1da0213382e",
            "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": parse_url
        },
    }

As ``django_sanction`` and its parent module ``sanction`` are provider-
agnostic, you must supply the relevant data for each.

Required provider fields
````````````````````````

* ``client_id``

  The client id as provided by the resource provider

* ``client_secret``

  The client secret as provided by the resource provider

* ``auth_endpoint``

  The providers' auth dialog endpoint to which users will be redirected for authorization

* ``token_endpoint``

  The endpoint used to swap the grant code for an access token

* ``resource_endpoint``

  The endpoint used to access user resources

Optional provider fields
````````````````````````

* ``scope``
  
  A list of scope parameters to request extended permissions from a user

* ``redirect_uri``

  The registered URL that the user will be redirected back to upon authorization

* ``parser``

  The parser to use for returned provider data


:note: If a provider deviates from the OAuth 2.0 spec in how it returns user
       data, client code must provide a supporting parser. See Facebook and 
       StackExchange implementations in the example project.


Authentication
--------------

Implement an authentication routine (see the example project for implementation
details) and add it to your settings file::

    OAUTH2_AUTH_FN = "example.auth.authenticate"


Backend
-------

Add the authentication backend to your settings::

    AUTHENTICATION_BACKENDS = (
        "django_sanction.backends.AuthenticationBackend",
    )

``django_sanction`` will play nicely with authentication backends, so it's
perfectly valid to have multiple backends listed here.


{'fraction_non_alphanumeric': 0.10837438423645321, 'fraction_numerical': 0.013171985435853501, 'mean_word_length': 3.41351606805293, 'pattern_counts': {'":': 30, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 16, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4454510', 'n_tokens_mistral': 2635, 'n_tokens_neox': 2469, 'n_words': 1037}