Welcome to django-rest-auth’s documentation!¶

Introduction¶

Since the introduction of django-rest-framework, Django apps have been able to serve up app-level REST API endpoints. As a result, we saw a lot of instances where developers implemented their own REST registration API endpoints here and there, snippets, and so on. We aim to solve this demand by providing django-rest-auth, a set of REST API endpoints to handle User Registration and Authentication tasks. By having these API endpoints, your client apps such as AngularJS, iOS, Android, and others can communicate to your Django backend site independently via REST APIs for User Management. Of course, we’ll add more API endpoints as we see the demand.

Installation¶

1. Install package:

pip install django-rest-auth

2. Add rest_auth app to INSTALLED_APPS in your django settings.py:

INSTALLED_APPS = (
    ...,
    'rest_framework',
    'rest_framework.authtoken',
    ...,
    'rest_auth'
)

3. Add rest_auth urls:

urlpatterns = patterns('',
    ...,
    url(r'^rest-auth/', include('rest_auth.urls'))
)

You’re good to go now!

INSTALLED_APPS = (
    ...,
    'allauth',
    'allauth.account',
    'rest_auth.registration',
)

urlpatterns = patterns('',
    ...,
    (r'^rest-auth/', include('rest_auth.urls')),
    (r'^rest-auth/registration/', include('rest_auth.registration.urls'))
)

INSTALLED_APPS = (
    ...,
    'rest_framework',
    'rest_framework.authtoken',
    'rest_auth'
    ...,
    'allauth',
    'allauth.account',
    'rest_auth.registration',
    ...,
    'allauth.socialaccount',
    'allauth.socialaccount.providers.facebook',
)

from allauth.socialaccount.providers.facebook.views import FacebookOAuth2Adapter
from rest_auth.registration.views import SocialLoginView

class FacebookLogin(SocialLoginView):
    adapter_class = FacebookOAuth2Adapter

urlpatterns += pattern('',
    ...,
    url(r'^rest-auth/facebook/$', FacebookLogin.as_view(), name='fb_login')
)

API endpoints¶

Configuration¶

• REST_AUTH_SERIALIZERS

  You can define your custom serializers for each endpoint without overriding urls and views by adding REST_AUTH_SERIALIZERS dictionary in your django settings. Possible key values:

  • LOGIN_SERIALIZER - serializer class in rest_auth.views.LoginView, default value rest_auth.serializers.LoginSerializer
  • TOKEN_SERIALIZER - response for successful authentication in rest_auth.views.LoginView, default value rest_auth.serializers.TokenSerializer
  • USER_DETAILS_SERIALIZER - serializer class in rest_auth.views.UserDetailsView, default value rest_auth.serializers.UserDetailsSerializer
  • PASSWORD_RESET_SERIALIZER - serializer class in rest_auth.views.PasswordResetView, default value rest_auth.serializers.PasswordResetSerializer
  • PASSWORD_RESET_CONFIRM_SERIALIZER - serializer class in rest_auth.views.PasswordResetConfirmView, default value rest_auth.serializers.PasswordResetConfirmSerializer
  • PASSWORD_CHANGE_SERIALIZER - serializer class in rest_auth.views.PasswordChangeView, default value rest_auth.serializers.PasswordChangeSerializer

  Example configuration:

  REST_AUTH_SERIALIZERS = {
      'LOGIN_SERIALIZER': 'path.to.custom.LoginSerializer',
      'TOKEN_SERIALIZER': 'path.to.custom.TokenSerializer',
      ...
  }
  

• REST_SESSION_LOGIN - Enable session login in Login API view (default: True)

• OLD_PASSWORD_FIELD_ENABLED - set it to True if you want to have old password verification on password change enpoint (default: False)

• LOGOUT_ON_PASSWORD_CHANGE - set to False if you want to keep the current user logged in after a password change

Demo project¶

The idea of creating demo project was to show how you can potentially use django-rest-auth app with jQuery on frontend. Do these steps to make it running (ideally in virtualenv).

cd /tmp
git clone https://github.com/Tivix/django-rest-auth.git
cd django-rest-auth/demo/
pip install -r requirements.pip
python manage.py syncdb --settings=demo.settings --noinput
python manage.py runserver --settings=demo.settings

Now, go to http://127.0.0.1:8000/ in your browser.

FAQ¶

1. Why account_confirm_email url is defined but it is not usable?

   In /rest_auth/registration/urls.py we can find something like this:

   url(r'^account-confirm-email/(?P<key>\w+)/$', TemplateView.as_view(),
       name='account_confirm_email'),
   

   This url is used by django-allauth. Empty TemplateView is defined just to allow reverse() call inside app - when email with verification link is being sent.

   You should override this view/url to handle it in your API client somehow and then, send post to /verify-email/ endpoint with proper key. If you don’t want to use API on that step, then just use ConfirmEmailView view from: djang-allauth https://github.com/pennersr/django-allauth/blob/master/allauth/account/views.py#L190

2. How can I update UserProfile assigned to User model?

   Assuming you already have UserProfile model defined like this

   from django.db import models
   from django.contrib.auth.models import User
   
   class UserProfile(models.Model):
       user = models.OneToOneField(User)
       # custom fields for user
       company_name = models.CharField(max_length=100)
   

   To allow update user details within one request send to rest_auth.views.UserDetailsView view, create serializer like this:

   from rest_framework import serializers
   from rest_auth.serializers import UserDetailsSerializer
   
   class UserSerializer(UserDetailsSerializer):
   
       company_name = serializers.CharField(source="userprofile.company_name")
   
       class Meta(UserDetailsSerializer.Meta):
           fields = UserDetailsSerializer.Meta.fields + ('company_name',)
   
       def update(self, instance, validated_data):
           profile_data = validated_data.pop('userprofile', {})
           company_name = profile_data.get('company_name')
   
           instance = super(UserSerializer, self).update(instance, validated_data)
   
           # get and update user profile
           profile = instance.userprofile
           if profile_data and company_name:
               profile.company_name = company_name
               profile.save()
           return instance
   

   And setup USER_DETAILS_SERIALIZER in django settings:

   REST_AUTH_SERIALIZERS = {
       'USER_DETAILS_SERIALIZER': 'demo.serializers.UserSerializer'
   }
   

Changelog¶