python-social-auth · nijel · Jun 24, 2026 · Jun 24, 2026
diff --git a/docs/backends/salesforce.rst b/docs/backends/salesforce.rst
@@ -35,8 +35,12 @@ Salesforce uses OAuth v2 for Authentication, check the `official docs`_.
             ...
         )
 
-- Then you can start using ``{% url social:begin 'salesforce-oauth2' %}`` in
-  your templates
+- Then you can start authentication from your templates with a POST form::
+
+        <form method="post" action="{% url 'social:begin' 'salesforce-oauth2' %}">
+            {% csrf_token %}
+            <button type="submit">Sign in with Salesforce</button>
+        </form>
 
 
 If using the sandbox mode:
@@ -54,8 +58,12 @@ If using the sandbox mode:
             ...
         )
 
-- Then you can start using ``{% url social:begin 'salesforce-oauth2-sandbox' %}``
-  in your templates
+- Then you can start authentication from your templates with a POST form::
+
+        <form method="post" action="{% url 'social:begin' 'salesforce-oauth2-sandbox' %}">
+            {% csrf_token %}
+            <button type="submit">Sign in with Salesforce Sandbox</button>
+        </form>
 
 .. _official docs: https://www.salesforce.com/us/developer/docs/api_rest/Content/intro_understanding_web_server_oauth_flow.htm
 .. _Defining Connected Apps: https://www.salesforce.com/us/developer/docs/api_rest/Content/intro_defining_remote_access_applications.htm
diff --git a/docs/backends/saml.rst b/docs/backends/saml.rst
@@ -193,22 +193,19 @@ Basic Usage
   must install and configure your metadata on their system before it will work.
 
 - Now everything is set! To allow users to login with any given IdP, you need to
-  give them a link to the python-social-auth "begin"/"auth" URL and include an
-  ``idp`` query parameter that specifies the name of the IdP to use. This is
-  needed since the backend supports multiple IdPs. The names of the IdPs are the
-  keys used in the ``SOCIAL_AUTH_SAML_ENABLED_IDPS`` setting.
+  submit the python-social-auth "begin"/"auth" URL and include an ``idp``
+  parameter that specifies the name of the IdP to use. This is needed since the
+  backend supports multiple IdPs. The names of the IdPs are the keys used in the
+  ``SOCIAL_AUTH_SAML_ENABLED_IDPS`` setting.
 
   Django example::
 
-      # In view:
-      context['testshib_url'] = u"{base}?{params}".format(
-          base=reverse('social:begin', kwargs={'backend': 'saml'}),
-          params=urllib.urlencode({'next': '/home', 'idp': 'testshib'})
-      )
-      # In template:
-      <a href="{{ testshib_url }}">TestShib Login</a>
-      # Result:
-      <a href="/login/saml/?next=%2Fhome&amp;idp=testshib">TestShib Login</a>
+      <form method="post" action="{% url 'social:begin' 'saml' %}">
+          {% csrf_token %}
+          <input type="hidden" name="next" value="/home">
+          <input type="hidden" name="idp" value="testshib">
+          <button type="submit">TestShib Login</button>
+      </form>
 
 - Testing with the TestShib_ provider is recommended, as it is known to work
   well.

diff --git a/docs/backends/twilio.rst b/docs/backends/twilio.rst
@@ -29,9 +29,12 @@ setting.
 
     'social_core.backends.twilio.TwilioAuth',
 
-- Usage example::
+- Usage example for Django templates::
 
-    <a href="/login/twilio">Enter using Twilio</a>
+    <form method="post" action="{% url 'social:begin' 'twilio' %}">
+        {% csrf_token %}
+        <button type="submit">Enter using Twilio</button>
+    </form>
 
 
 .. _Twilio Connect API: https://www.twilio.com/user/account/connect/apps
diff --git a/docs/backends/untappd.rst b/docs/backends/untappd.rst
@@ -41,8 +41,12 @@ Untappd uses OAuth v2 for Authentication, check the `official docs`_.
             ...
         )
 
