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..20c3496a 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 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:: diff --git a/docs/backends/google.rst b/docs/backends/google.rst index c15067c2..15eec8f7 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** (``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:: diff --git a/docs/backends/keycloak.rst b/docs/backends/keycloak.rst index bc4f81ef..2c913ce4 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** (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 = ( ... @@ -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..88c9ffd0 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 +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..74bc08a3 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 = ''