docs(auth): document structured failures and exception migration

docs/backends/azuread.rst

@@ -421,7 +421,8 @@ a Django view can retrieve the token before clearing the local session:
 Use a CSRF-protected POST form to invoke this view. This example assumes an
 authenticated B2C user and a single configured sign-in policy. Applications
 with multiple policies must select the backend for the stored sign-in policy.
-A missing or invalid ``end_session_endpoint`` raises ``AuthMissingParameter``;
+A missing or invalid ``end_session_endpoint`` raises ``AuthResponseError``
+with ``code="missing_claim"`` or ``code="invalid_claim"``, respectively;
 discovery request failures propagate through the usual backend error handling.
 
 Provider logout complements local logout. Disconnecting an account removes

docs/backends/email.rst

@@ -56,6 +56,9 @@ Password handling
 
 Here's an example of password handling to add to the pipeline::
 
+    from social_core.exceptions import AuthCredentialError
+
+
     def user_password(strategy, backend, user, is_new=False, *args, **kwargs):
         if backend.name != 'email':
             return
@@ -66,7 +69,14 @@ Here's an example of password handling to add to the pipeline::
             user.save()
         elif not user.validate_password(password):
             # return {'user': None, 'social': None}
-            raise AuthForbidden(backend)
+            raise AuthCredentialError(
+                backend,
+                code="credential_rejected",
+                source="request",
+                stage="pipeline",
+                parameter="password",
+                recovery="correct_input",
+            )
 
 .. _python-social-auth: https://github.com/python-social-auth
 .. _EmailAuth: https://github.com/python-social-auth/social-core/blob/master/social_core/backends/email.py

docs/backends/implementation.rst

@@ -266,7 +266,7 @@ redirected.
 Example code::
 
     from social_core.backends.open_id import OpenIdAuth
-    from social_core.exceptions import AuthMissingParameter
+    from social_core.exceptions import AuthInputError
 
 
     class LiveJournalOpenId(OpenIdAuth):
@@ -284,7 +284,7 @@ Example code::
         def openid_url(self):
             """Returns LiveJournal authentication URL"""
             if not self.data.get('openid_lj_user'):
-                raise AuthMissingParameter(self, 'openid_lj_user')
+                raise AuthInputError(self, code="missing_parameter", parameter="openid_lj_user", stage="begin")
             return 'http://%s.livejournal.com' % self.data['openid_lj_user']
 
 
@@ -300,7 +300,7 @@ Example code::
     from google.appengine.api import users
 
     from social_core.backends.base import BaseAuth
-    from social_core.exceptions import AuthException
+    from social_core.exceptions import AuthUnknownError
 
 
     class GoogleAppEngineAuth(BaseAuth):
@@ -329,7 +329,7 @@ Example code::
         def auth_complete(self, *args, **kwargs):
             """Completes login process, must return user instance."""
             if not users.get_current_user():
-                raise AuthException('Authentication error')
+                raise AuthUnknownError(self, code="unknown_error", stage="callback")
             kwargs.update({'response': '', 'backend': self})
             return self.strategy.authenticate(*args, **kwargs)
 
@@ -340,6 +340,12 @@ Common backend methods
 All backends inherit from ``BaseAuth`` which provides several methods that can be
 overridden to customize behavior. Here are some key methods:
 
