docs(auth0): explain connection selection and request overrides

docs/backends/auth0.rst

@@ -47,6 +47,44 @@ To enable Auth0 OAuth2 support:
         ...
     )
 
+Selecting a connection
+**********************
+
+To send users directly to a social or enterprise identity provider, pass the
+Auth0 ``connection`` parameter using :ref:`auth-extra-arguments`::
+
+    SOCIAL_AUTH_AUTH0_AUTH_EXTRA_ARGUMENTS = {
+        'connection': 'google-oauth2',
+    }
+
+Use the connection name configured in Auth0, rather than its connection ID.
+The connection must be enabled for your Auth0 application. For social and
+enterprise connections, this skips the Universal Login provider selection page
+and redirects to the selected identity provider. See Auth0's
+`connection selection guidance`_.
+
+To let users choose a connection when starting login, explicitly allow the
+request parameter to override the configured default::
+
+    SOCIAL_AUTH_AUTH0_AUTH_EXTRA_ARGUMENTS_OVERRIDE_ALLOWLIST = ['connection']
+
+Keep ``connection`` in ``SOCIAL_AUTH_AUTH0_AUTH_EXTRA_ARGUMENTS`` as shown above.
+For Django, start login with a POST form containing the CSRF token and the
+selected connection::
+
+    <form method="post" action="{% url 'social:begin' 'auth0' %}">
+        {% csrf_token %}
+        <input type="hidden" name="connection" value="google-oauth2">
+        <button type="submit">Continue with Google</button>
+    </form>
+
+Without the override allowlist, the configured connection is used even when the
+request supplies another value. The allowlist controls which parameter names
+can be overridden; it does not restrict the connection values users can submit.
+Connection selection controls login routing. Enforce any restrictions on which
+connections a user may authenticate through in Auth0 or your application's
+server-side authentication policy.
+
 Scopes
 ******
 
@@ -58,3 +96,5 @@ The backend will handle JWT token validation and extract user details including
 username, email, full name, and profile picture.
 
 .. _Auth0 Dashboard: https://manage.auth0.com/
+
+.. _connection selection guidance: https://support.auth0.com/center/s/article/Authenticating-users-through-a-specific-Connection-database-social-etc

docs/configuration/settings.rst

@@ -193,6 +193,8 @@ to control username generation.
     in the format of an import path.
 
 
+.. _auth-extra-arguments:
+
 Extra arguments on auth processes
 ---------------------------------
 
@@ -215,6 +217,17 @@ For other providers, just define settings in the form::
 
       SOCIAL_AUTH_<uppercase backend name>_AUTH_EXTRA_ARGUMENTS = {...}
 
+Configured values are used by default, even when the request contains a
+parameter with the same name. To allow matching request parameters to override
+specific configured values, list their names in::
+
+      SOCIAL_AUTH_<uppercase backend name>_AUTH_EXTRA_ARGUMENTS_OVERRIDE_ALLOWLIST = ['prompt']
+
+Each listed name must also be present in ``AUTH_EXTRA_ARGUMENTS``. Request-only
+parameters are not added automatically. Only allow overrides for parameters
+whose values users may choose; the allowlist restricts parameter names, not
+values. See :doc:`/backends/auth0` for a connection-selection example.
+
 Also, you can send extra parameters on request token process by defining
 settings in the same way explained above but with this other suffix::