Django REST social auth
=======================
[](https://github.com/st4lk/django-rest-social-auth/actions/workflows/lint.yml?query=branch%3Amaster)
[](https://github.com/st4lk/django-rest-social-auth/actions/workflows/test.yml?query=branch%3Amaster)
[](https://coveralls.io/github/st4lk/django-rest-social-auth?branch=master)
[](https://pypi.python.org/pypi/rest_social_auth)
[](https://pepy.tech/project/rest-social-auth)
OAuth signin with django rest framework.
Requirements
-----------
- python (3.7, 3.8, 3.9, 3.10, 3.11)
- django (3.2, 4.1, 4.2)
- djangorestframework (>=3.9, <4.0)
- social-auth-core (>=4.3, <5.0)
- social-auth-app-django (>=5.0, <6.0)
- [optional] djangorestframework-simplejwt (>=5.0.0)
- [optional] django-rest-knox (>=4.0.0, <5.0.0)
Release notes
-------------
[Here](https://github.com/st4lk/django-rest-social-auth/blob/master/RELEASE_NOTES.md)
Motivation
----------
To have a resource, that will do very simple thing:
take the [oauth code](https://tools.ietf.org/html/rfc6749#section-1.3.1) from social provider (for example facebook)
and return the authenticated user.
That's it.
I can't find such util for [django rest framework](http://www.django-rest-framework.org/).
There are packages (for example [django-rest-auth](https://github.com/Tivix/django-rest-auth)), that take [access_token](https://tools.ietf.org/html/rfc6749#section-1.4), not the [code](https://tools.ietf.org/html/rfc6749#section-1.3.1).
Also, i've used to work with awesome library [python-social-auth](https://github.com/omab/python-social-auth),
so it will be nice to use it again (now it is split into [social-core](https://github.com/python-social-auth/social-core) and [social-app-django](https://github.com/python-social-auth/social-app-django)). In fact, most of the work is done by this package.
Current util brings a little help to integrate django-rest-framework and python-social-auth.
Quick start
-----------
1. Install this package to your python distribution:
```bash
pip install rest-social-auth
```
2. Do the settings
Install apps
```python
INSTALLED_APPS = (
...
'rest_framework',
'rest_framework.authtoken', # only if you use token authentication
'social_django', # django social auth
'rest_social_auth', # this package
'knox', # Only if you use django-rest-knox
)
```
social auth settings, look [documentation](http://python-social-auth.readthedocs.io/en/latest/configuration/django.html) for more details
```python
SOCIAL_AUTH_FACEBOOK_KEY = 'your app client id'
SOCIAL_AUTH_FACEBOOK_SECRET = 'your app client secret'
SOCIAL_AUTH_FACEBOOK_SCOPE = ['email', ] # optional
SOCIAL_AUTH_FACEBOOK_PROFILE_EXTRA_PARAMS = {'locale': 'ru_RU'} # optional
AUTHENTICATION_BACKENDS = (
'social_core.backends.facebook.FacebookOAuth2',
# and maybe some others ...
'django.contrib.auth.backends.ModelBackend',
)
```
Also look [optional settings](#settings) avaliable.
3. Make sure everything is up do date
```bash
python manage.py migrate
```
4. Include rest social urls (choose at least one)
4.1 [session authentication](http://www.django-rest-framework.org/api-guide/authentication/#sessionauthentication)
```python
path('api/login/', include('rest_social_auth.urls_session')),
```
4.2 [token authentication](http://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication)
```python
path('api/login/', include('rest_social_auth.urls_token')),
```
4.3 [jwt authentication](https://github.com/davesque/django-rest-framework-simplejwt)
```python
path('api/login/', include('rest_social_auth.urls_jwt_pair')),
```
or / and
```python
path('api/login/', include('rest_social_auth.urls_jwt_sliding')),
```
4.4 [knox authentication](https://github.com/James1345/django-rest-knox/)
```python
path('api/login/', include('rest_social_auth.urls_knox')),
```
5. You are ready to login users
Following examples are for OAuth 2.0.
5.1 session authentication
- POST /api/login/social/session/
input:
{
"provider": "facebook",
"code": "AQBPBBTjbdnehj51"
}
output:
{
"username": "Alex",
"email": "user@email.com",
// other user data
}
+ session id in cookies
5.2 token authentication
- POST /api/login/social/token/
input:
{
"provider": "facebook",
"code": "AQBPBBTjbdnehj51"
}
output:
{
"token": "68ded41d89f6a28da050f882998b2ea1decebbe0"
}
- POST /api/login/social/token_user/
input:
{
"provider": "facebook",
"code": "AQBPBBTjbdnehj51"
}
output:
{
"username": "Alex",
"email": "user@email.com",
// other user data
"token": "68ded41d89f6a28da050f882998b2ea1decebbe0"
}
5.3 jwt authentication (using [django-rest-framework-simplejwt](https://github.com/davesque/django-rest-framework-simplejwt))
- POST /api/login/social/jwt-pair/
- POST /api/login/social/jwt-pair-user/
Similar to token authentication, but token is JSON Web Token.
See [JWT.io](http://jwt.io/) for details.
To use it, django-rest-framework-simplejwt must be installed.
For `jwt-pair`, the response will include additional "refresh" token:
```json
{
"token": "...",
"refresh": "..."
}
```
##### Or sliding JWT token:
- POST /api/login/social/jwt-sliding/
- POST /api/login/social/jwt-sliding-user/
Check [docs of simplejwt](https://github.com/davesque/django-rest-framework-simplejwt#token-types) for pair/sliding token difference.
Note. `django-rest-framework-simplejwt` doesn't work on python3.6
5.4 knox authentication
- POST /api/login/social/knox/
- POST /api/login/social/knox_user/
Similar to token authentication, but token is Django Rest Knox Token.
To use it, [django-rest-knox](https://github.com/James1345/django-rest-knox/) must be installed.
User model is taken from [`settings.AUTH_USER_MODEL`](https://docs.djangoproject.com/en/dev/topics/auth/customizing/#substituting-a-custom-user-model).
At input there is also non-required field `redirect_uri`.
If given, server will use this redirect uri in requests, instead of uri
got from settings.
This redirect_uri must be equal in front-end request and in back-end request.
Back-end will not do any redirect in fact.
It is also possible to specify provider in URL, not in request body.
Just append it to the url:
POST /api/login/social/session/facebook/
Don't need to specify it in body now:
{
"code": "AQBPBBTjbdnehj51"
}
Provider defined in URL has higher priority than provider in body.
If both are specified - provider will be taken from URL.
OAuth 2.0 workflow with rest-social-auth
-----------------------------------------
1. Front-end need to know following params for each social provider:
- client_id _# only in case of OAuth 2.0, id of registered application on social service provider_
- redirect_uri _# to this url social provider will redirect with code_
- scope=your_scope _# for example email_
- response_type=code _# same for all oauth2.0 providers_
2. Front-end redirect user to social authorize url with params from previous point.
3. User confirms.
4. Social provider redirects back to `redirect_uri` with param `code`.
5. Front-end now ready to login the user. To do it, send POST request with provider name and code:
POST /api/login/social/session/
with data (form data or json)
provider=facebook&code=AQBPBBTjbdnehj51
Backend will either signin the user, either signup, either return error.
Sometimes it is more suitable to specify provider in url, not in request body.
It is possible, rest-social-auth will understand that.
Following request is the same as above:
POST /api/login/social/session/facebook/
with data (form data or json)
code=AQBPBBTjbdnehj51
OAuth 1.0a workflow with rest-social-auth
-----------------------------------------
1. Front-end needs to make a POST request to your backend with the provider name ONLY:
POST /api/login/social/
with data (form data or json):
provider=twitter
Or specify provider in url, in that case data will be empty:
POST /api/login/social/twitter
2. The backend will return a short-lived `oauth_token` request token in the response. This can be used by the front-end to perform authentication with the provider.
3. User confirms. In the case of Twitter, they will then return the following data to your front-end:
{
"redirect_state": "...bHrz2x0wy43",
"oauth_token" : "...AAAAAAAhD5u",
"oauth_verifier": "...wDBdTR7CYdR"
}
4. Front-end now ready to login the user. To do it, send POST request again with provider name and the `oauth_token` and `oauth_verifier` you got from the provider:
POST /api/login/social/
with data (form data or json)
provider=twitter&oauth_token=AQBPBBTjbdnehj51&oauth_verifier=wDBdTR7CYdR
Backend will either signin the user, or signup, or return an error.
Same as in OAuth 2.0, you can specify provider in url, not in body:
POST /api/login/social/twitter
This flow is the same as described in [satellizer](https://github.com/sahat/satellizer#-login-with-oauth-10). This angularjs module is used in example project.
rest-social-auth purpose
------------------------
As we can see, our backend must implement resource for signin the user.
Django REST social auth provides means to easily implement such resource.
List of oauth providers
-----------------------
OAuth 1.0 and OAuth 2.0 providers are supported.
Look [python-social-auth](http://python-social-auth.readthedocs.io/en/latest/backends/index.html#social-backends) for full list.
Name of provider is taken from corresponding `backend.name` property of
particular backed class in python-social-auth.
For example for [facebook backend](https://github.com/python-social-auth/social-core/blob/master/social_core/backends/facebook.py#L22)
we see:
class FacebookOAuth2(BaseOAuth2):
name = 'facebook'
Here are some provider names:
Provider | provider name
--------- | -------------
Facebook | facebook
Google | google-oauth2
Vkontakte | vk-oauth2
Instagram | instagram
Github | github
Yandex | yandex-oauth2
Twitter | twitter
[Others](http://python-social-auth.readthedocs.io/en/latest/backends/index.html#social-backends) | [...](http://python-social-auth.readthedocs.io/en/latest/backends/index.html#social-backends)
Settings
--------
- `REST_SOCIAL_OAUTH_REDIRECT_URI`
Default: `'/'`
Defines redirect_uri. This redirect must be the same in both authorize request (made by front-end) and access token request (made by back-end) to OAuth provider.
To override the relative path (url path or url name are both supported):
REST_SOCIAL_OAUTH_REDIRECT_URI = '/oauth/redirect/path/'
# or url name
REST_SOCIAL_OAUTH_REDIRECT_URI = 'redirect_url_name'
Note, in case of url name, backend name will be provided to url resolver as argument.
- `REST_SOCIAL_DOMAIN_FROM_ORIGIN`
Default: `True`
Sometimes front-end and back-end are run on different domains.
For example frontend at 'myproject.com', and backend at 'api.myproject.com'.
If True, domain will be taken from request origin, if origin is defined.
So in current example domain will be 'myproject.com', not 'api.myproject.com'.
Next, this domain will be joined with path from `REST_SOCIAL_OAUTH_REDIRECT_URI` settings.
To be clear, suppose we have following settings (defaults):
REST_SOCIAL_OAUTH_REDIRECT_URI = '/'
REST_SOCIAL_DOMAIN_FROM_ORIGIN = True
Front-end is running on domain 'myproject.com', back-end - on 'api.myproject.com'.
Back-end will use following redirect_uri:
myproject.com/
And with following settings:
REST_SOCIAL_OAUTH_REDIRECT_URI = '/'
REST_SOCIAL_DOMAIN_FROM_ORIGIN = False
redirect_uri will be:
api.myproject.com/
Also look at [django-cors-headers](https://github.com/ottoyiu/django-cors-headers) if such architecture is your case.
- `REST_SOCIAL_OAUTH_ABSOLUTE_REDIRECT_URI`
Default: `None`
Full redirect uri (domain and path) can be hardcoded
REST_SOCIAL_OAUTH_ABSOLUTE_REDIRECT_URI = 'http://myproject.com/'
This settings has higher priority than `REST_SOCIAL_OAUTH_REDIRECT_URI` and `REST_SOCIAL_DOMAIN_FROM_ORIGIN`.
I.e. if this settings is defined, other will be ignored.
But `redirect_uri` param from request has higher priority than any setting.
- `REST_SOCIAL_LOG_AUTH_EXCEPTIONS`
Default: `True`
When `False` will not log social auth authentication exceptions.
- `REST_SOCIAL_VERBOSE_ERRORS`
Default: `False`
When `True` the API will return error message received from server. Can be potentially unsecure to turn it ON.
- `SOCIAL_AUTH_STRATEGY`
Default: `'rest_social_auth.strategy.DRFStrategy'`
Override [strategy](https://python-social-auth.readthedocs.io/en/latest/strategies.html) for python-social-auth.
Customization
-------------
First of all, customization provided by python-social-auth is also avaliable.
For example, use nice mechanism of [pipeline](http://python-social-auth.readthedocs.io/en/latest/pipeline.html) to do any action you need during login/signin.
Second, you can override any method from current package.
Specify serializer for each view by subclassing the view.
To do it
- define your own url:
path('api/login/social/$', MySocialView.as_view(), name='social_login'),
- define your serializer
from rest_framework import serializers
from django.contrib.auth import get_user_model
class MyUserSerializer(serializers.ModelSerializer):
class Meta:
model = get_user_model()
exclude = ('password', 'user_permissions', 'groups')
- define view
from rest_social_auth.views import SocialSessionAuthView
from .serializers import MyUserSerializer
class MySocialView(SocialSessionAuthView):
serializer_class = MyUserSerializer
Check the code of the lib, there is not much of it.
Example
-------
There is an [example project](https://github.com/st4lk/django-rest-social-auth/tree/master/example_project).
- clone repo
```bash
git clone https://github.com/st4lk/django-rest-social-auth.git
```
- run example project
```bash
make
```
It is assumed, that you have:
- [make](https://www.gnu.org/software/make/)
- [docker](https://www.docker.com/)
- open [https://127.0.0.1:8000/](https://127.0.0.1:8000/) in your browser
Note: `runsslserver` is used instead of built-in `runserver` to serve the project with TLS (aka SSL) certificate.
HTTPS is required by some social providers (facebook), without it they won't work.
The certificate will not be trusted by your system - that is expected.
Just tell your browser to proceed with this untrusted certificate - it is acceptable for development purposes.
In Chrome browser it can look like this:
- step 1: [image](https://user-images.githubusercontent.com/1771042/71641969-90ab7280-2cd6-11ea-95ed-de4c6e123345.png)
- step 2: [image](https://user-images.githubusercontent.com/1771042/71641970-91440900-2cd6-11ea-9275-f6c351ddc543.png)
More details [here](https://github.com/teddziuba/django-sslserver#browser-certificate-errors).
Facebook, Google and Twitter auth should work, all secret keys are already set.
Example project uses [satellizer](https://github.com/sahat/satellizer) angularjs module.
Development
-----------
Run tests locally
```bash
make test
```
Run tests in all enviroments (can take some time)
```bash
make test-tox
```
Contributors
------------
Thanks to all contributors!
<a href="https://github.com/st4lk/django-rest-social-auth/graphs/contributors">
<img src="https://contributors-img.web.app/image?repo=st4lk/django-rest-social-auth" />
</a>
- Alexey Evseev, [st4lk](https://github.com/st4lk)
- James Keys, [skolsuper](https://github.com/skolsuper)
- Aaron Abbott, [aabmass](https://github.com/aabmass)
- Grigorii Eremeev, [Budulianin](https://github.com/Budulianin)
- shubham, [shubh3794](https://github.com/shubh3794)
- Deshraj Yadav, [DESHRAJ](https://github.com/DESHRAJ)
- georgewhewell, [georgewhewell](https://github.com/georgewhewell)
- Ahmed Sa3d, [zee93](https://github.com/zee93)
- Olle Vidner, [ovidner](https://github.com/ovidner)
- MounirMesselmeni, [MounirMesselmeni](https://github.com/MounirMesselmeni)
- Tuomas Virtanen, [katajakasa](https://github.com/katajakasa)
- Jeremy Storer, [storerjeremy](https://github.com/storerjeremy)
- Jeffrey de Lange, [jgadelange](https://github.com/jgadelange)
- John Vandenberg, [jayvdb](https://github.com/jayvdb)
- Anton_Datsik, [AntonDatsik](https://github.com/AntonDatsik)
- Netizen29, [Netizen29](https://github.com/Netizen29)
- Dipendra Raj Panta, [Mr-DRP](https://github.com/Mr-DRP)
- JD, [jd-0001](https://github.com/jd-0001)
- Harsh Patel, [eelectronn](https://github.com/eelectronn)
- Devid, [sevdog](https://github.com/sevdog)
- Anton Yakovlev, [sputnik5459](https://github.com/sputnik5459)
- Olivér Kecskeméty, [KOliver94](https://github.com/KOliver94)
- vainu-arto, [vainu-arto](https://github.com/vainu-arto)
rest_social_auth release notes
==============================
v8.1.0
------
- Add support of Django 4.2
- Add support of Python 3.11
v8.0.0
------
- Drop support of Python 3.6
- Drop support of Django 3.0, 3.1
- Add support of Django 4.1
- Add support of Python 3.10
- Allow customized implementations of djangorestframework-simplejwt token class
- Add `REST_SOCIAL_VERBOSE_ERRORS` setting
v7.0.0
------
- Add support of social-auth-app-django==5.x
- Add support of Django 3.2
- Drop support of social-auth-app-django<5.0
v6.0.1
------
- Fix processing error from social provider #144
v6.0.0
------
- Add support of social-auth-core==4.0
- Add support of social-auth-app-django==4.0
- Drop support of Python 3.5
- Drop support of social-auth-core<4.0
- Drop support of social-auth-app-django<4.0
v5.0.1
------
- Expect error without response during error handling
v5.0.0
------
- Update user serializer: exclude field only if it was defined in customer user model
- Include error message from social provider into HTTP response of API
- Use `path()` django function instead of deprecated `url()`
- Drop support of Django 1.11
- Drop support of Python 2.7
- Drop support of deprecated `djangorestframework-jwt` dependency
- Add support of Django 3.1
Issues: #137
v4.2.0
------
- Take provider name from URL first
Issues: #121
v4.1.0
------
- Allow to specify custom strategy for python-social-auth
v4.0.0
------
- Update supported version of django-rest-knox (>=4.0.0, <5.0.0). v4 has breaking changes.
- Allow to use token auth with OAuth1 without django session enabled
Issues: #110
v3.0.0
------
- Add Django 3.0 support
- Add Python 3.8 support
- Drop Django 2.0, 2.1 support
- Fix facebook integration in example project: serve with fake TLS certificate
Issues: #104, #106
v2.2.0
------
- Update license, use MIT
- Add Django 2.2 support
- Fix customer redirect URI for OAuth1
- Cleanup knox integration
v2.1.0
------
- Use djangorestframework-simplejwt for JWT implementation
- Deprecate djangorestframework-jwt
- Add python3.7 support
Issues: #74
v2.0.2
------
- Make social-auth-core >=3.0 as mandatory dependency
v2.0.1
------
- Minor update of pypi deployment process
v2.0.0
------
- Update social-auth-core dependency to at least 3.0.0
Issues: #73
v1.5.0
------
- Update minimal required version of social-auth-app-django to 3.1.0
- Minor updates in readme
- Add Django 2.1 support
- Drop Django 1.10 support
- Drop Python 3.4 support
Issues: #70
v1.4.0
------
- Add django-rest-knox support
v1.3.1
------
- Fix Django 2.0 support
v1.3.0
------
- Add Django 2.0 support
- Drop Django 1.8, 1.9 support
Issues: #58
v1.2.0
------
- Add Python 3.6 and Django 1.11 support
Issues #54
v1.1.0
------
- Update docs
- Add new setting `REST_SOCIAL_LOG_AUTH_EXCEPTIONS`
Issues #42
v1.0.0
------
- Add Django 1.10 support
- Drop Django 1.7 support
- Add social-auth-core, social-auth-app-django dependencies
- Drop python-social-auth dependency
Issues: #33, #35, #37, #38
v0.5.0
------
- Handle HttpResponses returned by the pipeline
Issues: #28
v0.4.4
------
- Log exceptions from python-social-auth
- Don't use find_packages from setuptools
Issues: #22, #25
v0.4.3
------
- Fix queryset assert error
- minor typo fixes
Issues: #20
v0.4.2
------
- Remove django.conf.urls.patterns from code
- Exclude modifing immutable data
- refactor tests
- minor typo fixes
Issues: #11, #17, #14
v0.4.1
------
- Fix requirements.txt: allow django==1.9
v0.4.0
------
- Add [JSON Web Tokens](http://jwt.io/) using [djangorestframework-jwt](https://github.com/GetBlimp/django-rest-framework-jwt)
- Add Python 3.5 and Django 1.9 support
Issues: #6
v0.3.1
------
- Explicitly set token authentication for token views
v0.3.0
------
- Add support for Oauth1
- Add ability to override request parsing
- Allow to specify provider in url
- Drop Python 2.6 and Django 1.6 support
Issues: #2, #3, #5
v0.2.0
------
- Get domain from HTTP Origin
- Add example of Google OAuth2.0
- Add manual redirect uri (front-end can specify it)
- Use GenericAPIView instead of APIView
- Main serializer is output serializer, not input
- Update docs
- Minor code fixes
v0.1.0
------
First version in pypi
Raw data
{
"_id": null,
"home_page": "https://github.com/st4lk/django-rest-social-auth",
"name": "rest-social-auth",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "django,social,auth,rest,login,signin,signup,oauth",
"author": "st4lk",
"author_email": "alexevseev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d1/f3/f916adf100fcc656183ca44adad518731d406cbe2731fc8546eaafc51045/rest_social_auth-8.1.0.tar.gz",
"platform": "Any",
"description": "Django REST social auth\n=======================\n\n[](https://github.com/st4lk/django-rest-social-auth/actions/workflows/lint.yml?query=branch%3Amaster)\n[](https://github.com/st4lk/django-rest-social-auth/actions/workflows/test.yml?query=branch%3Amaster)\n[](https://coveralls.io/github/st4lk/django-rest-social-auth?branch=master)\n[](https://pypi.python.org/pypi/rest_social_auth)\n[](https://pepy.tech/project/rest-social-auth)\n\n\nOAuth signin with django rest framework.\n\n\nRequirements\n-----------\n\n- python (3.7, 3.8, 3.9, 3.10, 3.11)\n- django (3.2, 4.1, 4.2)\n- djangorestframework (>=3.9, <4.0)\n- social-auth-core (>=4.3, <5.0)\n- social-auth-app-django (>=5.0, <6.0)\n- [optional] djangorestframework-simplejwt (>=5.0.0)\n- [optional] django-rest-knox (>=4.0.0, <5.0.0)\n\nRelease notes\n-------------\n\n[Here](https://github.com/st4lk/django-rest-social-auth/blob/master/RELEASE_NOTES.md)\n\n\nMotivation\n----------\n\nTo have a resource, that will do very simple thing:\ntake the [oauth code](https://tools.ietf.org/html/rfc6749#section-1.3.1) from social provider (for example facebook)\nand return the authenticated user.\nThat's it.\n\nI can't find such util for [django rest framework](http://www.django-rest-framework.org/).\nThere are packages (for example [django-rest-auth](https://github.com/Tivix/django-rest-auth)), that take [access_token](https://tools.ietf.org/html/rfc6749#section-1.4), not the [code](https://tools.ietf.org/html/rfc6749#section-1.3.1).\nAlso, i've used to work with awesome library [python-social-auth](https://github.com/omab/python-social-auth),\nso it will be nice to use it again (now it is split into [social-core](https://github.com/python-social-auth/social-core) and [social-app-django](https://github.com/python-social-auth/social-app-django)). In fact, most of the work is done by this package.\nCurrent util brings a little help to integrate django-rest-framework and python-social-auth.\n\nQuick start\n-----------\n\n1. Install this package to your python distribution:\n\n ```bash\n pip install rest-social-auth\n ```\n\n2. Do the settings\n\n\n Install apps\n\n ```python\n INSTALLED_APPS = (\n ...\n 'rest_framework',\n 'rest_framework.authtoken', # only if you use token authentication\n 'social_django', # django social auth\n 'rest_social_auth', # this package\n 'knox', # Only if you use django-rest-knox\n )\n ```\n\n social auth settings, look [documentation](http://python-social-auth.readthedocs.io/en/latest/configuration/django.html) for more details\n\n ```python\n SOCIAL_AUTH_FACEBOOK_KEY = 'your app client id'\n SOCIAL_AUTH_FACEBOOK_SECRET = 'your app client secret'\n SOCIAL_AUTH_FACEBOOK_SCOPE = ['email', ] # optional\n SOCIAL_AUTH_FACEBOOK_PROFILE_EXTRA_PARAMS = {'locale': 'ru_RU'} # optional\n\n\n AUTHENTICATION_BACKENDS = (\n 'social_core.backends.facebook.FacebookOAuth2',\n # and maybe some others ...\n 'django.contrib.auth.backends.ModelBackend',\n )\n ```\n\n Also look [optional settings](#settings) avaliable.\n\n3. Make sure everything is up do date\n\n ```bash\n python manage.py migrate\n ```\n\n\n4. Include rest social urls (choose at least one)\n\n 4.1 [session authentication](http://www.django-rest-framework.org/api-guide/authentication/#sessionauthentication)\n\n ```python\n path('api/login/', include('rest_social_auth.urls_session')),\n ```\n\n 4.2 [token authentication](http://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication)\n\n ```python\n path('api/login/', include('rest_social_auth.urls_token')),\n ```\n\n 4.3 [jwt authentication](https://github.com/davesque/django-rest-framework-simplejwt)\n\n ```python\n path('api/login/', include('rest_social_auth.urls_jwt_pair')),\n ```\n\n or / and\n\n ```python\n path('api/login/', include('rest_social_auth.urls_jwt_sliding')),\n ```\n\n 4.4 [knox authentication](https://github.com/James1345/django-rest-knox/)\n\n ```python\n path('api/login/', include('rest_social_auth.urls_knox')),\n ```\n\n5. You are ready to login users\n\n Following examples are for OAuth 2.0.\n\n 5.1 session authentication\n\n - POST /api/login/social/session/\n\n input:\n\n {\n \"provider\": \"facebook\",\n \"code\": \"AQBPBBTjbdnehj51\"\n }\n\n output:\n\n {\n \"username\": \"Alex\",\n \"email\": \"user@email.com\",\n // other user data\n }\n\n + session id in cookies\n\n 5.2 token authentication\n\n - POST /api/login/social/token/\n\n input:\n\n {\n \"provider\": \"facebook\",\n \"code\": \"AQBPBBTjbdnehj51\"\n }\n\n output:\n\n {\n \"token\": \"68ded41d89f6a28da050f882998b2ea1decebbe0\"\n }\n\n - POST /api/login/social/token_user/\n\n input:\n\n {\n \"provider\": \"facebook\",\n \"code\": \"AQBPBBTjbdnehj51\"\n }\n\n output:\n\n {\n \"username\": \"Alex\",\n \"email\": \"user@email.com\",\n // other user data\n \"token\": \"68ded41d89f6a28da050f882998b2ea1decebbe0\"\n }\n\n 5.3 jwt authentication (using [django-rest-framework-simplejwt](https://github.com/davesque/django-rest-framework-simplejwt))\n\n - POST /api/login/social/jwt-pair/\n - POST /api/login/social/jwt-pair-user/\n\n Similar to token authentication, but token is JSON Web Token.\n\n See [JWT.io](http://jwt.io/) for details.\n\n To use it, django-rest-framework-simplejwt must be installed.\n\n For `jwt-pair`, the response will include additional \"refresh\" token:\n ```json\n {\n \"token\": \"...\",\n \"refresh\": \"...\"\n }\n ```\n\n ##### Or sliding JWT token:\n\n - POST /api/login/social/jwt-sliding/\n - POST /api/login/social/jwt-sliding-user/\n\n Check [docs of simplejwt](https://github.com/davesque/django-rest-framework-simplejwt#token-types) for pair/sliding token difference.\n\n Note. `django-rest-framework-simplejwt` doesn't work on python3.6\n\n 5.4 knox authentication\n\n - POST /api/login/social/knox/\n - POST /api/login/social/knox_user/\n\n Similar to token authentication, but token is Django Rest Knox Token.\n\n To use it, [django-rest-knox](https://github.com/James1345/django-rest-knox/) must be installed.\n\n\n User model is taken from [`settings.AUTH_USER_MODEL`](https://docs.djangoproject.com/en/dev/topics/auth/customizing/#substituting-a-custom-user-model).\n\n At input there is also non-required field `redirect_uri`.\n If given, server will use this redirect uri in requests, instead of uri\n got from settings.\n This redirect_uri must be equal in front-end request and in back-end request.\n Back-end will not do any redirect in fact.\n\n It is also possible to specify provider in URL, not in request body.\n Just append it to the url:\n\n POST /api/login/social/session/facebook/\n\n Don't need to specify it in body now:\n\n {\n \"code\": \"AQBPBBTjbdnehj51\"\n }\n\n Provider defined in URL has higher priority than provider in body.\n If both are specified - provider will be taken from URL.\n\n\nOAuth 2.0 workflow with rest-social-auth\n-----------------------------------------\n1. Front-end need to know following params for each social provider:\n - client_id _# only in case of OAuth 2.0, id of registered application on social service provider_\n - redirect_uri _# to this url social provider will redirect with code_\n - scope=your_scope _# for example email_\n - response_type=code _# same for all oauth2.0 providers_\n\n2. Front-end redirect user to social authorize url with params from previous point.\n\n3. User confirms.\n\n4. Social provider redirects back to `redirect_uri` with param `code`.\n\n5. Front-end now ready to login the user. To do it, send POST request with provider name and code:\n\n POST /api/login/social/session/\n\n with data (form data or json)\n\n provider=facebook&code=AQBPBBTjbdnehj51\n\n Backend will either signin the user, either signup, either return error.\n\n Sometimes it is more suitable to specify provider in url, not in request body.\n It is possible, rest-social-auth will understand that.\n Following request is the same as above:\n\n POST /api/login/social/session/facebook/\n\n with data (form data or json)\n\n code=AQBPBBTjbdnehj51\n\n\nOAuth 1.0a workflow with rest-social-auth\n-----------------------------------------\n1. Front-end needs to make a POST request to your backend with the provider name ONLY:\n\n POST /api/login/social/\n\n with data (form data or json):\n\n provider=twitter\n\n Or specify provider in url, in that case data will be empty:\n\n POST /api/login/social/twitter\n\n2. The backend will return a short-lived `oauth_token` request token in the response. This can be used by the front-end to perform authentication with the provider.\n\n3. User confirms. In the case of Twitter, they will then return the following data to your front-end:\n\n {\n \"redirect_state\": \"...bHrz2x0wy43\",\n \"oauth_token\" : \"...AAAAAAAhD5u\",\n \"oauth_verifier\": \"...wDBdTR7CYdR\"\n }\n\n4. Front-end now ready to login the user. To do it, send POST request again with provider name and the `oauth_token` and `oauth_verifier` you got from the provider:\n\n POST /api/login/social/\n\n with data (form data or json)\n\n provider=twitter&oauth_token=AQBPBBTjbdnehj51&oauth_verifier=wDBdTR7CYdR\n\n Backend will either signin the user, or signup, or return an error.\n Same as in OAuth 2.0, you can specify provider in url, not in body:\n\n POST /api/login/social/twitter\n\nThis flow is the same as described in [satellizer](https://github.com/sahat/satellizer#-login-with-oauth-10). This angularjs module is used in example project.\n\n\nrest-social-auth purpose\n------------------------\n\nAs we can see, our backend must implement resource for signin the user.\n\nDjango REST social auth provides means to easily implement such resource.\n\n\nList of oauth providers\n-----------------------\n\nOAuth 1.0 and OAuth 2.0 providers are supported.\n\nLook [python-social-auth](http://python-social-auth.readthedocs.io/en/latest/backends/index.html#social-backends) for full list.\nName of provider is taken from corresponding `backend.name` property of\nparticular backed class in python-social-auth.\n\nFor example for [facebook backend](https://github.com/python-social-auth/social-core/blob/master/social_core/backends/facebook.py#L22)\nwe see:\n\n class FacebookOAuth2(BaseOAuth2):\n name = 'facebook'\n\nHere are some provider names:\n\nProvider | provider name\n--------- | -------------\nFacebook | facebook\nGoogle | google-oauth2\nVkontakte | vk-oauth2\nInstagram | instagram\nGithub | github\nYandex | yandex-oauth2\nTwitter | twitter\n[Others](http://python-social-auth.readthedocs.io/en/latest/backends/index.html#social-backends) | [...](http://python-social-auth.readthedocs.io/en/latest/backends/index.html#social-backends)\n\n\nSettings\n--------\n\n- `REST_SOCIAL_OAUTH_REDIRECT_URI`\n\n Default: `'/'`\n\n Defines redirect_uri. This redirect must be the same in both authorize request (made by front-end) and access token request (made by back-end) to OAuth provider.\n\n To override the relative path (url path or url name are both supported):\n\n REST_SOCIAL_OAUTH_REDIRECT_URI = '/oauth/redirect/path/'\n # or url name\n REST_SOCIAL_OAUTH_REDIRECT_URI = 'redirect_url_name'\n\n Note, in case of url name, backend name will be provided to url resolver as argument.\n\n- `REST_SOCIAL_DOMAIN_FROM_ORIGIN`\n\n Default: `True`\n\n Sometimes front-end and back-end are run on different domains.\n For example frontend at 'myproject.com', and backend at 'api.myproject.com'.\n\n If True, domain will be taken from request origin, if origin is defined.\n So in current example domain will be 'myproject.com', not 'api.myproject.com'.\n Next, this domain will be joined with path from `REST_SOCIAL_OAUTH_REDIRECT_URI` settings.\n\n To be clear, suppose we have following settings (defaults):\n\n REST_SOCIAL_OAUTH_REDIRECT_URI = '/'\n REST_SOCIAL_DOMAIN_FROM_ORIGIN = True\n\n Front-end is running on domain 'myproject.com', back-end - on 'api.myproject.com'.\n Back-end will use following redirect_uri:\n\n myproject.com/\n\n And with following settings:\n\n REST_SOCIAL_OAUTH_REDIRECT_URI = '/'\n REST_SOCIAL_DOMAIN_FROM_ORIGIN = False\n\n redirect_uri will be:\n\n api.myproject.com/\n\n Also look at [django-cors-headers](https://github.com/ottoyiu/django-cors-headers) if such architecture is your case.\n\n- `REST_SOCIAL_OAUTH_ABSOLUTE_REDIRECT_URI`\n\n Default: `None`\n\n Full redirect uri (domain and path) can be hardcoded\n\n REST_SOCIAL_OAUTH_ABSOLUTE_REDIRECT_URI = 'http://myproject.com/'\n\n This settings has higher priority than `REST_SOCIAL_OAUTH_REDIRECT_URI` and `REST_SOCIAL_DOMAIN_FROM_ORIGIN`.\n I.e. if this settings is defined, other will be ignored.\n But `redirect_uri` param from request has higher priority than any setting.\n\n- `REST_SOCIAL_LOG_AUTH_EXCEPTIONS`\n\n Default: `True`\n\n When `False` will not log social auth authentication exceptions.\n\n- `REST_SOCIAL_VERBOSE_ERRORS`\n\n Default: `False`\n\n When `True` the API will return error message received from server. Can be potentially unsecure to turn it ON.\n\n- `SOCIAL_AUTH_STRATEGY`\n\n Default: `'rest_social_auth.strategy.DRFStrategy'`\n\n Override [strategy](https://python-social-auth.readthedocs.io/en/latest/strategies.html) for python-social-auth.\n\n\nCustomization\n-------------\n\nFirst of all, customization provided by python-social-auth is also avaliable.\nFor example, use nice mechanism of [pipeline](http://python-social-auth.readthedocs.io/en/latest/pipeline.html) to do any action you need during login/signin.\n\nSecond, you can override any method from current package.\nSpecify serializer for each view by subclassing the view.\n\nTo do it\n\n- define your own url:\n\n path('api/login/social/$', MySocialView.as_view(), name='social_login'),\n\n- define your serializer\n\n from rest_framework import serializers\n from django.contrib.auth import get_user_model\n\n class MyUserSerializer(serializers.ModelSerializer):\n\n class Meta:\n model = get_user_model()\n exclude = ('password', 'user_permissions', 'groups')\n\n- define view\n\n from rest_social_auth.views import SocialSessionAuthView\n from .serializers import MyUserSerializer\n\n class MySocialView(SocialSessionAuthView):\n serializer_class = MyUserSerializer\n\nCheck the code of the lib, there is not much of it.\n\n\nExample\n-------\n\nThere is an [example project](https://github.com/st4lk/django-rest-social-auth/tree/master/example_project).\n\n- clone repo\n\n ```bash\n git clone https://github.com/st4lk/django-rest-social-auth.git\n ```\n\n- run example project\n\n ```bash\n make\n ```\n\n It is assumed, that you have:\n - [make](https://www.gnu.org/software/make/)\n - [docker](https://www.docker.com/)\n\n- open [https://127.0.0.1:8000/](https://127.0.0.1:8000/) in your browser\n\n Note: `runsslserver` is used instead of built-in `runserver` to serve the project with TLS (aka SSL) certificate.\n HTTPS is required by some social providers (facebook), without it they won't work.\n The certificate will not be trusted by your system - that is expected.\n Just tell your browser to proceed with this untrusted certificate - it is acceptable for development purposes.\n\n In Chrome browser it can look like this:\n - step 1: [image](https://user-images.githubusercontent.com/1771042/71641969-90ab7280-2cd6-11ea-95ed-de4c6e123345.png)\n - step 2: [image](https://user-images.githubusercontent.com/1771042/71641970-91440900-2cd6-11ea-9275-f6c351ddc543.png)\n\n More details [here](https://github.com/teddziuba/django-sslserver#browser-certificate-errors).\n\nFacebook, Google and Twitter auth should work, all secret keys are already set.\n\nExample project uses [satellizer](https://github.com/sahat/satellizer) angularjs module.\n\nDevelopment\n-----------\n\nRun tests locally\n\n```bash\nmake test\n```\n\nRun tests in all enviroments (can take some time)\n\n```bash\nmake test-tox\n```\n\nContributors\n------------\n\nThanks to all contributors!\n\n<a href=\"https://github.com/st4lk/django-rest-social-auth/graphs/contributors\">\n <img src=\"https://contributors-img.web.app/image?repo=st4lk/django-rest-social-auth\" />\n</a>\n\n- Alexey Evseev, [st4lk](https://github.com/st4lk)\n- James Keys, [skolsuper](https://github.com/skolsuper)\n- Aaron Abbott, [aabmass](https://github.com/aabmass)\n- Grigorii Eremeev, [Budulianin](https://github.com/Budulianin)\n- shubham, [shubh3794](https://github.com/shubh3794)\n- Deshraj Yadav, [DESHRAJ](https://github.com/DESHRAJ)\n- georgewhewell, [georgewhewell](https://github.com/georgewhewell)\n- Ahmed Sa3d, [zee93](https://github.com/zee93)\n- Olle Vidner, [ovidner](https://github.com/ovidner)\n- MounirMesselmeni, [MounirMesselmeni](https://github.com/MounirMesselmeni)\n- Tuomas Virtanen, [katajakasa](https://github.com/katajakasa)\n- Jeremy Storer, [storerjeremy](https://github.com/storerjeremy)\n- Jeffrey de Lange, [jgadelange](https://github.com/jgadelange)\n- John Vandenberg, [jayvdb](https://github.com/jayvdb)\n- Anton_Datsik, [AntonDatsik](https://github.com/AntonDatsik)\n- Netizen29, [Netizen29](https://github.com/Netizen29)\n- Dipendra Raj Panta, [Mr-DRP](https://github.com/Mr-DRP)\n- JD, [jd-0001](https://github.com/jd-0001)\n- Harsh Patel, [eelectronn](https://github.com/eelectronn)\n- Devid, [sevdog](https://github.com/sevdog)\n- Anton Yakovlev, [sputnik5459](https://github.com/sputnik5459)\n- Oliv\u00e9r Kecskem\u00e9ty, [KOliver94](https://github.com/KOliver94)\n- vainu-arto, [vainu-arto](https://github.com/vainu-arto)\n\n\nrest_social_auth release notes\n==============================\n\nv8.1.0\n------\n- Add support of Django 4.2\n- Add support of Python 3.11\n\nv8.0.0\n------\n- Drop support of Python 3.6\n- Drop support of Django 3.0, 3.1\n- Add support of Django 4.1\n- Add support of Python 3.10\n- Allow customized implementations of djangorestframework-simplejwt token class\n- Add `REST_SOCIAL_VERBOSE_ERRORS` setting\n\nv7.0.0\n------\n- Add support of social-auth-app-django==5.x\n- Add support of Django 3.2\n- Drop support of social-auth-app-django<5.0\n\nv6.0.1\n------\n- Fix processing error from social provider #144\n\nv6.0.0\n------\n- Add support of social-auth-core==4.0\n- Add support of social-auth-app-django==4.0\n- Drop support of Python 3.5\n- Drop support of social-auth-core<4.0\n- Drop support of social-auth-app-django<4.0\n\nv5.0.1\n------\n- Expect error without response during error handling\n\nv5.0.0\n------\n- Update user serializer: exclude field only if it was defined in customer user model\n- Include error message from social provider into HTTP response of API\n- Use `path()` django function instead of deprecated `url()`\n- Drop support of Django 1.11\n- Drop support of Python 2.7\n- Drop support of deprecated `djangorestframework-jwt` dependency\n- Add support of Django 3.1\n\nIssues: #137\n\nv4.2.0\n------\n- Take provider name from URL first\n\nIssues: #121\n\nv4.1.0\n------\n- Allow to specify custom strategy for python-social-auth\n\nv4.0.0\n------\n- Update supported version of django-rest-knox (>=4.0.0, <5.0.0). v4 has breaking changes.\n- Allow to use token auth with OAuth1 without django session enabled\n\nIssues: #110\n\nv3.0.0\n------\n- Add Django 3.0 support\n- Add Python 3.8 support\n- Drop Django 2.0, 2.1 support\n- Fix facebook integration in example project: serve with fake TLS certificate\n\nIssues: #104, #106\n\nv2.2.0\n------\n- Update license, use MIT\n- Add Django 2.2 support\n- Fix customer redirect URI for OAuth1\n- Cleanup knox integration\n\nv2.1.0\n------\n- Use djangorestframework-simplejwt for JWT implementation\n- Deprecate djangorestframework-jwt\n- Add python3.7 support\n\nIssues: #74\n\nv2.0.2\n------\n- Make social-auth-core >=3.0 as mandatory dependency \n\nv2.0.1\n------\n- Minor update of pypi deployment process\n\nv2.0.0\n------\n- Update social-auth-core dependency to at least 3.0.0\n\nIssues: #73\n\nv1.5.0\n------\n- Update minimal required version of social-auth-app-django to 3.1.0\n- Minor updates in readme\n- Add Django 2.1 support\n- Drop Django 1.10 support\n- Drop Python 3.4 support\n\nIssues: #70\n\nv1.4.0\n------\n- Add django-rest-knox support\n\nv1.3.1\n------\n- Fix Django 2.0 support\n\nv1.3.0\n------\n- Add Django 2.0 support\n- Drop Django 1.8, 1.9 support\n\nIssues: #58\n\nv1.2.0\n------\n- Add Python 3.6 and Django 1.11 support\n\nIssues #54\n\nv1.1.0\n------\n- Update docs\n- Add new setting `REST_SOCIAL_LOG_AUTH_EXCEPTIONS`\n\nIssues #42\n\nv1.0.0\n------\n- Add Django 1.10 support\n- Drop Django 1.7 support\n- Add social-auth-core, social-auth-app-django dependencies\n- Drop python-social-auth dependency\n\nIssues: #33, #35, #37, #38\n\nv0.5.0\n------\n- Handle HttpResponses returned by the pipeline\n\nIssues: #28\n\nv0.4.4\n------\n- Log exceptions from python-social-auth\n- Don't use find_packages from setuptools\n\nIssues: #22, #25\n\nv0.4.3\n------\n- Fix queryset assert error\n- minor typo fixes\n\nIssues: #20\n\nv0.4.2\n------\n- Remove django.conf.urls.patterns from code\n- Exclude modifing immutable data\n- refactor tests\n- minor typo fixes\n\nIssues: #11, #17, #14\n\nv0.4.1\n------\n- Fix requirements.txt: allow django==1.9\n\nv0.4.0\n------\n- Add [JSON Web Tokens](http://jwt.io/) using [djangorestframework-jwt](https://github.com/GetBlimp/django-rest-framework-jwt)\n- Add Python 3.5 and Django 1.9 support\n\nIssues: #6\n\nv0.3.1\n------\n- Explicitly set token authentication for token views\n\nv0.3.0\n------\n- Add support for Oauth1\n- Add ability to override request parsing\n- Allow to specify provider in url\n- Drop Python 2.6 and Django 1.6 support\n\nIssues: #2, #3, #5\n\nv0.2.0\n------\n- Get domain from HTTP Origin\n- Add example of Google OAuth2.0\n- Add manual redirect uri (front-end can specify it)\n- Use GenericAPIView instead of APIView\n- Main serializer is output serializer, not input\n- Update docs\n- Minor code fixes\n\nv0.1.0\n------\n\nFirst version in pypi\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "Django rest framework resources for social auth",
"version": "8.1.0",
"project_urls": {
"Homepage": "https://github.com/st4lk/django-rest-social-auth"
},
"split_keywords": [
"django",
"social",
"auth",
"rest",
"login",
"signin",
"signup",
"oauth"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "48b4209651cdfecd58812cc71ec1501482498f625f64449c3af72d367f3dc13c",
"md5": "1056af143dc00d177ddf4f5766fd7d32",
"sha256": "c4ce361ed9ddb0078bfea23ac6b0718fd9049fd4e7819621e7dbc1b3fbfb3fc0"
},
"downloads": -1,
"filename": "rest_social_auth-8.1.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "1056af143dc00d177ddf4f5766fd7d32",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 16921,
"upload_time": "2023-06-13T21:07:47",
"upload_time_iso_8601": "2023-06-13T21:07:47.485748Z",
"url": "https://files.pythonhosted.org/packages/48/b4/209651cdfecd58812cc71ec1501482498f625f64449c3af72d367f3dc13c/rest_social_auth-8.1.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d1f3f916adf100fcc656183ca44adad518731d406cbe2731fc8546eaafc51045",
"md5": "551c1af7d43b064139468d154381124b",
"sha256": "b6c28f3e41aa1723ed33fa2f73128ffa30593d00f3e0f7308255fca7aef3a067"
},
"downloads": -1,
"filename": "rest_social_auth-8.1.0.tar.gz",
"has_sig": false,
"md5_digest": "551c1af7d43b064139468d154381124b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22467,
"upload_time": "2023-06-13T21:01:33",
"upload_time_iso_8601": "2023-06-13T21:01:33.382450Z",
"url": "https://files.pythonhosted.org/packages/d1/f3/f916adf100fcc656183ca44adad518731d406cbe2731fc8546eaafc51045/rest_social_auth-8.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-13 21:01:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "st4lk",
"github_project": "django-rest-social-auth",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "rest-social-auth"
}
JSON
