{"id":15025824,"url":"https://github.com/realmteam/django-rest-framework-social-oauth2","last_synced_at":"2025-04-08T12:09:35.175Z","repository":{"id":28126831,"uuid":"31625947","full_name":"RealmTeam/django-rest-framework-social-oauth2","owner":"RealmTeam","description":"python-social-auth and oauth2 support for django-rest-framework","archived":false,"fork":false,"pushed_at":"2024-01-12T15:05:08.000Z","size":80,"stargazers_count":1059,"open_issues_count":44,"forks_count":191,"subscribers_count":30,"default_branch":"master","last_synced_at":"2024-10-29T17:41:36.658Z","etag":null,"topics":["django","django-rest-framework","oauth2","python","python-social-auth"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RealmTeam.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2015-03-03T22:54:10.000Z","updated_at":"2024-10-09T18:11:08.000Z","dependencies_parsed_at":"2024-04-18T17:57:56.605Z","dependency_job_id":"ce21c8fb-847f-40a6-ab83-9f3008d2ff1f","html_url":"https://github.com/RealmTeam/django-rest-framework-social-oauth2","commit_stats":{"total_commits":63,"total_committers":29,"mean_commits":"2.1724137931034484","dds":0.7142857142857143,"last_synced_commit":"61b45b46630df6e89245e2b29cc5924b8f0225bf"},"previous_names":["philipgarnero/django-rest-framework-social-oauth2"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RealmTeam%2Fdjango-rest-framework-social-oauth2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RealmTeam%2Fdjango-rest-framework-social-oauth2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RealmTeam%2Fdjango-rest-framework-social-oauth2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RealmTeam%2Fdjango-rest-framework-social-oauth2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RealmTeam","download_url":"https://codeload.github.com/RealmTeam/django-rest-framework-social-oauth2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247838444,"owners_count":21004580,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["django","django-rest-framework","oauth2","python","python-social-auth"],"created_at":"2024-09-24T20:03:05.674Z","updated_at":"2025-04-08T12:09:35.155Z","avatar_url":"https://github.com/RealmTeam.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Django REST Framework Social OAuth2\n===================================\n\n.. image:: https://badge.fury.io/py/django-rest-framework-social-oauth2.svg\n    :target: http://badge.fury.io/py/django-rest-framework-social-oauth2\n\nThis module provides OAuth2 social authentication support for applications in Django REST Framework.\n\nThe aim of this package is to help set up social authentication for your REST API. It also helps setting up your OAuth2 provider.\n\nThis package relies on `python-social-auth \u003chttp://python-social-auth.readthedocs.io\u003e`_ and `django-oauth-toolkit \u003chttps://django-oauth-toolkit.readthedocs.org\u003e`_.\nYou should probably read their docs if you were to go further than what is done here.\nIf you have some hard time understanding OAuth2, you can read a simple explanation `here \u003chttps://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified\u003e`_.\n\n\nInstallation\n------------\n\nInstall with pip::\n\n    pip install django-rest-framework-social-oauth2\n\n\nAdd the following to your ``INSTALLED_APPS``:\n\n.. code-block:: python\n\n    INSTALLED_APPS = (\n        ...\n        'oauth2_provider',\n        'social_django',\n        'rest_framework_social_oauth2',\n    )\n\n\nInclude social auth urls to your urls.py:\n\n.. code-block:: python\n\n    urlpatterns = patterns(\n        ...\n        (r'^auth/', include('rest_framework_social_oauth2.urls')),\n    )\n\n\nAdd these context processors to your ``TEMPLATE_CONTEXT_PROCESSORS``:\n\n.. code-block:: python\n\n    TEMPLATE_CONTEXT_PROCESSORS = (\n        ...\n        'social_django.context_processors.backends',\n        'social_django.context_processors.login_redirect',\n    )\n\nNB: since Django version 1.8, the ``TEMPLATE_CONTEXT_PROCESSORS`` is deprecated, set the ``'context_processors'`` option in the ``'OPTIONS'`` of a DjangoTemplates backend instead:\n\n.. code-block:: python\n\n    TEMPLATES = [\n        {\n            ...\n            'OPTIONS': {\n                'context_processors': [\n                    ...\n                    'social_django.context_processors.backends',\n                    'social_django.context_processors.login_redirect',\n                ],\n            },\n        }\n    ]\n\n\nYou can then enable the authentication classes for Django REST Framework by default or per view (add or update the ``REST_FRAMEWORK`` and ``AUTHENTICATION_BACKENDS`` entries in your settings.py)\n\n.. code-block:: python\n\n    REST_FRAMEWORK = {\n        ...\n        'DEFAULT_AUTHENTICATION_CLASSES': (\n            ...\n            # 'oauth2_provider.ext.rest_framework.OAuth2Authentication',  # django-oauth-toolkit \u003c 1.0.0\n            'oauth2_provider.contrib.rest_framework.OAuth2Authentication',  # django-oauth-toolkit \u003e= 1.0.0\n            'rest_framework_social_oauth2.authentication.SocialAuthentication',\n        ),\n    }\n\n.. code-block:: python\n\n    AUTHENTICATION_BACKENDS = (\n        ...\n       'rest_framework_social_oauth2.backends.DjangoOAuth2',\n       'django.contrib.auth.backends.ModelBackend',\n    )\n\n\nThe settings of this  app are:\n\n- ``DRFSO2_PROPRIETARY_BACKEND_NAME``: name of your OAuth2 social backend (e.g ``\"Facebook\"``), defaults to ``\"Django\"``\n- ``DRFSO2_URL_NAMESPACE``: namespace for reversing URLs\n\nSetting Up a New Application\n----------------------------\n\nGo to Django admin and add a new Application with the following configuration:\n\n- ``client_id`` and ``client_secret`` should be left unchanged\n- ``user`` should be your superuser\n- ``redirect_uris`` should be left blank\n- ``client_type`` should be set to ``confidential``\n- ``authorization_grant_type`` should be set to ``'Resource owner password-based'``\n- ``name`` can be set to whatever you'd like\n\nThe installation is done, you can now test the newly configured application.\n\nIt is recommended that you read the docs from `python-social-auth` and `django-oauth-toolkit` if you would like to go further. If you want to enable a social backend (e.g. Facebook), check the docs of `python-social-auth` on `supported backends \u003chttp://python-social-auth.readthedocs.io/en/latest/backends/index.html#supported-backends\u003e`_ and `django-social-auth` on `backend configuration \u003chttp://python-social-auth.readthedocs.io/en/latest/configuration/django.html\u003e`_.\n\n\nTesting the Setup\n-----------------\n\nNow that the installation is done, let's try out the various functionality.\nWe will assume for the following examples that the REST API is reachable on ``http://localhost:8000``.\n\n- Retrieve a token for a user using ``curl``::\n\n    curl -X POST -d \"client_id=\u003cclient_id\u003e\u0026client_secret=\u003cclient_secret\u003e\u0026grant_type=password\u0026username=\u003cuser_name\u003e\u0026password=\u003cpassword\u003e\" http://localhost:8000/auth/token\n\n``\u003cclient_id\u003e`` and ``\u003cclient_secret\u003e`` are the keys generated automatically. you can find in the model Application you created.\n\n-  Refresh token::\n\n    curl -X POST -d \"grant_type=refresh_token\u0026client_id=\u003cclient_id\u003e\u0026client_secret=\u003cclient_secret\u003e\u0026refresh_token=\u003cyour_refresh_token\u003e\" http://localhost:8000/auth/token\n\n- Exchange an external token for a token linked to your app::\n\n    curl -X POST -d \"grant_type=convert_token\u0026client_id=\u003cclient_id\u003e\u0026client_secret=\u003cclient_secret\u003e\u0026backend=\u003cbackend\u003e\u0026token=\u003cbackend_token\u003e\" http://localhost:8000/auth/convert-token\n\n``\u003cbackend\u003e`` here needs to be replaced by the name of an enabled backend (e.g. \"Facebook\"). Note that ``PROPRIETARY_BACKEND_NAME`` is a valid backend name, but there is no use to do that here.\n``\u003cbackend_token\u003e`` is for the token you got from the service utilizing an iOS app for example.\n\n- Revoke tokens:\n\n    Revoke a single token::\n\n        curl -X POST -d \"client_id=\u003cclient_id\u003e\u0026client_secret=\u003cclient_secret\u003e\u0026token=\u003cyour_token\u003e\" http://localhost:8000/auth/revoke-token\n\n    Revoke all tokens for a user::\n\n        curl -H \"Authorization: Bearer \u003ctoken\u003e\" -X POST -d \"client_id=\u003cclient_id\u003e\" http://localhost:8000/auth/invalidate-sessions\n\n\nAuthenticating Requests\n-----------------------\n\nAs you have probably noticed, we enabled a default authentication backend called ``SocialAuthentication``.\nThis backend lets you register and authenticate your users seamlessly with your REST API.\n\nThe class simply retrieves the backend name and token from the Authorization header and tries to authenticate the user using the corresponding external provider. If the user was not yet registered on your app, it will automatically create a new user for this purpose.\n\nExample authenticated request::\n\n    curl -H \"Authorization: Bearer \u003cbackend_name\u003e \u003cbackend_token\u003e\" http://localhost:8000/route/to/your/view\n\n\nIntegration Examples\n--------------------\n\nFor each authentication provider, the top portion of your REST API settings.py file should look like this:\n\n.. code-block:: python\n\n    INSTALLED_APPS = (\n        ...\n        # OAuth\n        'oauth2_provider',\n        'social_django',\n        'rest_framework_social_oauth2',\n    )\n\n    TEMPLATES = [\n        {\n            ...\n            'OPTIONS': {\n                'context_processors': [\n                    ...\n                    # OAuth\n                    'social_django.context_processors.backends',\n                    'social_django.context_processors.login_redirect',\n                ],\n            },\n        }\n    ]\n\n    REST_FRAMEWORK = {\n        ...\n        'DEFAULT_AUTHENTICATION_CLASSES': (\n            ...\n            # OAuth\n            # 'oauth2_provider.ext.rest_framework.OAuth2Authentication',  # django-oauth-toolkit \u003c 1.0.0\n            'oauth2_provider.contrib.rest_framework.OAuth2Authentication',  # django-oauth-toolkit \u003e= 1.0.0\n            'rest_framework_social_oauth2.authentication.SocialAuthentication',\n        )\n    }\n\nListed below are a few examples of supported backends that can be used for social authentication.\n\n\nFacebook Example\n^^^^^^^^^^^^^^^^\n\nTo use Facebook as the authorization backend of your REST API, your settings.py file should look like this:\n\n.. code-block:: python\n\n    AUTHENTICATION_BACKENDS = (\n        # Others auth providers (e.g. Google, OpenId, etc)\n        ...\n\n        # Facebook OAuth2\n        'social_core.backends.facebook.FacebookAppOAuth2',\n        'social_core.backends.facebook.FacebookOAuth2',\n\n        # django-rest-framework-social-oauth2\n        'rest_framework_social_oauth2.backends.DjangoOAuth2',\n\n        # Django\n        'django.contrib.auth.backends.ModelBackend',\n    )\n\n    # Facebook configuration\n    SOCIAL_AUTH_FACEBOOK_KEY = '\u003cyour app id goes here\u003e'\n    SOCIAL_AUTH_FACEBOOK_SECRET = '\u003cyour app secret goes here\u003e'\n\n    # Define SOCIAL_AUTH_FACEBOOK_SCOPE to get extra permissions from Facebook.\n    # Email is not sent by default, to get it, you must request the email permission.\n    SOCIAL_AUTH_FACEBOOK_SCOPE = ['email']\n    SOCIAL_AUTH_FACEBOOK_PROFILE_EXTRA_PARAMS = {\n        'fields': 'id, name, email'\n    }\n\nRemember to add this new Application in your Django admin (see section \"Setting up Application\").\n\nYou can test these settings by running the following command::\n\n    curl -X POST -d \"grant_type=convert_token\u0026client_id=\u003cclient_id\u003e\u0026client_secret=\u003cclient_secret\u003e\u0026backend=facebook\u0026token=\u003cfacebook_token\u003e\" http://localhost:8000/auth/convert-token\n\nThis request returns the \"access_token\" that you should use with every HTTP request to your REST API. What is happening here is that we are converting a third-party access token (``\u003cuser_access_token\u003e``) to an access token to use with your API and its clients (\"access_token\"). You should use this token on each and further communications between your system/application and your api to authenticate each request and avoid authenticating with Facebook every time.\n\nYou can get the ID (``SOCIAL_AUTH_FACEBOOK_KEY``) and secret (``SOCIAL_AUTH_FACEBOOK_SECRET``) of your app at https://developers.facebook.com/apps/.\n\nFor testing purposes, you can use the access token ``\u003cuser_access_token\u003e`` from https://developers.facebook.com/tools/accesstoken/.\n\nFor more information on how to configure python-social-auth with Facebook visit http://python-social-auth.readthedocs.io/en/latest/backends/facebook.html.\n\n\nGoogle Example\n^^^^^^^^^^^^^^\n\nTo use Google OAuth2 as the authorization backend of your REST API, your settings.py file should look like this:\n\n.. code-block:: python\n\n    AUTHENTICATION_BACKENDS = (\n        # Others auth providers (e.g. Facebook, OpenId, etc)\n        ...\n\n\t# Google OAuth2\n\t'social_core.backends.google.GoogleOAuth2',\n\n        # django-rest-framework-social-oauth2\n        'rest_framework_social_oauth2.backends.DjangoOAuth2',\n\n        # Django\n        'django.contrib.auth.backends.ModelBackend',\n    )\n\n    # Google configuration\n    SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = \u003cyour app id goes here\u003e\n    SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = \u003cyour app secret goes here\u003e\n\n    # Define SOCIAL_AUTH_GOOGLE_OAUTH2_SCOPE to get extra permissions from Google.\n    SOCIAL_AUTH_GOOGLE_OAUTH2_SCOPE = [\n        'https://www.googleapis.com/auth/userinfo.email',\n        'https://www.googleapis.com/auth/userinfo.profile',\n    ]\n\nRemember to add the new Application in your Django admin (see section \"Setting up Application\").\n\nYou can test these settings by running the following command::\n\n    curl -X POST -d \"grant_type=convert_token\u0026client_id=\u003cdjango-oauth-generated-client_id\u003e\u0026client_secret=\u003cdjango-oauth-generated-client_secret\u003e\u0026backend=google-oauth2\u0026token=\u003cgoogle_token\u003e\" http://localhost:8000/auth/convert-token\n\nThis request returns an \"access_token\" that you should use with every HTTP requests to your REST API. What is happening here is that we are converting a third-party access token (``\u003cuser_access_token\u003e``) to an access token to use with your API and its clients (\"access_token\"). You should use this token on each and further communications between your system/application and your API to authenticate each request and avoid authenticating with Google every time.\n\nYou can get the ID (``SOCIAL_AUTH_GOOGLE_OAUTH2_KEY``) and secret (``SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET``) of your app at https://console.developers.google.com/apis/credentials\nand more information on how to create one on https://developers.google.com/identity/protocols/OAuth2.\n\nFor testing purposes, you can use the access token ``\u003cuser_access_token\u003e`` from https://developers.google.com/oauthplayground/.\n\nFor more information on how to configure python-social-auth with Google visit https://python-social-auth.readthedocs.io/en/latest/backends/google.html#google-oauth2.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frealmteam%2Fdjango-rest-framework-social-oauth2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frealmteam%2Fdjango-rest-framework-social-oauth2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frealmteam%2Fdjango-rest-framework-social-oauth2/lists"}