Add documentation for OAuth2 URL override and backend-specific Django middleware settings (#336)

* Initial plan

* Add documentation for OAuth2 URL override and backend-specific Django middleware settings

Co-authored-by: nijel <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: nijel <[email protected]>

Author: Copilot

docs/configuration/django.rst

@@ -305,6 +305,29 @@ available at ``request.strategy.backend`` and ``process_exception()`` will
 use it to build a backend-dependent redirect URL but fallback to default if not
 defined.
 
+Backend-specific settings
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Both the ``LOGIN_ERROR_URL`` and ``RAISE_EXCEPTIONS`` settings can be configured
+on a per-backend basis. This allows you to customize error handling behavior for
+specific authentication backends.
+
+To define backend-specific error URLs, use the backend name in the setting::
+
+    SOCIAL_AUTH_LOGIN_ERROR_URL = '/login-error/'  # Default for all backends
+    SOCIAL_AUTH_FACEBOOK_LOGIN_ERROR_URL = '/facebook-error/'  # Specific to Facebook
+    SOCIAL_AUTH_GOOGLE_OAUTH2_LOGIN_ERROR_URL = '/google-error/'  # Specific to Google OAuth2
+
+Similarly, you can control exception raising on a per-backend basis::
+
+    SOCIAL_AUTH_RAISE_EXCEPTIONS = False  # Default for all backends
+    SOCIAL_AUTH_FACEBOOK_RAISE_EXCEPTIONS = True  # Raise exceptions only for Facebook
+
+This is particularly useful when you want different error handling strategies for
+different authentication providers, such as showing a custom error page for certain
+providers or raising exceptions for debugging specific backends while keeping
+others in production mode.
+
 Exception processing is disabled if any of this settings is defined with a
 ``True`` value::
 

docs/configuration/settings.rst

@@ -191,6 +191,42 @@ settings in the same way explained above but with this other suffix::
 
       SOCIAL_AUTH_<uppercase backend name>_REQUEST_TOKEN_EXTRA_ARGUMENTS = {...}
 
+
+OAuth2 provider URLs override
+------------------------------
+
+By default, OAuth2 backends have hardcoded URLs for authorization and access token
+endpoints. However, these can be overridden via settings to support custom OAuth2
+providers or alternate deployments of the same provider (e.g., OpenHistoricalMap
+instead of OpenStreetMap, or self-hosted instances).
+
+``SOCIAL_AUTH_AUTHORIZATION_URL``
+    Override the authorization URL for OAuth2 backends globally or per-backend.
+    Example::
+
+      SOCIAL_AUTH_KEYCLOAK_AUTHORIZATION_URL = 'https://auth.example.com/auth/realms/myrealm/protocol/openid-connect/auth'
+
+``SOCIAL_AUTH_ACCESS_TOKEN_URL``
+    Override the access token URL for OAuth2 backends globally or per-backend.
+    Example::
+
+      SOCIAL_AUTH_KEYCLOAK_ACCESS_TOKEN_URL = 'https://auth.example.com/auth/realms/myrealm/protocol/openid-connect/token'
+
+``SOCIAL_AUTH_REVOKE_TOKEN_URL``
+    Override the token revocation URL for OAuth2 backends globally or per-backend.
+    Example::
+
+      SOCIAL_AUTH_GITHUB_REVOKE_TOKEN_URL = 'https://github.example.com/api/revoke'
+
+These settings allow you to use backends with custom deployments. For example,
+to use the OpenStreetMap backend with OpenHistoricalMap::
+
+    SOCIAL_AUTH_OPENSTREETMAP_AUTHORIZATION_URL = 'https://www.openhistoricalmap.org/oauth/authorize'
+    SOCIAL_AUTH_OPENSTREETMAP_ACCESS_TOKEN_URL = 'https://www.openhistoricalmap.org/oauth/access_token'
+
+Note that backend-specific settings (with the backend name) take precedence over
+generic settings, following the same pattern as other settings in this library.
+
 Basic information is requested to the different providers in order to create
 a coherent user instance (with first and last name, email and full name), this
 could be too intrusive for some sites that want to ask users the minimum data