docs(security): consolidate deployment and integration guidance

docs/backends/facebook_limited_login.rst

@@ -57,6 +57,21 @@ Enable the auth backend:
     ...
   )
 
+Security requirements
+---------------------
+
+The client supplies the signed ID token in the ``access_token`` parameter.
+The backend verifies the provider signature and applicable issuer, audience,
+subject, and time claims. It intentionally does not enforce the token's nonce,
+because the backend did not generate it server-side.
+
+Signature validation alone does not bind this token to an authentication
+initiated by the receiving browser or make it single-use. Applications requiring
+login-CSRF or account-linking replay protection must add an application-level
+initiation and single-use binding. Preserve the initiating authenticated local
+user through linking; do not treat an arbitrary client nonce as proof of that
+binding. See :doc:`../security` for shared deployment requirements.
+
 .. _Facebook App Creation: https://developers.facebook.com/apps/creation/
 .. _Facebook Limited Login: https://developers.facebook.com/docs/facebook-login/limited-login/
 .. _hosts file: https://en.wikipedia.org/wiki/Hosts_(file)

docs/backends/openid.rst

@@ -28,9 +28,15 @@ does not apply.
 Session and provider binding
 ----------------------------
 
-All OpenID backends require a positive assertion to match backend-scoped
-discovery state from the browser session that initiated authentication. When
-the framework supports restoring sessions, only a session identifier carried
+All OpenID backends require a positive assertion whose provider-signed return
+URL carries a session-held, one-use transaction value. The verified response
+must also match backend-scoped discovery state from the browser session that
+initiated authentication. A second OpenID start in the same session replaces
+the first transaction; the earlier callback is rejected. Unsolicited assertions
+are rejected, including for anonymous users. Always use the normal backend
+initiation path.
+
+When the framework supports restoring sessions, only a session identifier carried
 by the provider-signed ``openid.return_to`` can select that session. Missing or
 mismatched state requires the user to restart authentication.
 
@@ -49,6 +55,28 @@ setting to disable this validation. Custom strategies that implement session
 restoration must restore the complete OpenID session state and update
 session-derived pipeline arguments, including the authenticated user.
 
+Custom backends overriding authorization URL or HTML generation must include
+the transaction value in the provider-signed return URL, for example by calling
+``_return_to_for_login()``.
+
+Upgrading binding requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Authentication attempts initiated before upgrading to session, transaction, or
+fixed-provider binding must restart. Deployments upgrading from a release
+without fixed-provider binding should review associations created or migrated
+from unexpected identity URLs, especially Ubuntu, openSUSE, and Yandex rows
+migrated from nickname or email identifiers. Confirm ownership through recovery
+or authenticated relinking; those records cannot be repaired automatically.
+
+Setting ``SOCIAL_AUTH_ALLOW_UNVERIFIED_LEGACY_UID_MIGRATION = False`` limits
+migration risk but does not replace provider binding. Disable affected backends
+until the fixed release is installed. See
+:doc:`../configuration/identifier-migration` for evidence and recovery policy.
+
+Extra data
+----------
+
 OpenID_ backends can store extra data in ``UserSocialAuth.extra_data`` field
 by defining a set of values names to retrieve from any of the used schemas,
 AttributeExchange and SimpleRegistration. As their keywords differ we need

docs/backends/saml.rst

@@ -308,6 +308,8 @@ being sent with that request.
 
 ``social-auth-app-django`` preserves the server-side session identifier in
 SAML ``RelayState`` and restores the session before validating the response.
+The restored session key is rotated before continued use; do not override
+restoration in a way that retains the old key or changes the initiating user.
 Use a current ``social-auth-app-django`` release and a server-side Django
 session engine. In multi-instance deployments, every instance that can handle
 the login or callback must use the same session storage. Database and cached

docs/backends/telegram.rst

@@ -58,4 +58,17 @@ Telegram uses a widget-based authentication method for login.
   - Last name
   - Photo URL (if available)
 
+Security requirements
+---------------------
+
+The callback HMAC authenticates the Telegram data, and the backend rejects data
+more than 24 hours old. It does not bind the callback to a login initiated by
+the receiving browser or make it single-use. A valid signed callback can be
+replayed within its accepted age.
+
+Applications requiring login-CSRF or account-linking replay protection must add
+an application-controlled initiation and single-use binding before completing
+the login or association. Preserve the initiating authenticated local user
+through account linking. Serve the application and widget callback over HTTPS.
+
 .. _BotFather: https://t.me/botfather