-- Then you can start using ``{% url social:begin 'untappd' %}`` in
-  your templates
+- Then you can start authentication from your templates with a POST form::
+
+        <form method="post" action="{% url 'social:begin' 'untappd' %}">
+            {% csrf_token %}
+            <button type="submit">Sign in with Untappd</button>
+        </form>
 
 .. _official docs: https://untappd.com/api/docs
 .. _Add App: https://untappd.com/api/register?register=new
diff --git a/docs/backends/vk.rst b/docs/backends/vk.rst
@@ -36,7 +36,12 @@ VK.com uses OAuth2 for Authentication.
 
 - Add ``'social_core.backends.vk.VKOAuth2'`` into your ``SOCIAL_AUTH_AUTHENTICATION_BACKENDS``.
 
-- Then you can start using ``/login/vk-oauth2`` in your link href.
+- Then you can start authentication from your templates with a POST form::
+
+      <form method="post" action="{% url 'social:begin' 'vk-oauth2' %}">
+          {% csrf_token %}
+          <button type="submit">Sign in with VK</button>
+      </form>
 
 - Also it's possible to define extra permissions with::
 

diff --git a/docs/configuration/django.rst b/docs/configuration/django.rst
@@ -17,11 +17,15 @@ And for MongoEngine_ ORM::
 
     $ pip install social-auth-app-django-mongoengine
 
+Current ``social-auth-app-django`` releases follow supported Django versions
+and require Django 5.2 or newer and Python 3.10 or newer.
+
 
 Quickstart
 ----------
 
-This quickstart covers the essential configuration to get social authentication working in your Django project.
+This quickstart covers the essential configuration to get social authentication
+working in your Django project.
 
 **1. Add to INSTALLED_APPS**::
 
@@ -49,7 +53,9 @@ This is where you configure your ``client_id``, ``client_secret``, and ``scope``
         'https://www.googleapis.com/auth/userinfo.profile',
     ]
 
-For other providers, the pattern is ``SOCIAL_AUTH_<PROVIDER>_KEY``, ``SOCIAL_AUTH_<PROVIDER>_SECRET``, and ``SOCIAL_AUTH_<PROVIDER>_SCOPE``. See :doc:`/backends/index` for provider-specific settings.
+For other providers, the pattern is ``SOCIAL_AUTH_<PROVIDER>_KEY``,
+``SOCIAL_AUTH_<PROVIDER>_SECRET``, and ``SOCIAL_AUTH_<PROVIDER>_SCOPE``. See
+:doc:`/backends/index` for provider-specific settings.
 
 .. warning::
    Never commit credentials to version control. Use environment variables instead::
@@ -75,12 +81,17 @@ For other providers, the pattern is ``SOCIAL_AUTH_<PROVIDER>_KEY``, ``SOCIAL_AUT
 
     python manage.py migrate
 
-**7. Add login link in template**::
+**7. Add login form in template**::
 
-    <a href="{% url 'social:begin' 'google-oauth2' %}">Login with Google</a>
+    <form method="post" action="{% url 'social:begin' 'google-oauth2' %}">
+        {% csrf_token %}
+        <button type="submit">Login with Google</button>
+    </form>
 
 .. note::
-   **Database considerations**: SQLite has field length limitations that can cause issues. For production, use PostgreSQL or MySQL. If using MySQL InnoDB or SQLite, add::
+   **Database considerations**: SQLite has field length limitations that can
+   cause issues. For production, use PostgreSQL or MySQL. If using MySQL InnoDB
+   or SQLite, add::
 
        SOCIAL_AUTH_UID_LENGTH = 223
 
@@ -117,13 +128,11 @@ Also ensure to define the MongoEngine_ storage setting::
 Database
 --------
 
-When using PostgreSQL, it's recommended to use the built-in `JSONB`
-field to store the extracted ``extra_data``. To enable it define the setting::
-
-  SOCIAL_AUTH_JSONFIELD_ENABLED = True
+The built-in models use Django's native ``JSONField`` to store extracted
+``extra_data``.
 
-(For Django 1.7 and higher) you need to sync the database to create needed
-models once you added ``social_django`` to your installed apps::
+Sync the database to create needed models once you added ``social_django`` to
+your installed apps::
 
     ./manage.py migrate
 
