Add IdP setup instructions to backend documentation

docs/backends/auth0_openidconnect.rst

@@ -5,10 +5,26 @@ Auth0 OpenID Connect (OIDC) implementation. Separate from
 the previous ``Auth0OAuth2`` backend, as it builds on the base
 OIDC backend.
 
-To configure Auth0 as an OpenID Connect (OIDC) backend,
-you need the following minimum configuration,
-using details from your Auth0 tenant and an application
-you have configured in it::
+IdP Setup
+---------
+
+To configure Auth0:
+
+1. Log into your Auth0 Dashboard
+2. Navigate to **Applications** > **Create Application**
+3. Select **Regular Web Applications**
+4. In the application settings, configure:
+
+   * **Allowed Callback URLs**: ``https://your-domain.com/complete/auth0-openidconnect/``
+   * **Allowed Logout URLs**: ``https://your-domain.com/logout/`` (if using logout)
+   * **Allowed Web Origins**: ``https://your-domain.com``
+
+5. Note the **Domain** (e.g., ``mytenant.auth0.com``), **Client ID**, and **Client Secret**
+
+Application Configuration
+-------------------------
+
+Use the values from your Auth0 application::
 
     SOCIAL_AUTH_AUTH0_OPENIDCONNECT_DOMAIN = 'mytenant.auth0.com'
     SOCIAL_AUTH_AUTH0_OPENIDCONNECT_KEY = '<client_id>'

docs/backends/azuread.rst

@@ -1,13 +1,37 @@
 Microsoft Azure Active Directory
 ================================
 
-To enable OAuth2 support:
+IdP Setup
+---------
 