docs/configuration/django.rst

@@ -542,7 +542,23 @@ Starting Login
 --------------
 
 The ``social:begin`` view requires a ``POST`` request. Use a form and include
-the CSRF token in templates that start authentication.
+the CSRF token in templates that start authentication. The disconnection view
+likewise requires an authenticated, CSRF-protected POST.
+
+Provider completion callbacks are intentionally exempt from Django's CSRF token
+check and rely on the selected core backend's protocol validation. Legacy
+email and username login forms have no provider callback proof: submit them to
+``social:complete`` using a CSRF-protected POST instead. Do not exempt these
+forms or expose an alternate completion route bypassing validation.
+
+During authenticated account linking, preserve the initiating local user across
+the callback; reject or restart a flow if the principal changes. For externally
+resumed partials, preserve the explicit confirmation and nonce checks described
+under :ref:`partial-pipeline`.
+
+Restorable cross-site flows require shared server-side sessions and the same
+browser context. See :doc:`../backends/saml` for supported session arrangements,
+restoration, and upgrade troubleshooting.
 
 
 Templates
@@ -1206,16 +1222,20 @@ from ``social_django.constants`` or equivalent string literals:
 Endpoint Behaviors and Security Architecture
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Both endpoints employ a layered defense model to protect users and your
-application:
+Both endpoints preserve issuer, redirect, framing, and CSRF checks. Fetch
+Metadata headers influence navigation checks and automatic submission; they
+are optional browser context signals, not credentials. Missing headers do not
+remove the remaining checks. Keep these controls when overriding templates.
+Bridge target validation remains active even if general
+``SOCIAL_AUTH_SANITIZE_REDIRECTS`` validation is disabled.
 
 IdP Launch (``idp_launch``)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Route: ``/idp-launch/<str:backend>/`` (URL name: ``social:idp_launch``)
 
 Designed to handle `OIDC IdP-initiated login per the OpenID Connect Core
-specification <https://openid.net/specs/openid-connect-core-1_0-36.html#ThirdPartyInitiatedLogin>`_. Enforces 8 security layers:
+specification <https://openid.net/specs/openid-connect-core-1_0-36.html#ThirdPartyInitiatedLogin>`_. Its behavior is:
 
 1. **Opt-In Gate**: Raises ``Http404`` if ``LaunchBridge.IDP`` (or
    ``'idp_launch'``) is not present in ``SOCIAL_AUTH_ENABLE_LAUNCH_BRIDGES``.
@@ -1247,7 +1267,8 @@ App Launch (``app_launch``)
 
 Route: ``/app-launch/<str:backend>/`` (URL name: ``social:app_launch``)
 
-Designed for same-origin frontend or SPA redirects with OpenID Connect (OIDC) backends. Enforces 10 security layers:
+Designed for same-origin frontend or SPA redirects with OpenID Connect (OIDC)
+backends. Its behavior is:
 
 1. **Opt-In Gate**: Raises ``Http404`` if ``LaunchBridge.APP`` (or
    ``'app_launch'``) is not present in ``SOCIAL_AUTH_ENABLE_LAUNCH_BRIDGES``.
@@ -1333,10 +1354,13 @@ For example, to allow a frontend served on port 8443, include
 Customizing the Launch Template (``launch.html``)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Both bridge views render ``social_django/launch.html``. To customize the
-appearance, loading animation, or branding during the transition, create a
-file named ``social_django/launch.html`` within your project's ``templates``
-directory (ensuring your template loader prioritizes project templates).
+Both bridge views render ``social_django/launch.html``. Overrides must retain
+the CSRF token, forward only the supplied parameters, and honor ``auto_submit``:
+when false, show a manual confirmation button instead of submitting the form
+automatically. To customize the appearance, loading animation, or branding
+during the transition, create ``social_django/launch.html`` within your
+project's ``templates`` directory (ensuring your template loader prioritizes
+project templates).
 
 Template Context Variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/configuration/settings.rst

@@ -362,6 +362,8 @@ For OAuth backends::
     ]
 
 
+.. _request-redirect-settings:
+
 Processing requests and redirects
 ---------------------------------
 