@@ -148,7 +157,8 @@ or Django won't pick them when trying to authenticate the user.
 Don't miss ``django.contrib.auth.backends.ModelBackend`` if using ``django.contrib.auth``
 application or users won't be able to login by username / password method.
 
-For more documentation about setting backends to specific social applications, please see the :doc:`/backends/index`.
+For more documentation about setting backends to specific social applications,
+please see the :doc:`/backends/index`.
 
 .. _django-urls:
 
@@ -157,11 +167,11 @@ URLs entries
 
 Add URLs entries::
 
-    urlpatterns = patterns('',
+    urlpatterns = [
         ...
         path("", include('social_django.urls', namespace="social")),
         ...
-    )
+    ]
 
 In case you need a custom namespace, this setting is also needed::
 
@@ -175,20 +185,22 @@ In case you need a custom namespace, this setting is also needed::
       SOCIAL_AUTH_URL_NAMESPACE = 'accounts:social'
 
 
-Requiring POST only login
--------------------------
-
-By default login url ``social:begin`` uses ``GET`` request if you would like to require ``POST`` only (for example to comply with SOC audits) logging in then please use::
+Starting Login
+--------------
 
-    SOCIAL_AUTH_REQUIRE_POST = True
+The ``social:begin`` view requires a ``POST`` request. Use a form and include
+the CSRF token in templates that start authentication.
 
 
 Templates
 ---------
 
 Example of google-oauth2 backend usage in template::
 
-    <a href="{% url "social:begin" "google-oauth2" %}">Google</a>
+    <form method="post" action="{% url 'social:begin' 'google-oauth2' %}">
+        {% csrf_token %}
+        <button type="submit">Google</button>
+    </form>
 
 
 Template Context Processors
@@ -318,39 +330,17 @@ kwargs to the query set filter method.
 
 
 
-JSON field support
+JSON field storage
 ------------------
 
-Django 3.1 introduces `JSONField` support for all backends and adds a
-deprecation warning.
-
-These are the related settings to enabling this integration:
-
-- `SOCIAL_AUTH_JSONFIELD_ENABLED` (boolean)
-
-  Same behavior, setting name updated to match `JSONField` being supported by
-  all systems::
-
-    SOCIAL_AUTH_POSTGRES_JSONFIELD = True  # Before
-    SOCIAL_AUTH_JSONFIELD_ENABLED = True  # After
-
-- `SOCIAL_AUTH_JSONFIELD_CUSTOM` (import path)
-  Allows specifying an import string. This gives better control to setting a
-  custom JSONField.
-
-  For django systems < 3.1 (technically <4), you can set the old `JSONField`
-  to maintain behavior with earlier social-app-django releases::
-
-    SOCIAL_AUTH_JSONFIELD_CUSTOM = 'django.contrib.postgres.fields.JSONField'
-
-  For sites running or upgrading to django 3.1+, then can set this so the new
-  value::
-
-    SOCIAL_AUTH_JSONFIELD_CUSTOM = 'django.db.models.JSONField'
+The current Django models use Django's native ``models.JSONField`` for
+``extra_data`` and partial pipeline data. No JSON field setting is needed for
+new installations.
 
-- Deprecating setting: `SOCIAL_AUTH_POSTGRES_JSONFIELD` (bool)
-  Rename this to `SOCIAL_AUTH_JSONFIELD_ENABLED`. The setting will be deprecated
-  in a future release.
+Older migrations still import ``social_django.fields.JSONField`` for migration
+compatibility. The historical ``SOCIAL_AUTH_JSONFIELD_ENABLED``,
+``SOCIAL_AUTH_JSONFIELD_CUSTOM``, and ``SOCIAL_AUTH_POSTGRES_JSONFIELD``
+settings are only relevant while running those legacy migrations.
 
 
 Exceptions Middleware
@@ -367,7 +357,8 @@ Any method can be overridden, but for simplicity these two are recommended::
     get_redirect_uri(request, exception)
 
 By default, the message is the exception message and the URL for the redirect
