From 48508706b4754538ee475f897676b12ac34dbacf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 10 Nov 2025 15:15:27 +0000 Subject: [PATCH 1/4] Initial plan From bda036790407ef34eeb7d416db409ce14d81ea01 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 10 Nov 2025 15:27:28 +0000 Subject: [PATCH 2/4] Add comprehensive IdP setup guide for OIDC/SSO authentication Co-authored-by: nijel <212189+nijel@users.noreply.github.com> --- docs/idp_setup_guide.rst | 406 +++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 407 insertions(+) create mode 100644 docs/idp_setup_guide.rst diff --git a/docs/idp_setup_guide.rst b/docs/idp_setup_guide.rst new file mode 100644 index 00000000..9d0f0a1f --- /dev/null +++ b/docs/idp_setup_guide.rst @@ -0,0 +1,406 @@ +Identity Provider (IdP) Setup Guide +==================================== + +This guide helps Identity Provider (IdP) administrators configure their systems to work with applications using Python Social Auth, particularly for OIDC (OpenID Connect) and SSO (Single Sign-On) implementations. + +.. contents:: Table of Contents + :local: + :depth: 2 + +Overview +-------- + +When integrating your application with an Identity Provider for authentication, the IdP administrator needs to configure several settings. This guide provides the essential information needed to complete that setup. + +Understanding the Redirect URI / Callback URL +---------------------------------------------- + +The **Redirect URI** (also called **Callback URL**) is the most critical configuration setting. After a user successfully authenticates with the IdP, they are redirected back to your application at this URL. + +**Format:** + +For most backends, the redirect URI follows this pattern:: + + https://your-domain.com/complete// + +**Examples:** + +* OIDC (generic): ``https://example.com/complete/oidc/`` +* Okta OAuth2: ``https://example.com/complete/okta-oauth2/`` +* Okta OpenID Connect: ``https://example.com/complete/okta-openidconnect/`` +* Auth0 OpenID Connect: ``https://example.com/complete/auth0-openidconnect/`` +* Azure AD: ``https://example.com/complete/azuread-oauth2/`` or ``https://example.com/complete/azuread-tenant-oauth2/`` +* Keycloak: ``https://example.com/complete/keycloak/`` +* Google OAuth2: ``https://example.com/complete/google-oauth2/`` +* GitHub: ``https://example.com/complete/github/`` + +.. note:: + Replace ``https://example.com`` with your actual application domain. + If your application is running on a different path or port, adjust accordingly. + For development: ``http://localhost:8000/complete//`` + +.. warning:: + The redirect URI must use **HTTPS** in production environments. + Most IdPs will reject HTTP URLs for security reasons. + +Required Information from Application Developers +------------------------------------------------- + +Before starting the IdP configuration, gather this information from your application development team: + +1. **Backend Name**: Which authentication backend is being used (e.g., ``oidc``, ``okta-openidconnect``, ``keycloak``) +2. **Application Domain**: The full domain where the application is hosted +3. **Required Scopes**: What user information the application needs (typically: ``openid``, ``profile``, ``email``) +4. **Additional Settings**: Any backend-specific requirements + +Generic OIDC Provider Setup +---------------------------- + +For a generic OpenID Connect provider, follow these steps: + +1. **Create a new Application/Client** + + * Choose "Web Application" as the application type + * Note the ``Client ID`` and ``Client Secret`` generated + +2. **Configure the Redirect URI** + + Set the redirect URI to:: + + https://your-domain.com/complete/oidc/ + +3. **Configure Scopes/Permissions** + + Enable at least these scopes: + + * ``openid`` - Required for OpenID Connect + * ``profile`` - User profile information + * ``email`` - User email address + +4. **OIDC Discovery Endpoint** + + Ensure your IdP exposes the OpenID Connect discovery endpoint:: + + https://your-idp-domain/.well-known/openid-configuration + + The Python Social Auth backend will automatically discover endpoints from this URL. + +5. **Provide to Development Team** + + Give these values to your application developers: + + * ``Client ID`` + * ``Client Secret`` + * ``OIDC Endpoint`` (e.g., ``https://your-idp-domain``) + +Provider-Specific Setup Guides +------------------------------- + +Okta +**** + +**OAuth2 Setup:** + +1. Log into your Okta Admin Console +2. Navigate to **Applications** > **Create App Integration** +3. Select **OIDC - OpenID Connect** and **Web Application** +4. Configure: + + * **App integration name**: Your application name + * **Sign-in redirect URIs**: ``https://your-domain.com/complete/okta-oauth2/`` + * **Assignments**: Select which users/groups can access + +5. Save and note: + + * **Client ID** + * **Client Secret** + * **Okta domain** (e.g., ``https://dev-123456.okta.com``) + +**OpenID Connect Setup:** + +Same as OAuth2 above, but use redirect URI:: + + https://your-domain.com/complete/okta-openidconnect/ + +.. important:: + Do NOT use the ``/oauth2/default`` endpoint for Okta authentication. + Use your full Okta domain (e.g., ``https://dev-123456.okta.com/oauth2``) + +Auth0 +***** + +1. Log into your Auth0 Dashboard +2. Navigate to **Applications** > **Create Application** +3. Select **Regular Web Applications** +4. In the application settings: + + * **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. In the **Settings** tab, note: + + * **Domain** (e.g., ``mytenant.auth0.com``) + * **Client ID** + * **Client Secret** + +6. Under **Advanced Settings** > **Grant Types**, ensure these are enabled: + + * Authorization Code + * Refresh Token (if needed) + +Keycloak +******** + +1. Log into your Keycloak Admin Console +2. Select your Realm +3. Navigate to **Clients** > **Create** +4. Configure: + + * **Client ID**: Choose a meaningful name (e.g., ``django-app``) + * **Client Protocol**: ``openid-connect`` + * **Root URL**: ``https://your-domain.com`` + +5. In the client settings: + + * **Access Type**: ``confidential`` + * **Valid Redirect URIs**: ``https://your-domain.com/complete/keycloak/`` + * **Web Origins**: ``https://your-domain.com`` + +6. **Save** and go to the **Credentials** tab to get the **Client Secret** + +7. **Configure mappers** (if needed): + + * Go to **Mappers** > **Create** + * Create an **Audience Mapper** to ensure your ``client_id`` is in the JWT's ``aud`` claim + +8. **Configure algorithms** (recommended): + + * Go to **Fine Grain OpenID Connect Configuration** + * Set **User Info Signed Response Algorithm** to ``RS256`` + * Set **Request Object Signature Algorithm** to ``RS256`` + +9. Get the public key: + + * Go to **Realm Settings** > **Keys** > **RS256** + * Copy the **Public Key** + +10. Provide to development team: + + * **Client ID** + * **Client Secret** + * **Public Key** (for RS256 signature verification) + * **Authorization URL**: ``https://keycloak.example.com/auth/realms/your-realm/protocol/openid-connect/auth`` + * **Token URL**: ``https://keycloak.example.com/auth/realms/your-realm/protocol/openid-connect/token`` + +Azure Active Directory (Azure AD) +********************************** + +1. Log into the Azure Portal +2. Navigate to **Azure Active Directory** > **App registrations** > **New registration** +3. Configure: + + * **Name**: Your application name + * **Supported account types**: Choose based on your requirements + * **Redirect URI**: Select **Web** and enter ``https://your-domain.com/complete/azuread-oauth2/`` + +4. After registration, note the: + + * **Application (client) ID** + * **Directory (tenant) ID** + +5. Create a **Client Secret**: + + * Go to **Certificates & secrets** > **New client secret** + * Add a description and expiration period + * **Copy the secret value immediately** (you won't be able to see it again) + +6. Configure **API Permissions**: + + * Go to **API permissions** > **Add a permission** + * Select **Microsoft Graph** + * Add these delegated permissions: + + * ``User.Read`` + * ``email`` + * ``openid`` + * ``profile`` + + * Click **Grant admin consent** if required + +7. Provide to development team: + + * **Application (client) ID** (as ``KEY``) + * **Client Secret** (as ``SECRET``) + * **Tenant ID** (as ``TENANT_ID``) + +Google +****** + +1. Go to the `Google Cloud Console`_ +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: + + * **Application type**: Web application + * **Authorized JavaScript origins**: ``https://your-domain.com`` + * **Authorized redirect URIs**: ``https://your-domain.com/complete/google-oauth2/`` + +6. After creation, note: + + * **Client ID** + * **Client Secret** + +7. If needed, configure the **OAuth consent screen**: + + * Set application name, logo, and privacy policy + * Add required scopes (``email``, ``profile``, ``openid``) + +Common Configuration Issues +---------------------------- + +Redirect URI Mismatch +********************* + +**Error**: "Redirect URI mismatch" or "Invalid redirect URI" + +**Solution**: Ensure the redirect URI configured in your IdP **exactly matches** the URL format used by Python Social Auth, including: + +* Protocol (``http://`` vs ``https://``) +* Domain name (including subdomain) +* Port number (if non-standard) +* Path (including trailing slash) + +Example of correct matching:: + + IdP Setting: https://app.example.com/complete/oidc/ + Application URL: https://app.example.com/complete/oidc/ + ✓ Match! + +Example of incorrect matching:: + + IdP Setting: https://app.example.com/complete/oidc + Application URL: https://app.example.com/complete/oidc/ + ✗ Mismatch! (missing trailing slash) + +Multiple Redirect URIs +*********************** + +If you need to support multiple environments (development, staging, production), configure all redirect URIs in your IdP: + +* ``http://localhost:8000/complete/oidc/`` (local development) +* ``https://staging.example.com/complete/oidc/`` (staging) +* ``https://app.example.com/complete/oidc/`` (production) + +HTTPS Requirement +***************** + +Most IdPs require HTTPS redirect URIs in production. For local development: + +* Use ``http://localhost:8000`` or ``http://127.0.0.1:8000`` +* Some IdPs allow HTTP for localhost/development environments +* For proper testing, consider using a tool like ngrok to create HTTPS tunnels + +Scopes and Claims +***************** + +Ensure the required scopes are configured in your IdP: + +**Minimum recommended scopes:** + +* ``openid`` - Required for OIDC +* ``profile`` - User's basic profile (name, username) +* ``email`` - User's email address + +**Optional scopes:** + +* ``offline_access`` - For refresh tokens (long-lived sessions) +* ``groups`` - User's group memberships +* Custom scopes based on your application needs + +Testing the Configuration +-------------------------- + +After configuring your IdP, test the integration: + +1. **Test the Discovery Endpoint** (for OIDC):: + + curl https://your-idp-domain/.well-known/openid-configuration + + This should return a JSON document with authorization and token endpoints. + +2. **Test the Authentication Flow**: + + * Navigate to your application's login page + * Click the SSO/OIDC login button + * You should be redirected to the IdP's login page + * After successful login, you should be redirected back to your application + +3. **Check for Common Issues**: + + * Verify the redirect URI is correctly configured + * Ensure the client secret hasn't expired + * Check that required scopes are granted + * Verify user permissions and assignments in the IdP + +4. **Review Application Logs**: + + Ask your development team to check the application logs for any authentication errors. + +Django-Specific Configuration Notes +------------------------------------ + +For Django applications using ``social-auth-app-django``: + +**URL Configuration** + +The URLs are typically configured in your ``urls.py``:: + + urlpatterns = [ + ... + path("", include('social_django.urls', namespace="social")), + ... + ] + +This creates the following URL patterns: + +* ``/login//`` - Initiates authentication +* ``/complete//`` - Handles the callback (redirect URI) +* ``/disconnect//`` - Disconnects the social account + +**Custom Namespace** + +If using a custom namespace, the redirect URI changes:: + + # urls.py + path("auth/", include('social_django.urls', namespace="social")), + +The redirect URI becomes:: + + https://your-domain.com/auth/complete// + +Security Considerations +----------------------- + +1. **Use HTTPS**: Always use HTTPS in production for redirect URIs +2. **Validate State Parameter**: Python Social Auth handles this automatically +3. **Rotate Secrets**: Regularly rotate client secrets +4. **Limit Scopes**: Only request the minimum required scopes +5. **Monitor Access**: Keep logs of authentication attempts +6. **User Consent**: Ensure users understand what data is being shared +7. **Session Security**: Configure secure session cookies in your application + +Additional Resources +-------------------- + +* :doc:`backends/oidc` - OIDC backend documentation +* :doc:`backends/okta` - Okta-specific setup +* :doc:`backends/keycloak` - Keycloak-specific setup +* :doc:`backends/azuread` - Azure AD-specific setup +* :doc:`configuration/django` - Django framework configuration +* :doc:`configuration/settings` - General settings documentation + +For backend-specific details, see the :doc:`backends/index` documentation. + +.. _Google Cloud Console: https://console.cloud.google.com/ diff --git a/docs/index.rst b/docs/index.rst index e71f6e5c..dc7fc0e5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,6 +24,7 @@ Code and other contributions are welcome. The code is hosted on GitHub_. intro maintainers installing + idp_setup_guide configuration/index pipeline strategies From bb3e6a3ee38aa5670e3039bc84617578052272e8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 10 Nov 2025 18:16:43 +0000 Subject: [PATCH 3/4] Update existing backend docs with concise IdP setup instructions Co-authored-by: nijel <212189+nijel@users.noreply.github.com> --- docs/backends/auth0_openidconnect.rst | 24 +- docs/backends/azuread.rst | 52 +++- docs/backends/google.rst | 31 +- docs/backends/keycloak.rst | 42 ++- docs/backends/oidc.rst | 19 ++ docs/backends/okta.rst | 54 +++- docs/idp_setup_guide.rst | 406 -------------------------- docs/index.rst | 1 - 8 files changed, 170 insertions(+), 459 deletions(-) delete mode 100644 docs/idp_setup_guide.rst diff --git a/docs/backends/auth0_openidconnect.rst b/docs/backends/auth0_openidconnect.rst index 81c9133f..2f489361 100644 --- a/docs/backends/auth0_openidconnect.rst +++ b/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 = '' diff --git a/docs/backends/azuread.rst b/docs/backends/azuread.rst index ddf2f0d1..920fffe1 100644 --- a/docs/backends/azuread.rst +++ b/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 as 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:: diff --git a/docs/backends/google.rst b/docs/backends/google.rst index c15067c2..a7986e1b 100644 --- a/docs/backends/google.rst +++ b/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 `_ +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** (``API & auth -> 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:: diff --git a/docs/backends/keycloak.rst b/docs/backends/keycloak.rst index bc4f81ef..23f3dfb9 100644 --- a/docs/backends/keycloak.rst +++ b/docs/backends/keycloak.rst @@ -3,9 +3,34 @@ 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**, 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 = ( ... @@ -13,14 +38,7 @@ To enable Keycloak as a backend: '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: ``/login/keycloak`` and the authorization code flow should commence. - User ID Configuration --------------------- diff --git a/docs/backends/oidc.rst b/docs/backends/oidc.rst index 6f0c77af..fa1c2f6d 100644 --- a/docs/backends/oidc.rst +++ b/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 above +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 --------------------------------- diff --git a/docs/backends/okta.rst b/docs/backends/okta.rst index a52b55fa..d324bd70 100644 --- a/docs/backends/okta.rst +++ b/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 = '' diff --git a/docs/idp_setup_guide.rst b/docs/idp_setup_guide.rst deleted file mode 100644 index 9d0f0a1f..00000000 --- a/docs/idp_setup_guide.rst +++ /dev/null @@ -1,406 +0,0 @@ -Identity Provider (IdP) Setup Guide -==================================== - -This guide helps Identity Provider (IdP) administrators configure their systems to work with applications using Python Social Auth, particularly for OIDC (OpenID Connect) and SSO (Single Sign-On) implementations. - -.. contents:: Table of Contents - :local: - :depth: 2 - -Overview --------- - -When integrating your application with an Identity Provider for authentication, the IdP administrator needs to configure several settings. This guide provides the essential information needed to complete that setup. - -Understanding the Redirect URI / Callback URL ----------------------------------------------- - -The **Redirect URI** (also called **Callback URL**) is the most critical configuration setting. After a user successfully authenticates with the IdP, they are redirected back to your application at this URL. - -**Format:** - -For most backends, the redirect URI follows this pattern:: - - https://your-domain.com/complete// - -**Examples:** - -* OIDC (generic): ``https://example.com/complete/oidc/`` -* Okta OAuth2: ``https://example.com/complete/okta-oauth2/`` -* Okta OpenID Connect: ``https://example.com/complete/okta-openidconnect/`` -* Auth0 OpenID Connect: ``https://example.com/complete/auth0-openidconnect/`` -* Azure AD: ``https://example.com/complete/azuread-oauth2/`` or ``https://example.com/complete/azuread-tenant-oauth2/`` -* Keycloak: ``https://example.com/complete/keycloak/`` -* Google OAuth2: ``https://example.com/complete/google-oauth2/`` -* GitHub: ``https://example.com/complete/github/`` - -.. note:: - Replace ``https://example.com`` with your actual application domain. - If your application is running on a different path or port, adjust accordingly. - For development: ``http://localhost:8000/complete//`` - -.. warning:: - The redirect URI must use **HTTPS** in production environments. - Most IdPs will reject HTTP URLs for security reasons. - -Required Information from Application Developers -------------------------------------------------- - -Before starting the IdP configuration, gather this information from your application development team: - -1. **Backend Name**: Which authentication backend is being used (e.g., ``oidc``, ``okta-openidconnect``, ``keycloak``) -2. **Application Domain**: The full domain where the application is hosted -3. **Required Scopes**: What user information the application needs (typically: ``openid``, ``profile``, ``email``) -4. **Additional Settings**: Any backend-specific requirements - -Generic OIDC Provider Setup ----------------------------- - -For a generic OpenID Connect provider, follow these steps: - -1. **Create a new Application/Client** - - * Choose "Web Application" as the application type - * Note the ``Client ID`` and ``Client Secret`` generated - -2. **Configure the Redirect URI** - - Set the redirect URI to:: - - https://your-domain.com/complete/oidc/ - -3. **Configure Scopes/Permissions** - - Enable at least these scopes: - - * ``openid`` - Required for OpenID Connect - * ``profile`` - User profile information - * ``email`` - User email address - -4. **OIDC Discovery Endpoint** - - Ensure your IdP exposes the OpenID Connect discovery endpoint:: - - https://your-idp-domain/.well-known/openid-configuration - - The Python Social Auth backend will automatically discover endpoints from this URL. - -5. **Provide to Development Team** - - Give these values to your application developers: - - * ``Client ID`` - * ``Client Secret`` - * ``OIDC Endpoint`` (e.g., ``https://your-idp-domain``) - -Provider-Specific Setup Guides -------------------------------- - -Okta -**** - -**OAuth2 Setup:** - -1. Log into your Okta Admin Console -2. Navigate to **Applications** > **Create App Integration** -3. Select **OIDC - OpenID Connect** and **Web Application** -4. Configure: - - * **App integration name**: Your application name - * **Sign-in redirect URIs**: ``https://your-domain.com/complete/okta-oauth2/`` - * **Assignments**: Select which users/groups can access - -5. Save and note: - - * **Client ID** - * **Client Secret** - * **Okta domain** (e.g., ``https://dev-123456.okta.com``) - -**OpenID Connect Setup:** - -Same as OAuth2 above, but use redirect URI:: - - https://your-domain.com/complete/okta-openidconnect/ - -.. important:: - Do NOT use the ``/oauth2/default`` endpoint for Okta authentication. - Use your full Okta domain (e.g., ``https://dev-123456.okta.com/oauth2``) - -Auth0 -***** - -1. Log into your Auth0 Dashboard -2. Navigate to **Applications** > **Create Application** -3. Select **Regular Web Applications** -4. In the application settings: - - * **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. In the **Settings** tab, note: - - * **Domain** (e.g., ``mytenant.auth0.com``) - * **Client ID** - * **Client Secret** - -6. Under **Advanced Settings** > **Grant Types**, ensure these are enabled: - - * Authorization Code - * Refresh Token (if needed) - -Keycloak -******** - -1. Log into your Keycloak Admin Console -2. Select your Realm -3. Navigate to **Clients** > **Create** -4. Configure: - - * **Client ID**: Choose a meaningful name (e.g., ``django-app``) - * **Client Protocol**: ``openid-connect`` - * **Root URL**: ``https://your-domain.com`` - -5. In the client settings: - - * **Access Type**: ``confidential`` - * **Valid Redirect URIs**: ``https://your-domain.com/complete/keycloak/`` - * **Web Origins**: ``https://your-domain.com`` - -6. **Save** and go to the **Credentials** tab to get the **Client Secret** - -7. **Configure mappers** (if needed): - - * Go to **Mappers** > **Create** - * Create an **Audience Mapper** to ensure your ``client_id`` is in the JWT's ``aud`` claim - -8. **Configure algorithms** (recommended): - - * Go to **Fine Grain OpenID Connect Configuration** - * Set **User Info Signed Response Algorithm** to ``RS256`` - * Set **Request Object Signature Algorithm** to ``RS256`` - -9. Get the public key: - - * Go to **Realm Settings** > **Keys** > **RS256** - * Copy the **Public Key** - -10. Provide to development team: - - * **Client ID** - * **Client Secret** - * **Public Key** (for RS256 signature verification) - * **Authorization URL**: ``https://keycloak.example.com/auth/realms/your-realm/protocol/openid-connect/auth`` - * **Token URL**: ``https://keycloak.example.com/auth/realms/your-realm/protocol/openid-connect/token`` - -Azure Active Directory (Azure AD) -********************************** - -1. Log into the Azure Portal -2. Navigate to **Azure Active Directory** > **App registrations** > **New registration** -3. Configure: - - * **Name**: Your application name - * **Supported account types**: Choose based on your requirements - * **Redirect URI**: Select **Web** and enter ``https://your-domain.com/complete/azuread-oauth2/`` - -4. After registration, note the: - - * **Application (client) ID** - * **Directory (tenant) ID** - -5. Create a **Client Secret**: - - * Go to **Certificates & secrets** > **New client secret** - * Add a description and expiration period - * **Copy the secret value immediately** (you won't be able to see it again) - -6. Configure **API Permissions**: - - * Go to **API permissions** > **Add a permission** - * Select **Microsoft Graph** - * Add these delegated permissions: - - * ``User.Read`` - * ``email`` - * ``openid`` - * ``profile`` - - * Click **Grant admin consent** if required - -7. Provide to development team: - - * **Application (client) ID** (as ``KEY``) - * **Client Secret** (as ``SECRET``) - * **Tenant ID** (as ``TENANT_ID``) - -Google -****** - -1. Go to the `Google Cloud Console`_ -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: - - * **Application type**: Web application - * **Authorized JavaScript origins**: ``https://your-domain.com`` - * **Authorized redirect URIs**: ``https://your-domain.com/complete/google-oauth2/`` - -6. After creation, note: - - * **Client ID** - * **Client Secret** - -7. If needed, configure the **OAuth consent screen**: - - * Set application name, logo, and privacy policy - * Add required scopes (``email``, ``profile``, ``openid``) - -Common Configuration Issues ----------------------------- - -Redirect URI Mismatch -********************* - -**Error**: "Redirect URI mismatch" or "Invalid redirect URI" - -**Solution**: Ensure the redirect URI configured in your IdP **exactly matches** the URL format used by Python Social Auth, including: - -* Protocol (``http://`` vs ``https://``) -* Domain name (including subdomain) -* Port number (if non-standard) -* Path (including trailing slash) - -Example of correct matching:: - - IdP Setting: https://app.example.com/complete/oidc/ - Application URL: https://app.example.com/complete/oidc/ - ✓ Match! - -Example of incorrect matching:: - - IdP Setting: https://app.example.com/complete/oidc - Application URL: https://app.example.com/complete/oidc/ - ✗ Mismatch! (missing trailing slash) - -Multiple Redirect URIs -*********************** - -If you need to support multiple environments (development, staging, production), configure all redirect URIs in your IdP: - -* ``http://localhost:8000/complete/oidc/`` (local development) -* ``https://staging.example.com/complete/oidc/`` (staging) -* ``https://app.example.com/complete/oidc/`` (production) - -HTTPS Requirement -***************** - -Most IdPs require HTTPS redirect URIs in production. For local development: - -* Use ``http://localhost:8000`` or ``http://127.0.0.1:8000`` -* Some IdPs allow HTTP for localhost/development environments -* For proper testing, consider using a tool like ngrok to create HTTPS tunnels - -Scopes and Claims -***************** - -Ensure the required scopes are configured in your IdP: - -**Minimum recommended scopes:** - -* ``openid`` - Required for OIDC -* ``profile`` - User's basic profile (name, username) -* ``email`` - User's email address - -**Optional scopes:** - -* ``offline_access`` - For refresh tokens (long-lived sessions) -* ``groups`` - User's group memberships -* Custom scopes based on your application needs - -Testing the Configuration --------------------------- - -After configuring your IdP, test the integration: - -1. **Test the Discovery Endpoint** (for OIDC):: - - curl https://your-idp-domain/.well-known/openid-configuration - - This should return a JSON document with authorization and token endpoints. - -2. **Test the Authentication Flow**: - - * Navigate to your application's login page - * Click the SSO/OIDC login button - * You should be redirected to the IdP's login page - * After successful login, you should be redirected back to your application - -3. **Check for Common Issues**: - - * Verify the redirect URI is correctly configured - * Ensure the client secret hasn't expired - * Check that required scopes are granted - * Verify user permissions and assignments in the IdP - -4. **Review Application Logs**: - - Ask your development team to check the application logs for any authentication errors. - -Django-Specific Configuration Notes ------------------------------------- - -For Django applications using ``social-auth-app-django``: - -**URL Configuration** - -The URLs are typically configured in your ``urls.py``:: - - urlpatterns = [ - ... - path("", include('social_django.urls', namespace="social")), - ... - ] - -This creates the following URL patterns: - -* ``/login//`` - Initiates authentication -* ``/complete//`` - Handles the callback (redirect URI) -* ``/disconnect//`` - Disconnects the social account - -**Custom Namespace** - -If using a custom namespace, the redirect URI changes:: - - # urls.py - path("auth/", include('social_django.urls', namespace="social")), - -The redirect URI becomes:: - - https://your-domain.com/auth/complete// - -Security Considerations ------------------------ - -1. **Use HTTPS**: Always use HTTPS in production for redirect URIs -2. **Validate State Parameter**: Python Social Auth handles this automatically -3. **Rotate Secrets**: Regularly rotate client secrets -4. **Limit Scopes**: Only request the minimum required scopes -5. **Monitor Access**: Keep logs of authentication attempts -6. **User Consent**: Ensure users understand what data is being shared -7. **Session Security**: Configure secure session cookies in your application - -Additional Resources --------------------- - -* :doc:`backends/oidc` - OIDC backend documentation -* :doc:`backends/okta` - Okta-specific setup -* :doc:`backends/keycloak` - Keycloak-specific setup -* :doc:`backends/azuread` - Azure AD-specific setup -* :doc:`configuration/django` - Django framework configuration -* :doc:`configuration/settings` - General settings documentation - -For backend-specific details, see the :doc:`backends/index` documentation. - -.. _Google Cloud Console: https://console.cloud.google.com/ diff --git a/docs/index.rst b/docs/index.rst index dc7fc0e5..e71f6e5c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,7 +24,6 @@ Code and other contributions are welcome. The code is hosted on GitHub_. intro maintainers installing - idp_setup_guide configuration/index pipeline strategies From 84fbc4d2dad84d939d01f1be4184f28f07659727 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 10 Nov 2025 18:52:29 +0000 Subject: [PATCH 4/4] Apply code review feedback: fix formatting and clarify references Co-authored-by: nijel <212189+nijel@users.noreply.github.com> --- docs/backends/azuread.rst | 2 +- docs/backends/google.rst | 2 +- docs/backends/keycloak.rst | 2 +- docs/backends/oidc.rst | 2 +- docs/backends/okta.rst | 8 ++++---- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/backends/azuread.rst b/docs/backends/azuread.rst index 920fffe1..20c3496a 100644 --- a/docs/backends/azuread.rst +++ b/docs/backends/azuread.rst @@ -71,7 +71,7 @@ possible to use a version of the backend with tenant support. IdP Setup for Tenant ^^^^^^^^^^^^^^^^^^^^^ -Follow the same IdP setup steps as above, but use redirect URI:: +Follow the same IdP setup steps from the 'IdP Setup' section above, but use redirect URI:: https://your-domain.com/complete/azuread-tenant-oauth2/ diff --git a/docs/backends/google.rst b/docs/backends/google.rst index a7986e1b..15eec8f7 100644 --- a/docs/backends/google.rst +++ b/docs/backends/google.rst @@ -53,7 +53,7 @@ To configure Google OAuth2: * **Authorized redirect URIs**: ``https://your-domain.com/complete/google-oauth2/`` 6. Note the **Client ID** and **Client Secret** -7. Configure the **OAuth consent screen** (``API & auth -> Consent screen``): +7. Configure the **OAuth consent screen** (``APIs & Services > OAuth consent screen``): * Set the **PRODUCT NAME** and other required fields * Add scopes: ``email``, ``profile``, ``openid`` diff --git a/docs/backends/keycloak.rst b/docs/backends/keycloak.rst index 23f3dfb9..2c913ce4 100644 --- a/docs/backends/keycloak.rst +++ b/docs/backends/keycloak.rst @@ -18,7 +18,7 @@ To configure Keycloak: * **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**, set: +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`` diff --git a/docs/backends/oidc.rst b/docs/backends/oidc.rst index fa1c2f6d..88c9ffd0 100644 --- a/docs/backends/oidc.rst +++ b/docs/backends/oidc.rst @@ -29,7 +29,7 @@ To configure your OIDC Identity Provider for use with this backend: 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 above +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:: diff --git a/docs/backends/okta.rst b/docs/backends/okta.rst index d324bd70..74bc08a3 100644 --- a/docs/backends/okta.rst +++ b/docs/backends/okta.rst @@ -26,8 +26,8 @@ To configure Okta for OAuth2: 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:: +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 = '' @@ -46,8 +46,8 @@ Follow the same steps as OAuth2 above, but use the redirect URI:: 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:: +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 = ''