Installation

  1. Install package:
pip install dj-rest-auth
  1. Add dj_rest_auth app to INSTALLED_APPS in your django settings.py:
INSTALLED_APPS = (
    ...,
    'rest_framework',
    'rest_framework.authtoken',
    ...,
    'dj_rest_auth'
)

Note

This project depends on django-rest-framework library, so install it if you haven’t done yet. Make sure also you have installed rest_framework and rest_framework.authtoken apps

  1. Add dj_rest_auth urls:
urlpatterns = [
    ...,
    path('dj-rest-auth/', include('dj_rest_auth.urls'))
]
  1. Migrate your database
python manage.py migrate

You’re good to go now!

Registration (optional)

  1. If you want to enable standard registration process you will need to install django-allauth by using pip install 'dj-rest-auth[with_social]'.
  2. Add django.contrib.sites, allauth, allauth.account, allauth.socialaccount and dj_rest_auth.registration apps to INSTALLED_APPS in your django settings.py:
  3. Add SITE_ID = 1 to your django settings.py
INSTALLED_APPS = (
    ...,
    'django.contrib.sites',
    'allauth',
    'allauth.account',
    'allauth.socialaccount',
    'dj_rest_auth.registration',
)

SITE_ID = 1
  1. Add dj_rest_auth.registration urls:
urlpatterns = [
    ...,
    path('dj-rest-auth/', include('dj_rest_auth.urls')),
    path('dj-rest-auth/registration/', include('dj_rest_auth.registration.urls'))
]

Social Authentication (optional)

Using django-allauth, dj-rest-auth provides helpful class for creating social media authentication view.

Note

Points 1 and 2 are related to django-allauth configuration, so if you have already configured social authentication, then please go to step 3. See django-allauth documentation for more details.

  1. Add allauth.socialaccount and allauth.socialaccount.providers.facebook or allauth.socialaccount.providers.twitter apps to INSTALLED_APPS in your django settings.py:
INSTALLED_APPS = (
    ...,
    'rest_framework',
    'rest_framework.authtoken',
    'dj_rest_auth'
    ...,
    'django.contrib.sites',
    'allauth',
    'allauth.account',
    'dj_rest_auth.registration',
    ...,
    'allauth.socialaccount',
    'allauth.socialaccount.providers.facebook',
    'allauth.socialaccount.providers.twitter',

)
  1. Add Social Application in django admin panel

Facebook

  1. Create new view as a subclass of dj_rest_auth.registration.views.SocialLoginView with FacebookOAuth2Adapter adapter as an attribute:
from allauth.socialaccount.providers.facebook.views import FacebookOAuth2Adapter
from dj_rest_auth.registration.views import SocialLoginView

class FacebookLogin(SocialLoginView):
    adapter_class = FacebookOAuth2Adapter
  1. Create url for FacebookLogin view:
urlpatterns += [
    ...,
    path('dj-rest-auth/facebook/', FacebookLogin.as_view(), name='fb_login')
]

Twitter

If you are using Twitter for your social authentication, it is a bit different since Twitter uses OAuth 1.0.

  1. Create new view as a subclass of dj_rest_auth.registration.views.SocialLoginView with TwitterOAuthAdapter adapter and TwitterLoginSerializer as an attribute:
from allauth.socialaccount.providers.twitter.views import TwitterOAuthAdapter
from dj_rest_auth.registration.views import SocialLoginView
from dj_rest_auth.social_serializers import TwitterLoginSerializer

class TwitterLogin(SocialLoginView):
    serializer_class = TwitterLoginSerializer
    adapter_class = TwitterOAuthAdapter
  1. Create url for TwitterLogin view:
urlpatterns += [
    ...,
    path('dj-rest-auth/twitter/', TwitterLogin.as_view(), name='twitter_login')
]

Note

Starting from v0.21.0, django-allauth has dropped support for context processors. Check out http://django-allauth.readthedocs.org/en/latest/changelog.html#from-0-21-0 for more details.

GitHub

If you are using GitHub for your social authentication, it uses code and not AccessToken directly.

  1. Create new view as a subclass of dj_rest_auth.views.SocialLoginView with GitHubOAuth2Adapter adapter, an OAuth2Client and a callback_url as attributes:
from allauth.socialaccount.providers.github.views import GitHubOAuth2Adapter
from allauth.socialaccount.providers.oauth2.client import OAuth2Client
from dj_rest_auth.registration.views import SocialLoginView

class GitHubLogin(SocialLoginView):
    adapter_class = GitHubOAuth2Adapter
    callback_url = CALLBACK_URL_YOU_SET_ON_GITHUB
    client_class = OAuth2Client
  1. Create url for GitHubLogin view:
urlpatterns += [
    ...,
    path('dj-rest-auth/github/', GitHubLogin.as_view(), name='github_login')
]

Google

If you are using Google for your social authentication, you can choose Authorization Code Grant or Implicit Grant (deprecated). Serializer of dj-rest-auth accepts both code and token

  1. Add allauth.socialaccount and allauth.socialaccount.providers.google apps to INSTALLED_APPS in your django settings.py:
