REST version of Django authentication system.
Project description
# djoser
[![Build Status](https://travis-ci.org/sunscrapers/djoser.svg?branch=master)](https://travis-ci.org/sunscrapers/djoser)
REST version of [Django](https://www.djangoproject.com/) authentication system.
**djoser** is set of [Django Rest Framework](http://www.django-rest-framework.org/)
views to handle such things as registration, login and password reset. It
works with [custom user model](https://docs.djangoproject.com/en/dev/topics/auth/customizing/).
Instead of reusing Django code (e.g. `PasswordResetForm`), we reimplemented
few things to fit better into [Single Page App](http://en.wikipedia.org/wiki/Single-page_application)
architecture.
Developed by [SUNSCRAPERS](http://sunscrapers.com/) with passion & patience.
Available endpoints:
* `/me`
* `/register`
* `/login`
* `/activate`
* `/{{ User.USERNAME_FIELD }}`
* `/password`
* `/password/reset`
* `/password/reset/confirm`
Supported Python versions:
* Python 2.7
* Python 3.4
Supported Django versions:
* Django 1.5
* Django 1.6
* Django 1.7
## Installation
Use `pip`:
$ pip install git+https://github.com/sunscrapers/djoser.git
## Usage
Configure `INSTALLED_APPS`:
```python
INSTALLED_APPS = (
'django.contrib.auth',
(...),
'rest_framework',
'rest_framework.authtoken',
'djoser',
(...),
)
```
Configure `urls.py`:
```python
urlpatterns = patterns('',
(...),
url(r'^auth/', include('djoser.urls')),
)
```
Optionally add `djoser` settings:
```python
DJOSER = {
'DOMAIN': 'frontend.com',
'SITE_NAME': 'Frontend',
'PASSWORD_RESET_CONFIRM_URL': '#/password/reset/confirm/{uid}/{token}',
'ACTIVATION_URL': '#/activate/{uid}/{token}',
'LOGIN_AFTER_ACTIVATION': True,
'SEND_ACTIVATION_EMAIL': True,
}
```
Check [settings](#settings) section for more info.
## Endpoints
### User
URL: `/me`
Methods: `GET`, `PUT`
`PUT` request data:
* `{{ User.REQUIRED_FIELDS }}`
`PUT` and `GET` response data:
* `{{ User.USERNAME_FIELD }}`
* `{{ User.REQUIRED_FIELDS }}`
Use this endpoint to retrieve/update user.
### Register
URL: `/register`
Methods: `POST`
`POST` request data:
* `{{ User.USERNAME_FIELD }}`
* `{{ User.REQUIRED_FIELDS }}`
* `password`
`POST` response data:
* `{{ User.USERNAME_FIELD }}`
* `{{ User.REQUIRED_FIELDS }}`
* `auth_token` (if `LOGIN_AFTER_ACTIVATION` is `True`)
Use this endpoint to register new user. Your user model manager should
implement [`create_user`](https://docs.djangoproject.com/en/dev/ref/contrib/auth/#django.contrib.auth.models.UserManager.create_user)
method and have [`USERNAME_FIELD`](https://docs.djangoproject.com/en/dev/topics/auth/customizing/#django.contrib.auth.models.CustomUser.USERNAME_FIELD)
and [`REQUIRED_FIELDS`](https://docs.djangoproject.com/en/dev/topics/auth/customizing/#django.contrib.auth.models.CustomUser.REQUIRED_FIELDS)
fields.
If `LOGIN_AFTER_ACTIVATION` is `True`, you will receive authentication token
within response.
### Login
URL: `/login`
Methods: `POST`
`POST` request data:
* `{{ User.USERNAME_FIELD }}`
* `password`
`POST` response data:
* `auth_token`
Use this endpoint to obtain user [authentication token](http://www.django-rest-framework.org/api-guide/authentication#tokenauthentication).
### Activate
URL: `/activate`
Methods: `POST`
`POST` request data:
* `uid`
* `token`
`POST` response data:
* `auth_token` (if `LOGIN_AFTER_ACTIVATION` is `True`)
Use this endpoint to activate user account.
### Set username
URL: `/{{ User.USERNAME_FIELD }}`
Methods: `POST`
`POST` request data:
* `new_{{ User.USERNAME_FIELD }}`
* `re_new_{{ User.USERNAME_FIELD }}` (if `SET_USERNAME_RETYPE` is `True`)
* `current_password`
Use this endpoint to change user username (`USERNAME_FIELD`).
### Set password
URL: `/password`
Methods: `POST`
`POST` request data:
* `new_password`
* `re_new_password` (if `SET_PASSWORD_RETYPE` is `True`)
* `current_password`
Use this endpoint to change user password.
### Reset password
URL: `/password/reset`
Methods: `POST`
`POST` request data:
* `email`
Use this endpoint to send email to user with password reset link. You have to
setup `DOMAIN`, `SITE_NAME`, `PASSWORD_RESET_CONFIRM_URL`.
### Reset password confirmation
URL: `/password/reset/confirm`
Methods: `POST`
`POST` request data:
* `uid`
* `token`
* `new_password`
* `re_new_password` (if `PASSWORD_RESET_CONFIRM_RETYPE` is `True`)
Use this endpoint to finish reset password process.
## Settings
#### `LOGIN_AFTER_REGISTRATION`
If `True`, register endpoint will return `auth_token` within response.
Default: `False`
#### `DOMAIN`
Domain of your frontend app. Default: `''`.
#### `SITE_NAME`
Name of your frontend app. Default: `''`.
#### `PASSWORD_RESET_CONFIRM_URL`
URL to your frontend password reset page. It should containt `{uid}` and
`{token}` placeholders, e.g. `#/password-reset/{uid}/{token}`. Default: `''`.
#### `SEND_ACTIVATION_EMAIL`
If `True`, register endpoint will send activation email to user.
#### `ACTIVATION_URL`
URL to your frontend activation page. It should containt `{uid}` and `{token}`
placeholders, e.g. `#/activate/{uid}/{token}`. Default: `''`.
#### `LOGIN_AFTER_ACTIVATION`
If `True`, activate endpoint will return `auth_token` within response.
Default: `False`
#### `SET_USERNAME_RETYPE`
If `True`, you need to pass `re_new_{{ User.USERNAME_FIELD }}` to
`/{{ User.USERNAME_FIELD }}` endpoint, to validate username equality.
Default: `False`
#### `SET_PASSWORD_RETYPE`
If `True`, you need to pass `re_new_password` to `/password` endpoint, to
validate password equality.
Default: `False`
#### `PASSWORD_RESET_CONFIRM_RETYPE`
If `True`, you need to pass `re_new_password` to `/password/reset/confirm`
endpoint, to validate password equality.
Default: `False`
## Emails
There are few email templates which you could override:
* `activation_email_body.txt`
* `activation_email_subject.txt`
* `password_reset_email_body.txt`
* `password_reset_email_subject.txt`
All of them have following context:
* `user`
* `domain`
* `site_name`
* `url`
* `uid`
* `token`
* `protocol`
## Customization
If you need to override some `djoser` behaviour, you could define your custom view/serializer.
Define custom urls instead of reusing `djoser.urls`:
```python
urlpatterns = patterns('',
(...),
url(r'^register$', views.CustomRegistrationView.as_view()),
)
```
Define custom view/serializer (inherit from one of `djoser` class) and override necessary method/field:
```python
class CustomRegistrationView(djoser.views.RegistrationView):
def send_email(self, *args, **kwargs):
your_custom_email_sender(*args, **kwargs)
```
You could check `djoser` API in source code:
* [`djoser.views`](https://github.com/sunscrapers/djoser/blob/master/djoser/views.py)
* [`djoser.serializers`](https://github.com/sunscrapers/djoser/blob/master/djoser/serializers.py)
## Similar projects
List of projects related to Django, REST and authentication:
- [django-rest-auth](https://github.com/Tivix/django-rest-auth)
- [django-rest-framework-digestauth](https://github.com/juanriaza/django-rest-framework-digestauth)
- [django-oauth-toolkit](https://github.com/evonove/django-oauth-toolkit)
- [doac](https://github.com/Rediker-Software/doac)
- [django-rest-framework-jwt](https://github.com/GetBlimp/django-rest-framework-jwt)
- [django-rest-framework-httpsignature](https://github.com/etoccalino/django-rest-framework-httpsignature)
- [hawkrest](https://github.com/kumar303/hawkrest)
[![Build Status](https://travis-ci.org/sunscrapers/djoser.svg?branch=master)](https://travis-ci.org/sunscrapers/djoser)
REST version of [Django](https://www.djangoproject.com/) authentication system.
**djoser** is set of [Django Rest Framework](http://www.django-rest-framework.org/)
views to handle such things as registration, login and password reset. It
works with [custom user model](https://docs.djangoproject.com/en/dev/topics/auth/customizing/).
Instead of reusing Django code (e.g. `PasswordResetForm`), we reimplemented
few things to fit better into [Single Page App](http://en.wikipedia.org/wiki/Single-page_application)
architecture.
Developed by [SUNSCRAPERS](http://sunscrapers.com/) with passion & patience.
Available endpoints:
* `/me`
* `/register`
* `/login`
* `/activate`
* `/{{ User.USERNAME_FIELD }}`
* `/password`
* `/password/reset`
* `/password/reset/confirm`
Supported Python versions:
* Python 2.7
* Python 3.4
Supported Django versions:
* Django 1.5
* Django 1.6
* Django 1.7
## Installation
Use `pip`:
$ pip install git+https://github.com/sunscrapers/djoser.git
## Usage
Configure `INSTALLED_APPS`:
```python
INSTALLED_APPS = (
'django.contrib.auth',
(...),
'rest_framework',
'rest_framework.authtoken',
'djoser',
(...),
)
```
Configure `urls.py`:
```python
urlpatterns = patterns('',
(...),
url(r'^auth/', include('djoser.urls')),
)
```
Optionally add `djoser` settings:
```python
DJOSER = {
'DOMAIN': 'frontend.com',
'SITE_NAME': 'Frontend',
'PASSWORD_RESET_CONFIRM_URL': '#/password/reset/confirm/{uid}/{token}',
'ACTIVATION_URL': '#/activate/{uid}/{token}',
'LOGIN_AFTER_ACTIVATION': True,
'SEND_ACTIVATION_EMAIL': True,
}
```
Check [settings](#settings) section for more info.
## Endpoints
### User
URL: `/me`
Methods: `GET`, `PUT`
`PUT` request data:
* `{{ User.REQUIRED_FIELDS }}`
`PUT` and `GET` response data:
* `{{ User.USERNAME_FIELD }}`
* `{{ User.REQUIRED_FIELDS }}`
Use this endpoint to retrieve/update user.
### Register
URL: `/register`
Methods: `POST`
`POST` request data:
* `{{ User.USERNAME_FIELD }}`
* `{{ User.REQUIRED_FIELDS }}`
* `password`
`POST` response data:
* `{{ User.USERNAME_FIELD }}`
* `{{ User.REQUIRED_FIELDS }}`
* `auth_token` (if `LOGIN_AFTER_ACTIVATION` is `True`)
Use this endpoint to register new user. Your user model manager should
implement [`create_user`](https://docs.djangoproject.com/en/dev/ref/contrib/auth/#django.contrib.auth.models.UserManager.create_user)
method and have [`USERNAME_FIELD`](https://docs.djangoproject.com/en/dev/topics/auth/customizing/#django.contrib.auth.models.CustomUser.USERNAME_FIELD)
and [`REQUIRED_FIELDS`](https://docs.djangoproject.com/en/dev/topics/auth/customizing/#django.contrib.auth.models.CustomUser.REQUIRED_FIELDS)
fields.
If `LOGIN_AFTER_ACTIVATION` is `True`, you will receive authentication token
within response.
### Login
URL: `/login`
Methods: `POST`
`POST` request data:
* `{{ User.USERNAME_FIELD }}`
* `password`
`POST` response data:
* `auth_token`
Use this endpoint to obtain user [authentication token](http://www.django-rest-framework.org/api-guide/authentication#tokenauthentication).
### Activate
URL: `/activate`
Methods: `POST`
`POST` request data:
* `uid`
* `token`
`POST` response data:
* `auth_token` (if `LOGIN_AFTER_ACTIVATION` is `True`)
Use this endpoint to activate user account.
### Set username
URL: `/{{ User.USERNAME_FIELD }}`
Methods: `POST`
`POST` request data:
* `new_{{ User.USERNAME_FIELD }}`
* `re_new_{{ User.USERNAME_FIELD }}` (if `SET_USERNAME_RETYPE` is `True`)
* `current_password`
Use this endpoint to change user username (`USERNAME_FIELD`).
### Set password
URL: `/password`
Methods: `POST`
`POST` request data:
* `new_password`
* `re_new_password` (if `SET_PASSWORD_RETYPE` is `True`)
* `current_password`
Use this endpoint to change user password.
### Reset password
URL: `/password/reset`
Methods: `POST`
`POST` request data:
* `email`
Use this endpoint to send email to user with password reset link. You have to
setup `DOMAIN`, `SITE_NAME`, `PASSWORD_RESET_CONFIRM_URL`.
### Reset password confirmation
URL: `/password/reset/confirm`
Methods: `POST`
`POST` request data:
* `uid`
* `token`
* `new_password`
* `re_new_password` (if `PASSWORD_RESET_CONFIRM_RETYPE` is `True`)
Use this endpoint to finish reset password process.
## Settings
#### `LOGIN_AFTER_REGISTRATION`
If `True`, register endpoint will return `auth_token` within response.
Default: `False`
#### `DOMAIN`
Domain of your frontend app. Default: `''`.
#### `SITE_NAME`
Name of your frontend app. Default: `''`.
#### `PASSWORD_RESET_CONFIRM_URL`
URL to your frontend password reset page. It should containt `{uid}` and
`{token}` placeholders, e.g. `#/password-reset/{uid}/{token}`. Default: `''`.
#### `SEND_ACTIVATION_EMAIL`
If `True`, register endpoint will send activation email to user.
#### `ACTIVATION_URL`
URL to your frontend activation page. It should containt `{uid}` and `{token}`
placeholders, e.g. `#/activate/{uid}/{token}`. Default: `''`.
#### `LOGIN_AFTER_ACTIVATION`
If `True`, activate endpoint will return `auth_token` within response.
Default: `False`
#### `SET_USERNAME_RETYPE`
If `True`, you need to pass `re_new_{{ User.USERNAME_FIELD }}` to
`/{{ User.USERNAME_FIELD }}` endpoint, to validate username equality.
Default: `False`
#### `SET_PASSWORD_RETYPE`
If `True`, you need to pass `re_new_password` to `/password` endpoint, to
validate password equality.
Default: `False`
#### `PASSWORD_RESET_CONFIRM_RETYPE`
If `True`, you need to pass `re_new_password` to `/password/reset/confirm`
endpoint, to validate password equality.
Default: `False`
## Emails
There are few email templates which you could override:
* `activation_email_body.txt`
* `activation_email_subject.txt`
* `password_reset_email_body.txt`
* `password_reset_email_subject.txt`
All of them have following context:
* `user`
* `domain`
* `site_name`
* `url`
* `uid`
* `token`
* `protocol`
## Customization
If you need to override some `djoser` behaviour, you could define your custom view/serializer.
Define custom urls instead of reusing `djoser.urls`:
```python
urlpatterns = patterns('',
(...),
url(r'^register$', views.CustomRegistrationView.as_view()),
)
```
Define custom view/serializer (inherit from one of `djoser` class) and override necessary method/field:
```python
class CustomRegistrationView(djoser.views.RegistrationView):
def send_email(self, *args, **kwargs):
your_custom_email_sender(*args, **kwargs)
```
You could check `djoser` API in source code:
* [`djoser.views`](https://github.com/sunscrapers/djoser/blob/master/djoser/views.py)
* [`djoser.serializers`](https://github.com/sunscrapers/djoser/blob/master/djoser/serializers.py)
## Similar projects
List of projects related to Django, REST and authentication:
- [django-rest-auth](https://github.com/Tivix/django-rest-auth)
- [django-rest-framework-digestauth](https://github.com/juanriaza/django-rest-framework-digestauth)
- [django-oauth-toolkit](https://github.com/evonove/django-oauth-toolkit)
- [doac](https://github.com/Rediker-Software/doac)
- [django-rest-framework-jwt](https://github.com/GetBlimp/django-rest-framework-jwt)
- [django-rest-framework-httpsignature](https://github.com/etoccalino/django-rest-framework-httpsignature)
- [hawkrest](https://github.com/kumar303/hawkrest)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
djoser-0.0.1.tar.gz
(7.8 kB
view hashes)