-- Fill in ``Client ID`` and ``Client Secret`` settings. These values can be
-  obtained easily as described in `Azure AD Application Registration`_ doc::
+To configure Azure AD:
+
+1. Log into the Azure Portal
+2. Navigate to **Azure Active Directory** > **App registrations** > **New registration**
+3. Configure:
+
+   * **Name**: Your application name
+   * **Redirect URI**: Select **Web** and enter ``https://your-domain.com/complete/azuread-oauth2/``
+
+4. After registration, note the **Application (client) ID** and **Directory (tenant) ID**
+5. Create a client secret:
+
+   * Go to **Certificates & secrets** > **New client secret**
+   * Copy the secret value immediately (you won't be able to see it again)
+
+6. Configure API Permissions:
 
-      SOCIAL_AUTH_AZUREAD_OAUTH2_KEY = ''
-      SOCIAL_AUTH_AZUREAD_OAUTH2_SECRET = ''
+   * Go to **API permissions** > **Add a permission** > **Microsoft Graph**
+   * Add delegated permissions: ``User.Read``, ``email``, ``openid``, ``profile``
+   * Click **Grant admin consent** if required
+
+Application Configuration
+-------------------------
+
+Fill in ``Client ID`` and ``Client Secret`` settings with values from Azure AD::
+
+    SOCIAL_AUTH_AZUREAD_OAUTH2_KEY = ''
+    SOCIAL_AUTH_AZUREAD_OAUTH2_SECRET = ''
 
 - Also it's possible to define extra permissions with::
 
@@ -44,17 +68,21 @@ possible to use a version of the backend with tenant support.
 
 *Note: The backends are split because of the needed cryptography dependencies which must be installed manually.*
 
-To enable OAuth2 Tenant support:
+IdP Setup for Tenant
+^^^^^^^^^^^^^^^^^^^^^
 
-- Fill in ``Client ID`` and ``Client Secret`` settings. These values can be
-  obtained easily as described in `Azure AD Application Registration`_ doc::
+Follow the same IdP setup steps from the 'IdP Setup' section above, but use redirect URI::
 
-      SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_KEY = ''
-      SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET = ''
+    https://your-domain.com/complete/azuread-tenant-oauth2/
 
-- Fill in the tenant id::
+Application Configuration for Tenant
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Fill in ``Client ID``, ``Client Secret``, and ``Tenant ID`` settings::
 
-      SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_TENANT_ID = ''
+    SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_KEY = ''
+    SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET = ''
+    SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_TENANT_ID = ''
 
 - Also it's possible to define extra permissions with::
 

docs/backends/google.rst

@@ -38,16 +38,33 @@ Recently Google launched OAuth2 support following the definition at `OAuth2 draf
 It works in a similar way to plain OAuth mechanism, but developers **must** register
 an application and apply for a set of keys. Check `Google OAuth2`_ document for details.
 
-When creating the application in the Google Console be sure to fill the
-``PRODUCT NAME`` at ``API & auth -> Consent screen`` form.
+IdP Setup
+^^^^^^^^^
 
-To enable OAuth2 support:
+To configure Google OAuth2:
 
-- fill ``Client ID`` and ``Client Secret`` settings, these values can be obtained
-  easily as described on `OAuth2 Registering`_ doc::
+1. Go to the `Google Cloud Console <https://console.cloud.google.com/>`_
+2. Create a new project or select an existing one
+3. Navigate to **APIs & Services** > **Credentials**
+4. Click **Create Credentials** > **OAuth client ID**
+5. Configure:
 
-      SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = ''
-      SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = ''
+   * **Application type**: Web application
+   * **Authorized redirect URIs**: ``https://your-domain.com/complete/google-oauth2/``
+
+6. Note the **Client ID** and **Client Secret**
+7. Configure the **OAuth consent screen** (``APIs & Services > OAuth consent screen``):
+
+   * Set the **PRODUCT NAME** and other required fields
+   * Add scopes: ``email``, ``profile``, ``openid``
+
+Application Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Fill in ``Client ID`` and ``Client Secret`` settings with values from Google::
+
+    SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = ''
+    SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = ''
 
 - setup any needed extra scope::
 

docs/backends/keycloak.rst

@@ -3,24 +3,42 @@ Keycloak - Open Source Red Hat SSO
 
 Keycloak is an open source IAM and SSO system.
 
-To enable Keycloak as a backend:
+IdP Setup
+---------
 
-- On your project settings, add Keycloak on your ``AUTHENTICATION_BACKENDS``::
+To configure Keycloak:
+
+1. Log into your Keycloak Admin Console and select your Realm
+2. Navigate to **Clients** > **Create**
+3. Configure the client:
+
+   * **Client ID**: Choose a meaningful name (e.g., ``django-app``)
+   * **Client Protocol**: ``openid-connect``
+   * **Access Type**: ``confidential``
+   * **Valid Redirect URIs**: ``https://your-domain.com/complete/keycloak/``
+
+4. Save and go to the **Credentials** tab to get the **Client Secret**
+5. Under **Fine Grain OpenID Connect Configuration** (found in the client's Settings or Advanced Settings tab; location may vary depending on Keycloak version), set:
+
+   * **User Info Signed Response Algorithm**: ``RS256``
+   * **Request Object Signature Algorithm**: ``RS256``
+
+6. Get the public key from **Realm Settings** > **Keys** > **RS256**
+7. Create an **Audience Mapper** (**Mappers** > **Create**) to ensure your ``client_id`` is in the JWT's ``aud`` claim
+8. Note the **Authorization URL** and **Token URL** from the Realm OpenID Endpoint Configuration
+
+Application Configuration
+-------------------------
+
+Add Keycloak to your ``AUTHENTICATION_BACKENDS``::
 
     AUTHENTICATION_BACKENDS = (
         ...
         'social_core.backends.keycloak.KeycloakOAuth2',
         'django.contrib.auth.backends.ModelBackend',
     )
 
-- Create a Client in your Keycloak realm
-
-- On your client under ``Fine Grain OpenID Connect Configuration`` ensure that ``User Info Signed Response Algorithm`` and ``Request Object Signature Algorithm`` is set to ``RS256``. Save. Then go to: Realm Settings -> Keys -> RS256 and copy your Public key to ``SOCIAL_AUTH_KEYCLOAK_PUBLIC_KEY`` in your django settings
-
-- Add these values of ``Client ID`` and ``Client Secret`` from client in your project settings file.
-
-The ``Client ID`` should be added on ``SOCIAL_AUTH_KEYCLOAK_KEY`` and the ``Client Secret`` should be
-added on ``SOCIAL_AUTH_KEYCLOAK_SECRET``. You also need to add your keycloak instance auth and token URL's found in the Realm OpenID Endpoint Configuration::
+Configure with values from your Keycloak client::
 
     SOCIAL_AUTH_KEYCLOAK_KEY = 'test-django-oidc'
     SOCIAL_AUTH_KEYCLOAK_SECRET = 'a7a41-245e-...'
@@ -31,10 +49,6 @@ added on ``SOCIAL_AUTH_KEYCLOAK_SECRET``. You also need to add your keycloak ins
     SOCIAL_AUTH_KEYCLOAK_ACCESS_TOKEN_URL = \
         'https://iam.example.com/auth/realms/voxcloud-staff/protocol/openid-connect/token'
 
-Lastly you need to ensure the ``client_id`` is in your JWT's ``aud`` key. On your client go to Mappers -> Create. Create an ``Audience Mapper`` and ensure the ``Included Client Audience`` is your ``client_id``.
-
-Thereafter go to: ``<app_url>/login/keycloak`` and the authorization code flow should commence.
-
 User ID Configuration
 ---------------------
 

docs/backends/oidc.rst

@@ -16,6 +16,25 @@ The remaining configuration will be auto-detected, by fetching::
 This class can be used standalone, but is also the base class for some other
 backends.
 
+IdP Setup
+---------
+
+To configure your OIDC Identity Provider for use with this backend:
+
+1. Create a new application/client in your IdP with type "Web Application"
+2. Set the **Redirect URI** (also called Callback URL) to::
+
+    https://your-domain.com/complete/oidc/
+
+   Replace ``your-domain.com`` with your actual application domain.
+
+3. Configure scopes to include at minimum: ``openid``, ``profile``, ``email``
+4. Note the generated **Client ID** and **Client Secret** for use in your Django settings
+5. Ensure your IdP exposes the OpenID Connect discovery endpoint at: ``https://your-idp-domain/.well-known/openid-configuration``
+
+.. note::
+   For development, you can use ``http://localhost:8000/complete/oidc/`` as the redirect URI.
+
 Authentication Request Parameters
 ---------------------------------
 

docs/backends/okta.rst

@@ -6,25 +6,49 @@ This section describes how to setup the different services provided by Okta.
 Okta OAuth2
 -----------
 
-To enable OAuth2 support:
+IdP Setup
+^^^^^^^^^
 
-- Fill ``Client ID``, ``Client Secret`` and `API URL (e.g.
-  https://dev-000000.oktapreview.com/oauth2)` settings, these values can be
-  obtained easily from Okta after creating a Web application. Please note, do
-  not use the ``/oauth2/default`` endpoint for Okta authentication::
+To configure Okta for OAuth2:
 
-      SOCIAL_AUTH_OKTA_OAUTH2_KEY = ''
-      SOCIAL_AUTH_OKTA_OAUTH2_SECRET = ''
-      SOCIAL_AUTH_OKTA_OAUTH2_API_URL = ''
+1. Log into your Okta Admin Console
+2. Navigate to **Applications** > **Create App Integration**
+3. Select **OIDC - OpenID Connect** and **Web Application**
+4. Set the **Sign-in redirect URI** to::
+
+    https://your-domain.com/complete/okta-oauth2/
+
+5. Save and note the **Client ID**, **Client Secret**, and **Okta domain** (e.g., ``https://dev-123456.okta.com``)
+
+.. important::
+   Do NOT use the ``/oauth2/default`` endpoint for Okta authentication.
+
+Application Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Fill ``Client ID``, ``Client Secret`` and ``API URL (e.g.
+https://dev-000000.oktapreview.com/oauth2)`` settings with the values from the IdP setup above::
+
+    SOCIAL_AUTH_OKTA_OAUTH2_KEY = ''
+    SOCIAL_AUTH_OKTA_OAUTH2_SECRET = ''
+    SOCIAL_AUTH_OKTA_OAUTH2_API_URL = ''
 
 Okta OpenId Connect
 -------------------
 
-- Fill ``Client ID``, ``Client Secret`` and `API URL (e.g.
-  https://dev-000000.oktapreview.com/oauth2)` settings, these values can be
-  obtained easily from Okta after creating a Web application. Please note, do
-  not use the ``/oauth2/default`` endpoint for Okta authentication::
+IdP Setup
+^^^^^^^^^
+
+Follow the same steps as OAuth2 above, but use the redirect URI::
+
+    https://your-domain.com/complete/okta-openidconnect/
+
+Application Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Fill ``Client ID``, ``Client Secret`` and ``API URL (e.g.
+https://dev-000000.oktapreview.com/oauth2)`` settings with the values from the IdP setup::
 
-      SOCIAL_AUTH_OKTA_OPENIDCONNECT_KEY = ''
-      SOCIAL_AUTH_OKTA_OPENIDCONNECT_SECRET = ''
-      SOCIAL_AUTH_OKTA_OPENIDCONNECT_API_URL = ''
+    SOCIAL_AUTH_OKTA_OPENIDCONNECT_KEY = ''
+    SOCIAL_AUTH_OKTA_OPENIDCONNECT_SECRET = ''
+    SOCIAL_AUTH_OKTA_OPENIDCONNECT_API_URL = ''