Welcome to django-rest-auth’s documentation!¶
Warning
Version 0.3.0 is not compatible with any of previous versions, see Changelog section for a list of changes.
Contents¶
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.
Features¶
- User Registration with activation
- Login/Logout
- Retrieve/Update the Django User model
- Password change
- Password reset via e-mail
- Social Media authentication
Apps structure¶
- rest_auth has basic auth functionality like login, logout, password reset and password change
- rest_auth.registration has logic related with registration and social media authentication
Angular app¶
- Tivix has also created angular module which uses API endpoints from this app - angular-django-registration-auth
Demo project¶
- You can also check our Demo Project which is using jQuery on frontend.
Installation¶
- Install package:
pip install django-rest-auth
- Add rest_auth app to INSTALLED_APPS in your django settings.py:
INSTALLED_APPS = (
...,
'rest_framework',
'rest_framework.authtoken',
...,
'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
- Add rest_auth urls:
urlpatterns = patterns('',
...,
(r'^rest-auth/', include('rest_auth.urls'))
)
You’re good to go now!
Registration (optional)¶
- If you want to enable standard registration process you will need to install django-allauth - see this doc for installation http://django-allauth.readthedocs.org/en/latest/installation.html.
- Add allauth, allauth.account and rest_auth.registration apps to INSTALLED_APPS in your django settings.py:
INSTALLED_APPS = (
...,
'allauth',
'allauth.account',
'rest_auth.registration',
)
- Add rest_auth.registration urls:
urlpatterns = patterns('',
...,
(r'^rest-auth/', include('rest_auth.urls'))
(r'^rest-auth/registration/', include('rest_auth.registration.urls'))
)
API endpoints¶
Basic¶
/rest-auth/login/ (POST)
- username (string)
- password (string)
/rest-auth/logout/ (POST)
/rest-auth/password/reset/ (POST)
/rest-auth/password/reset/confirm/ (POST)
- uid
- token
- new_password1
- new_password2
Note
uid and token are sent in email after calling /rest-auth/password/reset/
/rest-auth/password/change/ (POST)
- new_password1
- new_password2
/rest-auth/user/ (GET)
/rest-auth/user/ (PUT/PATCH)
- username
- first_name
- last_name
Registration¶
/rest-auth/registration/ (POST)
- username
- password1
- password2
Note
This endpoint is based on allauth.account.views.SignupView and uses the same form as in this view. To override fields you have to create custom Signup Form and define it in django settings:
ACCOUNT_FORMS = { 'signup': 'path.to.custom.SignupForm' }
See allauth documentation for more details.
/rest-auth/registration/verify-email/ (POST)
- key
Social Media Authentication¶
Basing on example from installation section Installation
/rest-auth/facebook/ (POST)
- access_token
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.Login, default value rest_auth.serializers.LoginSerializer
- TOKEN_SERIALIZER - response for successful authentication in rest_auth.views.Login, default value rest_auth.serializers.TokenSerializer
- USER_DETAILS_SERIALIZER - serializer class in rest_auth.views.UserDetails, default value rest_auth.serializers.UserDetailsSerializer
- PASSWORD_RESET_SERIALIZER - serializer class in rest_auth.views.PasswordReset, default value rest_auth.serializers.PasswordResetSerializer
- PASSWORD_RESET_CONFIRM_SERIALIZER - serializer class in rest_auth.views.PasswordResetConfirm, default value rest_auth.serializers.PasswordResetConfirmSerializer
- PASSWORD_CHANGE_SERIALIZER - serializer class in rest_auth.views.PasswordChange, 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)
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¶
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
Changelog¶
0.3.1¶
- added old_password field in PasswordChangeSerializer
- make all endpoints browsable
- removed LoggedInRESTAPIView, LoggedOutRESTAPIView
- fixed minor bugs
0.3.0¶
- replaced django-registration with django-allauth
- moved registration logic to separated django application (rest_auth.registration)
- added serializers customization in django settings
- added social media authentication view
- changed request method from GET to POST in logout endpoint
- changed request method from POST to PUT/PATCH for user details edition
- changed password reset confim url - uid and token should be sent in POST
- increase test coverage
- made compatibile with django 1.7
- removed user profile support
Social Authenitcation (optional)¶
Using django-allauth, django-rest-auth provides helpful class for creating social media authentication view. Below is an example with Facebook authentication.
Note
Points 1, 2 and 3 are related with django-allauth configuration, so if you have already configured social authentication, then please go to step 4. See django-allauth documentation for more details.