+``process_error(data, *, stage="callback")``
+    Detects provider errors in callbacks and successful HTTP responses. OAuth2
+    backends also call this hook during token exchange and refresh. Overrides
+    must accept the keyword-only ``stage`` argument, pass it to the superclass,
+    and use it when constructing structured exceptions. See :doc:`../exceptions`.
+
 ``id_key()``
     Returns the ID key to use for this backend. By default, this method checks
     if the ``ID_KEY`` has been configured via settings (using

docs/backends/saml.rst

@@ -292,7 +292,7 @@ particular, there are two methods that are designed for subclasses to override:
   on the user's SAML attributes. For example, you can restrict access to your
   application to only accept users who belong to a certain department. After
   inspecting the passed attributes parameter, do nothing to allow the user to
-  login, or raise ``social_core.exceptions.AuthForbidden`` to reject the user.
+  login, or raise ``social_core.exceptions.AuthPolicyError`` to reject the user.
 
 
 Troubleshooting

docs/backends/username.rst

@@ -51,6 +51,9 @@ Password handling
 
 Here's an example of password handling to add to the pipeline::
 
+    from social_core.exceptions import AuthCredentialError
+
+
     def user_password(strategy, user, is_new=False, *args, **kwargs):
         if strategy.backend.name != 'username':
             return
@@ -61,7 +64,14 @@ Here's an example of password handling to add to the pipeline::
             user.save()
         elif not user.validate_password(password):
             # return {'user': None, 'social': None}
-            raise AuthException(strategy.backend)
+            raise AuthCredentialError(
+                strategy.backend,
+                code="credential_rejected",
+                source="request",
+                stage="pipeline",
+                parameter="password",
+                recovery="correct_input",
+            )
 
 .. _python-social-auth: https://github.com/python-social-auth
 .. _UsernameAuth: https://github.com/python-social-auth/social-core/blob/master/social_core/backends/username.py

docs/configuration/django.rst

@@ -496,8 +496,8 @@ When query parameter transport is active (or triggered via fallback), the redire
 destination receives two query parameters:
 
 ``message = ''``
-    Message from the exception raised. In some cases, this is the error message
-    returned by the provider during the authentication process.
+    Safe default message from the exception raised. Provider descriptions are
+    retained in the exception's diagnostic ``detail`` and are not sent to clients.
 
 ``backend = ''``
     Backend name that was used, or ``unknown-backend`` if unresolved.
@@ -582,6 +582,32 @@ Exception processing is disabled if any of these settings is defined with a
     DEBUG = True
 
 
+Structured authentication errors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+See :ref:`authentication-exceptions` for the exception families and recovery
+contract. The middleware uses safe default messages; provider diagnostics and
+identifying context are not included in client transports.
+
+Enable metadata in query transport (including message-storage fallback) with:
+
+.. code-block:: python
+
+    SOCIAL_AUTH_ERROR_INCLUDE_METADATA = True  # Default: False
+
+The redirect receives ``error_code``, ``error_source``, ``error_stage``, and
+``error_recovery`` alongside the configured message/backend parameters.
+Backend-specific settings are supported. Existing query parameters and fragments
+are preserved; stale metadata values are replaced when metadata is enabled.
+If a configured message/backend parameter name matches a metadata key, the
+configured parameter takes precedence and that metadata field is omitted.
+
+Applications should select their own messages and redirects from stable codes,
+and should decide reporting independently of suggested recovery actions.
+Subclasses overriding ``dispatch_error`` or ``append_query_params`` must accept
+the new optional ``metadata`` argument.
+
+
 Launch Bridge Endpoints
 -----------------------
 

docs/configuration/settings.rst

@@ -259,8 +259,8 @@ An explicitly configured ``ID_KEY`` takes precedence over older
 backend-specific identifier selectors such as ``USERNAME_AS_ID``,
 ``USE_UNIQUE_USER_ID``, and ``IDENTIFIED_BY_PERMANENT_ID``.
 An explicitly configured field must be present and non-empty in the provider
-data; otherwise authentication fails with ``AuthMissingParameter`` rather
-than storing an ambiguous user identifier.
+data; otherwise authentication fails with ``AuthResponseError`` and
+``code="missing_claim"`` rather than storing an ambiguous user identifier.
 
 Example: Configure Seznam backend to use ``id`` instead of the default ``oauth_user_id``::
 
@@ -382,11 +382,11 @@ address or domain name. To white-list just set any of these settings:
 ``SOCIAL_AUTH_<BACKEND_NAME>_WHITELISTED_DOMAINS = ['foo.com', 'bar.com']``
     Supply a list of domain names to be white-listed. Any user with an email
     address on any of the allowed domains will login successfully, otherwise
-    ``AuthForbidden`` is raised.
+    ``AuthPolicyError`` is raised.
 
 ``SOCIAL_AUTH_<BACKEND_NAME>_WHITELISTED_EMAILS = ['me@foo.com', 'you@bar.com']``
     Supply a list of email addresses to be white-listed. Any user with an email
-    address in this list will login successfully, otherwise ``AuthForbidden``
+    address in this list will login successfully, otherwise ``AuthPolicyError``
     is raised.