INSTALLED_APPS = (
    ...,
    'rest_framework',
    'rest_framework.authtoken',
    'dj_rest_auth'
    ...,
    'django.contrib.sites',
    'allauth',
    'allauth.account',
    'dj_rest_auth.registration',
    ...,
    'allauth.socialaccount',
    'allauth.socialaccount.providers.google',

)
  1. Create new view as a subclass of dj_rest_auth.views.SocialLoginView with GoogleOAuth2Adapter adapter, an OAuth2Client and a callback_url as attributes:
from allauth.socialaccount.providers.google.views import GoogleOAuth2Adapter
from allauth.socialaccount.providers.oauth2.client import OAuth2Client
from dj_rest_auth.registration.views import SocialLoginView

class GoogleLogin(SocialLoginView): # if you want to use Authorization Code Grant, use this
    adapter_class = GoogleOAuth2Adapter
    callback_url = CALLBACK_URL_YOU_SET_ON_GOOGLE
    client_class = OAuth2Client

class GoogleLogin(SocialLoginView): # if you want to use Implicit Grant, use this
    adapter_class = GoogleOAuth2Adapter
  1. Create url for GoogleLogin view:
urlpatterns += [
    ...,
    path('dj-rest-auth/google/', GoogleLogin.as_view(), name='google_login')
]

5. Retrive code (or token) By accessing Google’s endpoint, you can get code or token

If you’re using Authorization Code Grant, you can get code from folloing URL

https://accounts.google.com/o/oauth2/v2/auth?redirect_uri=<CALLBACK_URL_YOU_SET_ON_GOOGLE>&prompt=consent&response_type=code&client_id=<YOUR CLIENT ID>&scope=openid%20email%20profile&access_type=offline

If you’re using Implicit Grant, you can get token from folloing URL

https://accounts.google.com/o/oauth2/v2/auth?redirect_uri=<CALLBACK_URL_YOU_SET_ON_GOOGLE>&prompt=consent&response_type=token&client_id=<YOUR CLIENT ID>&scope=openid%20email%20profile

  1. POST code or token to specified URL(/dj-rest-auth/google/)

Additional Social Connect Views

If you want to allow connecting existing accounts in addition to login, you can use connect views:

from allauth.socialaccount.providers.facebook.views import FacebookOAuth2Adapter
from allauth.socialaccount.providers.github.views import GitHubOAuth2Adapter
from allauth.socialaccount.providers.twitter.views import TwitterOAuthAdapter
from allauth.socialaccount.providers.oauth2.client import OAuth2Client
from dj_rest_auth.registration.views import SocialConnectView
from dj_rest_auth.social_serializers import TwitterConnectSerializer

class FacebookConnect(SocialConnectView):
    adapter_class = FacebookOAuth2Adapter

class TwitterConnect(SocialConnectView):
    serializer_class = TwitterConnectSerializer
    adapter_class = TwitterOAuthAdapter

class GithubConnect(SocialConnectView):
    adapter_class = GitHubOAuth2Adapter
    callback_url = CALLBACK_URL_YOU_SET_ON_GITHUB
    client_class = OAuth2Client

In urls.py:

urlpatterns += [
    ...,
    path('dj-rest-auth/facebook/connect/', FacebookConnect.as_view(), name='fb_connect')
    path('dj-rest-auth/twitter/connect/', TwitterConnect.as_view(), name='twitter_connect')
    path('dj-rest-auth/github/connect/', GithubConnect.as_view(), name='github_connect')
]

You can also use the following views to check all social accounts attached to the current authenticated user and disconnect selected social accounts:

from dj_rest_auth.registration.views import (
    SocialAccountListView, SocialAccountDisconnectView
)

urlpatterns += [
    ...,
    path(
        'socialaccounts/',
        SocialAccountListView.as_view(),
        name='social_account_list'
    ),
    path(
        'socialaccounts/<int:pk>/disconnect/',
        SocialAccountDisconnectView.as_view(),
        name='social_account_disconnect'
    )
]

JSON Web Token (JWT) Support (optional)

By default dj-rest-auth uses Django’s Token-based authentication. If you want to use JWT authentication, follow these steps:

  1. Install djangorestframework-simplejwt
    • djangorestframework-simplejwt is currently the only supported JWT library.
  2. Add a simple_jwt auth configuration to the list of authentication classes.
REST_FRAMEWORK = {
    ...
    'DEFAULT_AUTHENTICATION_CLASSES': (
        ...
        'dj_rest_auth.jwt_auth.JWTCookieAuthentication',
    )
    ...
}
  1. Add the following configuration value to your settings file to enable JWT authentication in dj-rest-auth.
REST_USE_JWT = True
  1. Declare what you want the cookie key to be called. If you want to use the refresh token feature, also be sure to set that variable.
JWT_AUTH_COOKIE = 'my-app-auth'
JWT_AUTH_REFRESH_COOKIE = 'my-refresh-token'

This example value above will cause dj-rest-auth to return a Set-Cookie header that looks like this:

Set-Cookie: my-app-auth=xxxxxxxxxxxxx; expires=Sat, 28 Mar 2020 18:59:00 GMT; HttpOnly; Max-Age=300; Path=/

If JWT_AUTH_REFRESH_COOKIE is also set, it will also set a comperable cookie for that. JWT_AUTH_COOKIE is also used while authenticating each request against protected views.