Usage

This guide will walk you through the process of installing DRF-Social-OAuth2 and setting it up for use with your Django REST Framework application. It assumes that you have some familiarity with Django and have a basic understanding of OAuth2 authentication. If you’re new to Django or OAuth2, we recommend checking out our resources section for additional learning materials.

To begin, you’ll need to have Python 3 and pip installed on your local machine. Once you have those installed, you can follow the instructions outlined in the installation section of this guide to install DRF-Social-OAuth2 and its dependencies. Then, you can configure your Django settings to use DRF-Social-OAuth2 by adding the necessary lines to your settings.py file. Finally, you’ll need to migrate your database to apply the changes.

By the end of this guide, you’ll have successfully installed DRF-Social-OAuth2 and set it up for use with your Django REST Framework application. With DRF-Social-OAuth2, you can make your REST API more secure and user-friendly by allowing users to authenticate with their social media accounts.

Installation

This framework is published at the PyPI, install it with pip:

$ pip install drf_social_oauth2==3.1.0

To enable OAuth2 social authentication support for your Django REST Framework application, you need to install and configure drf-social-oauth2. To get started, add the following packages to your INSTALLED_APPS:

INSTALLED_APPS = (
    ...
    'oauth2_provider',
    'social_django',
    'drf_social_oauth2',
)

Include social auth urls to your urls.py:

from django.conf.urls import url

urlpatterns = patterns(
    ...
    url(r'^auth/', include('drf_social_oauth2.urls', namespace='drf'))
)

For versions of Django 4.0 or higher, use re_path instead:

from django.urls import re_path

urlpatterns = patterns(
    ...
    re_path(r'^auth/', include('drf_social_oauth2.urls', namespace='drf'))
)

Next, add the following context processors to your TEMPLATE_CONTEXT_PROCESSORS:

TEMPLATE_CONTEXT_PROCESSORS = (
    ...
    'social_django.context_processors.backends',
    'social_django.context_processors.login_redirect',
)

Note that since Django version 1.8, the TEMPLATE_CONTEXT_PROCESSORS setting is deprecated. You should instead set the ‘context_processors’ option in the OPTIONS of a DjangoTemplates backend:

TEMPLATES = [
    {
        ...
        'OPTIONS': {
            'context_processors': [
                ...
                'social_django.context_processors.backends',
                'social_django.context_processors.login_redirect',
            ],
        },
    }
]

You can then enable the authentication classes for Django REST Framework by default or per view by updating the REST_FRAMEWORK and AUTHENTICATION_BACKENDS entries in your settings.py:

REST_FRAMEWORK = {
    ...
    'DEFAULT_AUTHENTICATION_CLASSES': (
        ...
        # 'oauth2_provider.ext.rest_framework.OAuth2Authentication',  # django-oauth-toolkit < 1.0.0
        'oauth2_provider.contrib.rest_framework.OAuth2Authentication',  # django-oauth-toolkit >= 1.0.0
        'drf_social_oauth2.authentication.SocialAuthentication',
    ),
}

AUTHENTICATION_BACKENDS = (
    ...
   'drf_social_oauth2.backends.DjangoOAuth2',
   'django.contrib.auth.backends.ModelBackend',
)

The following are settings available for drf-social-oauth2:

DRFSO2_PROPRIETARY_BACKEND_NAME: name of your OAuth2 social backend (e.g "Facebook"), defaults to "Django"
DRFSO2_URL_NAMESPACE: namespace for reversing URLs
ACTIVATE_JWT: if set to True, both access and refresh tokens are issued as JWTs signed with SECRET_KEY (HS256). Default is False. See Activating JWT tokens below.

Activating JWT tokens

To make /auth/token and /auth/convert-token issue JWT-encoded access and refresh tokens, set ACTIVATE_JWT = True in your Django settings:

# settings.py
ACTIVATE_JWT = True

That is the only thing you need to do — provided 'drf_social_oauth2' is in INSTALLED_APPS, the package’s AppConfig.ready() hook wires the JWT generators into django-oauth-toolkit at startup.

What the response looks like

The token_type field stays "Bearer" — that is the OAuth2 transport, not the token format. The JWT lives in the access_token (and refresh_token) value itself: three dot-separated base64url segments.

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6Ii4uLiJ9.SIGNATURE",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "read write",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6Ii4uLiJ9.SIGNATURE"
}

You can verify the token format with PyJWT:

import jwt
from django.conf import settings

decoded = jwt.decode(access_token, settings.SECRET_KEY, algorithms=['HS256'])
# {'token': '<random 30-char opaque token>'}

Using the token in subsequent requests

Send it as a normal Bearer credential:

Authorization: Bearer eyJhbGciOi...

Do not include the backend name in the header (e.g. Bearer facebook eyJ...); that format is rejected by OAuth2Authentication.

Caveat: explicit overrides win

If your OAUTH2_PROVIDER dict explicitly sets ACCESS_TOKEN_GENERATOR or REFRESH_TOKEN_GENERATOR, those values take precedence and ACTIVATE_JWT becomes a no-op. Either remove those keys or point them at 'drf_social_oauth2.generate_token' yourself.