diff --git a/docs/backends/auth0.rst b/docs/backends/auth0.rst index af0d3dc9..1a5139bd 100644 --- a/docs/backends/auth0.rst +++ b/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:: + +
+ {% csrf_token %} + + +
+ +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 diff --git a/docs/configuration/settings.rst b/docs/configuration/settings.rst index ef65aa63..00d7b2a0 100644 --- a/docs/configuration/settings.rst +++ b/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__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__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::