Metadata-Version: 1.1
Name: django-rest-framework-social-oauth2
Version: 0.0.5
Summary: UNKNOWN
Home-page: https://github.com/PhilipGarnero/django-rest-framework-social-oauth2
Author: Philip Garnero
Author-email: philip.garnero@gmail.com
License: MIT
Description: Django rest-framework Social Oauth2
        ===================================
        
        This module provides a python-social-auth and oauth2 support for django-rest-framework.
        
        The first aim of this package is to help setting up social auth for your rest api. It also helps setting up your Oauth2 provider.
        
        This package is relying on `python-social-auth <http://psa.matiasaguirre.net/docs/index.html>`_ and `django-oauth-toolkit <https://django-oauth-toolkit.readthedocs.org>`_.
        You should probably read their docs if you were to go further than what is done here.
        If you have some hard time understanding Oauth2 you can read a simple explanation `here <https://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified>`_.
        
        
        Installation
        ------------
        
        Install with pip::
        
            pip install django-rest-framework-social-oauth2
        
        
        Add these apps to your `INSTALLED_APPS`
        
        .. code-block:: python
        
            INSTALLED_APPS = (
                ...
                'oauth2_provider',
                'social.apps.django_app.default',
                'rest_framework_social_oauth2',
            )
        
        
        Include auth urls to your urls.py
        
        .. code-block:: python
        
            urlpatterns = patterns(
                ...
                (r'^auth/', include('rest_framework_social_oauth2.urls')),
            )
        
        
        Add these context processors to your `TEMPLATE_CONTEXT_PROCESSORS`
        
        .. code-block:: python
        
            TEMPLATE_CONTEXT_PROCESSORS = (
                ...
                'social.apps.django_app.context_processors.backends',
                'social.apps.django_app.context_processors.login_redirect',
            )
        
        
        You can then enable the authentication classes for django rest framework by default or per view (add or update the `REST_FRAMEWORK` and `AUTHENTICATION_BACKENDS` entries to your settings.py)
        
        .. code-block:: python
        
            REST_FRAMEWORK = {
                ...
                'DEFAULT_AUTHENTICATION_CLASSES': (
                    ...
                    'oauth2_provider.ext.rest_framework.OAuth2Authentication',
                    'rest_framework_social_oauth2.authentication.SocialAuthentication',
                ),
            }
        
        .. code-block:: python
        
            AUTHENTICATION_BACKENDS = (
                ...
               'rest_framework_social_oauth2.backends.DjangoOAuth2',
               'django.contrib.auth.backends.ModelBackend',
            )
        
        
        The two only settings of this app are :
         - PROPRIETARY_APPLICATION_NAME sets the name of your client , defaults to "Owner"
         - PROPRIETARY_BACKEND_NAME sets the name of your Oauth2 social backend (e.g Facebook), defaults to "Django"
        
        
        Now go to django admin and add a new Application.
         - client_id and client_secret shouldn't be changed
         - user should be your superuser
         - redirect_uris should be left blank
         - client_type should be set to public
         - authorization_grant_type should be set to 'Resource owner password-based'
         - name should be set to the value of PROPRIETARY_APPLICATION_NAME (by default its value is "Owner")
        
        
        The installation is done, you can now test the app.
        
        Remember that you need to read the docs from `python-social-auth` and `django-oauth-toolkit` if you want to go further.
        If you want to enable a social backend (like facebook), check the docs of `python-social-auth` about `supported backends <http://psa.matiasaguirre.net/docs/backends/index.html#social-backends>`_ or `django-social-auth` about `bakends system <http://django-social-auth.readthedocs.org/en/latest/backends/index.html>`_.
        
        
        Testing the setup
        -----------------
        
        - Now that the installation is done, let's try it ! Ask a token for an user using curl :
        
            curl -X POST -d "client_id=<client_id>&client_secret=<client_secret>&grant_type=password&username=<user_name>&password=<password>" http://localhost:8000/auth/token
        
        `<client_id>` and `<client_secret>` are the keys generated automatically that you can find in the model Application you created.
        
        -  Now let's imagine you need to refresh your token :
        
            curl -X POST -d "grant_type=refresh_token&client_id=<client_id>&client_secret=<client_secret>&refresh_token=<your_refresh_token>" http://localhost:8000/auth/token
        
        - Now let's try something else ! Let's exchange an external token for a token linked to your app :
        
            curl -H "Authorization: Bearer <backend> <backend_token>" http://localhost:8000/auth/convert-token
        
        `<backend>` here needs to be replaced by the name of an enabled backend (facebook for example if that's the case). Note that PROPRIETARY_BACKEND_NAME is a valid backend name but there is no use in using it here.
        `<backend_token>` is for the token you got from the service utilizing an iOS app for example.
        
        This is possible because convert_token is an api_view using 'rest_framework_social_oauth2.authentication.SocialAuthentication' as an authentication class.
        This class simply gets the backend and the backend token from the `Authorization` header and try to authenticate the user using the right external provider.
        
        - Finally, let's revoke your token :
            curl -X POST -d "client_id=<client_id>&client_secret=<client_secret>&token=<your_token>" http://localhost:8000/auth/revoke-token
        
        If you have any questions feel free to explore the code (there is very little) and to ask me.
        
        
        Facebook Backend
        -----------------
        
        To use Facebook as the authorization backend of your django-rest-framework api, your settings.py file should look like this:
        
        .. code-block:: python
        
            INSTALLED_APPS = (
                ...
                # OAuth
                'oauth2_provider',
                'social.apps.django_app.default',
                'rest_framework_social_oauth2',
            )
        
            TEMPLATE_CONTEXT_PROCESSORS = (
                ...
                # OAuth
                'social.apps.django_app.context_processors.backends',
                'social.apps.django_app.context_processors.login_redirect',
            )
        
            REST_FRAMEWORK = {
                ...
                'DEFAULT_AUTHENTICATION_CLASSES': (
                    ...
                    # OAuth
                    'oauth2_provider.ext.rest_framework.OAuth2Authentication',
                    'rest_framework_social_oauth2.authentication.SocialAuthentication',
                )
            }
        
            AUTHENTICATION_BACKENDS = (
        
                # Others auth providers (e.g. Google, OpenId, etc)
                ...
        
                # Facebook OAuth2
                'social.backends.facebook.FacebookAppOAuth2',
                'social.backends.facebook.FacebookOAuth2',
        
                # django-rest-framework-social-oauth2
                'rest_framework_social_oauth2.backends.DjangoOAuth2',
        
                # Django
                'django.contrib.auth.backends.ModelBackend',
        
            )
        
            # Facebook configuration
            SOCIAL_AUTH_FACEBOOK_KEY = '<your app id goes here>'
            SOCIAL_AUTH_FACEBOOK_SECRET = '<your app secret goes here'
        
            # Define SOCIAL_AUTH_FACEBOOK_SCOPE to get extra permissions from facebook. Email is not sent by default, to get it, you must request the email permission:
            SOCIAL_AUTH_FACEBOOK_SCOPE = ['email']
        
        
        - You can test these settings by running the following command :
        
            curl -H "Authorization: Bearer facebook <user_access_token>" http://localhost:8000/auth/convert-token
        
        This request returns the "access_token" that you should use on all HTTP requests with DRF. What is happening here is that we are converting a third-party access token (<user_access_token>) in an access token to use with your api and its clients ("access_token"). You should use this token on each and further communications between your system/application and your api to authenticate each request and avoid authenticating with FB every time.
        
        Upon receiving this request, the 'convert_token' view authorizes this execution by first calling the 'SocialAuthentication' class which will validate the token against Facebook, because that is the <backend> specified in the CURL command. Facebook validates the token and returns the user data wich will be use by this class to return the existing User or to create a new one if necessary. Eventually, the 'convert_token' view receives this User and creates or loads an existing token (access_token) and returns it.
        
        You can find the id and secret of your app at https://developers.facebook.com/apps/.
        
        For testing purposes you can use the access token `<user_access_token>` from https://developers.facebook.com/tools/accesstoken/.
        
        For more information on how to configure python-social-auth with Facebook visit http://psa.matiasaguirre.net/docs/backends/facebook.html.
        
        
        
        
        
        
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
