django-rest-framework-social-oauth2: a deprecated bridge between social login and token auth

The deprecation notice is the first thing in the README

The very first thing in the documentation is a warning block, and it is not subtle. This project is deprecated and no longer maintained, and the recommendation is to use django-allauth instead, described as providing a comprehensive solution for social authentication in Django REST Framework that is still worked on.

That framing decides most of what follows. The rest of the README is a complete, working installation guide, and it is worth reading precisely because it documents a pattern that still works, but the package is a dead end and the author says so.

The package itself is small in scope. It provides OAuth2 social authentication support for applications in Django REST Framework, and the aim is to help set up social authentication for a REST API. It also helps setting up your OAuth2 provider, which is the part that surprises people: this is not only a client of social providers, it is also a way to issue your own tokens to mobile apps that authenticate against a social account.

The implementation depends on two other projects rather than reimplementing OAuth. It relies on python-social-auth, which handles talking to the social providers, and on django-oauth-toolkit, which handles the token side. The README suggests reading their docs if you want to go further than what is done here, and links a plain-language explanation of OAuth2 for anyone who is finding the protocol itself difficult.

The project is MIT licensed, with a LICENSE.txt and a contributors.txt, and the last push was on 2026-04-17.

Three packages in INSTALLED_APPS, and the Django 1.8 context processor trap

Installation is a pip install followed by three settings changes.

pip install django-rest-framework-social-oauth2

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

The three entries are the django-oauth-toolkit app, the python-social-auth Django app, and this package itself, so all three have to be registered.

The social auth URLs are then included in urls.py, under a prefix that this package owns:

urlpatterns = patterns(
    ...
    (r'^auth/', include('rest_framework_social_oauth2.urls')),
)

The context processors are where the documentation shows its age. TEMPLATE_CONTEXT_PROCESSORS with social_django.context_processors.backends and social_django.context_processors.login_redirect was the way to do this, and the README notes that since Django version 1.8 that setting is deprecated. The modern form is to set the context_processors option in the OPTIONS of a DjangoTemplates backend instead:

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

That note is the clearest sign of the project's age, and it is also the kind of detail that breaks silently. A settings file copied from this README into a modern Django project raises a deprecation warning at startup rather than an error, and the context processors are not applied, so the backends context is empty and the social login flow fails at the point where it tries to resolve which provider to use.

The authentication classes and the OAuth2 application record

The DRF side is two settings blocks, and the first one carries a version conditional that tells you which era of django-oauth-toolkit is in play.

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
        'rest_framework_social_oauth2.authentication.SocialAuthentication',
    ),
}

So the standard OAuth2 authentication class comes from django-oauth-toolkit, with the module path depending on whether the toolkit is older or newer than 1.0.0, and the social authentication class comes from this package.

The backend list pairs the social backend with Django's own:

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

Then there is a Django admin task, which is the part that most often trips people up. You add a new Application with client_id and client_secret left unchanged, user set to your superuser, redirect_uris left blank, client_type set to confidential, authorization_grant_type set to Resource owner password-based, and name set to whatever you like.

The grant type choice is the crux. This is not a browser redirect flow with an authorisation code, it is the resource owner password-based grant, which is why redirect_uris can be blank and why the client_secret is left as generated. That grant type has been deprecated in OAuth 2.1 and removed in OAuth 2.2, so a project built this way is using a grant that is on its way out, which is one more reason to read the deprecation notice before copying any of it.

The package has two settings of its own. DRFSO2_PROPRIETARY_BACKEND_NAME is the name of your OAuth2 social backend, for example Facebook, and defaults to Django. DRFSO2_URL_NAMESPACE is the namespace for reversing URLs.

Four token endpoints, and the one that makes this package unusual

The testing section shows the API surface, and one of the four endpoints is the reason this package still exists in some codebases.

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

That retrieves a token for a user, using the password grant against your own API. The refresh token endpoint takes grant_type=refresh_token with the same client credentials and the refresh token.

The unusual one is the third:

curl -X POST -d "grant_type=convert_token&client_id=<client_id>&client_secret=<client_secret>&backend=<backend>&token=<backend_token>" http://localhost:8000/auth/convert-token

This exchanges an external token for a token linked to your app. The backend is the name of an enabled backend, for example Facebook, and the backend_token is the token you got from the service, for example from an iOS app. So a user who has signed in with a social provider on a device can hand you that provider's token, and your API swaps it for one of its own.

The note says that DRFSO2_PROPRIETARY_BACKEND_NAME is a valid backend name, but there is no use to do that here, which is a small warning against a configuration that would otherwise seem to work.

The fourth endpoint is revocation. Revoke a single token with grant_type alongside the token, and revoke all tokens for a user with an Authorization Bearer header and just the client_id, on the invalidate-sessions path.

So the package gives you a small OAuth2 provider surface on top of django-oauth-toolkit, with a social-token exchange on top, wired into DRF through a SocialAuthentication class that reads the backend name and token from the Authorization header and creates the user automatically if they are not registered yet. The authenticated request form is a two-part header:

curl -H "Authorization: Bearer <backend_name> <backend_token>" http://localhost:8000/route/to/your/view

What the package depends on, and what it costs to keep using

The setup script gives the dependency picture, and it is short enough to read at a glance. The runtime requirements are djangorestframework at 3.10.3 or newer, django-oauth-toolkit at 0.12.0 or newer, and social-auth-app-django at 3.1.0 or newer. The package guards its own Python floor with an explicit check that raises SystemError if the interpreter is older than 3.5.

The classifiers say Development Status 4 - Beta, which is consistent with a package that has been in place long enough to be depended upon and has stopped moving.

The first limitation is the deprecation itself. A package that is not maintained does not get security patches, and a package in the authentication path is the worst possible place for that. The dependencies it pulls in are not the risk, the package itself is.

The second limitation is the grant type. The documented setup uses Resource owner password-based, which means your API handles the user's password directly. That grant was removed in OAuth 2.2 and has been deprecated for years, and it is the pattern that leads to a second factor or a token policy being bolted on afterwards. The token endpoints here make it easy to build on that foundation, which is a reason to be careful rather than a reason it is fine.

The third limitation is the third-party surface. Three moving parts, python-social-auth, django-oauth-toolkit and this package, have to agree on versions, and the django-oauth-toolkit import path in the README even changes between versions before and after 1.0.0. A project that upgrades any of them may find that the documented configuration no longer matches.

The fourth is the automatic user creation. The SocialAuthentication class creates a new user if the person is not yet registered on your app, which is convenient and is also a policy decision your application may not want, since it happens inside the authentication layer rather than in your own sign-up code.

The successor named in the deprecation notice, django-allauth, takes over both the social authentication and the account management side, and is where a project starting today should look.

Editorial conclusion

django-rest-framework-social-oauth2 fits an existing Django REST Framework project that already runs an older social auth stack and needs token exchange endpoints without rewriting its authentication layer. It is a poor fit for anything new, because the project states it is deprecated and no longer maintained, and it points at django-allauth as the replacement to use instead. Before adopting, read the deprecation notice at the top of the README rather than the rest of it, check that your Python is 3.5 or above as the setup script requires, and plan the migration to django-allauth rather than adding another authentication dependency to a project that already has one.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. RealmTeam/django-rest-framework-social-oauth2 on GitHub