@@ -384,6 +386,16 @@ allow some tweaks to the behavior of these.
     ``next`` GET argument if the hostname is on the list, otherwise it defaults
     to the value of ``SOCIAL_AUTH_LOGIN_REDIRECT_URL``.
 
+``SOCIAL_AUTH_ALLOWED_REDIRECT_SCHEMES = ['http', 'https']``
+    Select the schemes accepted for request-derived completion redirects.
+    HTTP(S) URLs must also pass the host allowlist. For a native application,
+    explicitly add its private-use scheme, for example
+    ``['http', 'https', 'com.example.app']``. Private-use destinations are
+    authorized by scheme alone; their host-like component is not checked against
+    ``ALLOWED_REDIRECT_HOSTS``. Approve only schemes controlled by the intended
+    application. These checks do not provide general URL safety or SSRF
+    protection. Backend-specific settings take precedence over global values.
+
 ``SOCIAL_AUTH_REDIRECT_IS_HTTPS = False``
     On projects behind a reverse proxy that uses HTTPS, the redirect URIs
     can have the wrong schema (``http://`` instead of ``https://``) if
@@ -470,14 +482,21 @@ Miscellaneous settings
     This setting does not rename arguments passed by ``create_user``; required
     creation fields must be supplied separately. The default mapping is empty.
 
-``SOCIAL_AUTH_PROTECTED_USER_FIELDS = ['email',]``
-    During the pipeline process a ``dict`` named ``details`` will be populated
-    with the needed values to create the user instance, but it's also used to
-    update the user instance. Any value in it will be checked as an attribute
-    in the user instance (first by doing ``hasattr(user, name)``). Usually
-    there are attributes that cannot be updated (like ``username``, ``id``,
-    ``email``, etc.), those fields need to be *protect*. Set any field name that
-    requires *protection* in this setting, and it won't be updated.
+``SOCIAL_AUTH_PROTECTED_USER_FIELDS = []``
+    Add local field names that ``user_details`` must not update from provider
+    profile data. By default, ``username``, ``id``, ``pk``, ``email``,
+    ``password``, ``is_active``, ``is_staff``, and ``is_superuser`` are already
+    protected. Configured fields supplement that list. Protection applies to
+    the destination field after ``USER_FIELD_MAPPING`` is resolved; it governs
+    updates, not which fields are passed to initial user creation.
+
+``SOCIAL_AUTH_NO_DEFAULT_PROTECTED_USER_FIELDS = False``
+    Explicit ``True`` removes the default protected fields; any fields listed
+    in ``PROTECTED_USER_FIELDS`` remain protected. This transfers responsibility
+    for identity and authorization-sensitive updates to the application.
+    Preserve equivalent protection before allowing provider data to update
+    local account identifiers, credentials, activity, or privilege fields.
+    Both settings support backend-specific overrides.
 
 
 ``SOCIAL_AUTH_IMMUTABLE_USER_FIELDS = ['email',]``

docs/pipeline.rst

@@ -81,6 +81,30 @@ arguments that may be passed from other pipeline functions or future versions::
         pass
 
 
+.. _pipeline-security:
+
+Pipeline security
+-----------------
+
+Custom pipeline steps execute with application authority. Preserve protocol
+validation, identity selection, policy checks, and association ordering. Keep
+``auth_allowed`` before user creation or linking. Request and provider values
+retain their provenance when saved in sessions, associations, or partials;
+revalidate them before using them for a new security decision. Confirmed resume
+parameters are effective request data, not independently trusted identity claims.
+
+Provider email and profile fields do not establish local authorization or
+account ownership by themselves. ``associate_by_email`` is disabled by default;
+enable it only with an explicit verified-email and account-recovery policy.
+Review protected local fields in :doc:`configuration/settings` and partial
+ownership and confirmation requirements under :ref:`partial-pipeline`.
+
+The optional ``social_core.pipeline.debug.debug`` step prints the provider
+response, details, positional arguments, and pipeline keyword arguments to
+standard output. These may include tokens, validation codes, personal data,
+and other secrets. Use it only with controlled development data; do not enable
+it in production. Custom diagnostics must avoid logging raw authentication data.
+
 Authentication Pipeline
 -----------------------
 
@@ -312,6 +336,8 @@ Backend specific disconnection pipelines can also be defined with a setting such
 ``SOCIAL_AUTH_TWITTER_DISCONNECT_PIPELINE``.
 
 
+.. _partial-pipeline:
+
 Partial Pipeline
 ----------------