-is the location specified by the ``LOGIN_ERROR_URL`` setting.
+is the location specified by the ``LOGIN_ERROR_URL`` setting. The middleware
+supports both synchronous and asynchronous Django request handlers.
 
 If a valid backend was detected by ``strategy()`` decorator, it will be
 available at ``request.strategy.backend`` and ``process_exception()`` will

diff --git a/docs/configuration/porting_from_dsa.rst b/docs/configuration/porting_from_dsa.rst
@@ -41,15 +41,18 @@ URLs
 The URLs are namespaced, you can chose your namespace, the `example app`_ uses
 the ``social`` namespace. Replace the old include with::
 
-    urlpatterns = patterns('',
+    urlpatterns = [
         ...
-        url('', include('social_django.urls', namespace='social'))
+        path('', include('social_django.urls', namespace='social')),
         ...
-    )
+    ]
 
-On templates use a namespaced URL::
+On templates use a namespaced URL in a POST form to start login::
 
-    {% url 'social:begin' "google-oauth2" %}
+    <form method="post" action="{% url 'social:begin' 'google-oauth2' %}">
+        {% csrf_token %}
+        <button type="submit">Google</button>
+    </form>
 
 Account disconnection URL would be::
 

diff --git a/docs/configuration/settings.rst b/docs/configuration/settings.rst
@@ -65,7 +65,7 @@ results and others for error situations.
 
 ``SOCIAL_AUTH_LOGIN_REDIRECT_URL = '/logged-in/'``
     Used to redirect the user once the auth process ended successfully. The
-    value of ``?next=/foo`` is used if it was present
+    value of the ``next`` request parameter is used if it was present
 
 ``SOCIAL_AUTH_LOGIN_ERROR_URL = '/login-error/'``
     URL where the user will be redirected in case of an error
@@ -75,8 +75,9 @@ results and others for error situations.
 
 ``SOCIAL_AUTH_NEW_USER_REDIRECT_URL = '/new-users-redirect-url/'``
     Used to redirect new registered users, will be used in place of
-    ``SOCIAL_AUTH_LOGIN_REDIRECT_URL`` if defined. Note that ``?next=/foo`` is appended if present,
-    if you want new users to go to next, you'll need to do it yourself.
+    ``SOCIAL_AUTH_LOGIN_REDIRECT_URL`` if defined. Note that the ``next``
+    request parameter is appended if present, if you want new users to go to
+    next, you'll need to do it yourself.
 
 ``SOCIAL_AUTH_NEW_ASSOCIATION_REDIRECT_URL = '/new-association-redirect-url/'``
     Like ``SOCIAL_AUTH_NEW_USER_REDIRECT_URL`` but for new associated accounts

diff --git a/docs/developer_intro.rst b/docs/developer_intro.rst
@@ -15,9 +15,12 @@ When you add the PSA entry to your ``urls.py``, it looks like this::
 
 that "namespace" part on the end is what keeps the names in the PSA-world from
 colliding with the names in your app, or other 3rd-party apps.  So your login
-link will look like this::
+form will look like this::
 
-    <a href="{% url 'social:begin' 'provider-name' %}">Login</a>
+    <form method="post" action="{% url 'social:begin' 'provider-name' %}">
+        {% csrf_token %}
+        <button type="submit">Login</button>
+    </form>
 
 (See how "social" in the URL mapping matches the value of "namespace" in the
 ``urls.py`` entry?)
@@ -63,11 +66,11 @@ like::
 
     http://example.com/login/github
 
-And clicking on that link will cause the "pipeline" to be started. The pipeline
-is a list of functions that build up data about the user as we go through the
-steps of the authentication process.  (If you really want to understand the
-pipeline, look at the source in ``social/backends/base.py``, and see the
-``run_pipeline()`` function in ``BaseAuth``.)
+Submitting the login form to that URL will cause the "pipeline" to be started.
+The pipeline is a list of functions that build up data about the user as we go
+through the steps of the authentication process.  (If you really want to
+understand the pipeline, look at the source in ``social/backends/base.py``, and
+see the ``run_pipeline()`` function in ``BaseAuth``.)
 
 The design contract for each function in the pipeline is: