📝 [#4246] Update changelog and documentation

Documented the default legacy behaviour of OIDC callback endpoints, and
update the configuration docs to make people favour the new settings.

A future PR will use a feature flag approach combined with detection
of new/existing instances to apply the most sensible configuration, so
that we don't need people to opt-in to the envvars.

CHANGELOG.rst

@@ -2,17 +2,39 @@
 Changelog
 =========
 
-2.7.0-alpha.1 (2024-XX-XX)
-==========================
+2.7.0 "TBD" (2024-07-??)
+========================
 
-This is an alpha release, meaning it is not finished yet or suitable for production use.
+This release is in development, meaning it is not finished yet or suitable for
+production use.
 
 Upgrade notes
 -------------
 
 * ⚠️ The feature flag to disable backend validation is now removed, instances relying
   on it should verify that their existing forms works with the validation enforced.
 
+* We're consolidating the OpenID Connect *Redirect URI* endpoints into a single
+  endpoint: ``/auth/oidc/callback/``. The legacy endpoints are still enabled (by default),
+  but scheduled for removal in Open Forms 3.0.
+
+  You can already opt-in to the new behaviour through three environment variables:
+
+  - ``USE_LEGACY_OIDC_ENDPOINTS=false``: admin login
+  - ``USE_LEGACY_DIGID_EH_OIDC_ENDPOINTS=false``: DigiD/eHerkenning plugins
+  - ``USE_LEGACY_ORG_OIDC_ENDPOINTS=false``: Organization OIDC plugin
+
+  Note that the OpenID applications need to be updated on the identity provider,
+  specifically the allowed "Redirect URIs" setting needs to be updated with the
+  following path replacements:
+
+  - ``/oidc/callback/`` -> ``/auth/oidc/callback/``
+  - ``/digid-oidc/callback/`` -> ``/auth/oidc/callback/``
+  - ``/eherkenning-oidc/callback/`` -> ``/auth/oidc/callback/``
+  - ``/digid-machtigen-oidc/callback/`` -> ``/auth/oidc/callback/``
+  - ``/eherkenning-bewindvoering-oidc/callback/`` -> ``/auth/oidc/callback/``
+  - ``/org-oidc/callback/`` -> ``/auth/oidc/callback/``
+
 2.6.7 (2024-05-22)
 ==================
 

docs/configuration/authentication/oidc_digid.rst

@@ -17,15 +17,31 @@ flow:
 
 .. _configuration_oidc_digid_appgroup:
 
-Configureren van OIDC voor DigiD
-================================
+Configureren van OIDC-provider
+==============================
 
 Contacteer de IAM beheerders in je organisatie om een *Client* aan te
 maken in de omgeving van de OpenID Connect provider.
 
+**Redirect URI (vanaf Open Formulieren 2.7.0)**
+
+.. warning::
+
+    Zorg dat Open Formulieren :ref:`geïnstalleerd <installation_index>` is met de
+    ``USE_LEGACY_DIGID_EH_OIDC_ENDPOINTS=false``
+    :ref:`omgevingsvariabele<installation_environment_config>`, anders worden de legacy
+    (zie hieronder) endpoints gebruikt.
+
+Voor de **Redirect URI** vul je ``https://open-formulieren.gemeente.nl/auth/oidc/callback/`` in,
+waarbij je ``open-formulieren.gemeente.nl`` vervangt door het relevante domein.
+
+**Redirect URI (legacy)**
+
 Voor de **Redirect URI** vul je ``https://open-formulieren.gemeente.nl/digid-oidc/callback/`` in,
 waarbij je ``open-formulieren.gemeente.nl`` vervangt door het relevante domein.
 
+**Gegevens**
+
 Aan het eind van dit proces moet je de volgende gegevens hebben:
 
 * Server adres, bijvoorbeeld ``login.gemeente.nl``

docs/configuration/authentication/oidc_eherkenning.rst

@@ -17,15 +17,31 @@ flow:
 
 .. _configuration_oidc_eherkenning_appgroup:
 
-Configureren van OIDC voor eHerkenning
-======================================
+Configureren van OIDC-provider
+==============================
 
 Contacteer de IAM beheerders in je organisatie om een *Client* aan te
 maken in de omgeving van de OpenID Connect provider.
 
+**Redirect URI (vanaf Open Formulieren 2.7.0)**
+
+.. warning::
+
+    Zorg dat Open Formulieren :ref:`geïnstalleerd <installation_index>` is met de
+    ``USE_LEGACY_DIGID_EH_OIDC_ENDPOINTS=false``
+    :ref:`omgevingsvariabele<installation_environment_config>`, anders worden de legacy
+    (zie hieronder) endpoints gebruikt.
+
+Voor de **Redirect URI** vul je ``https://open-formulieren.gemeente.nl/auth/oidc/callback/`` in,
+waarbij je ``open-formulieren.gemeente.nl`` vervangt door het relevante domein.
+
+**Redirect URI (legacy)**
+
 Voor de **Redirect URI** vul je ``https://open-formulieren.gemeente.nl/eherkenning-oidc/callback/`` in,
 waarbij je ``open-formulieren.gemeente.nl`` vervangt door het relevante domein.
 
+**Gegevens**
+
 Aan het eind van dit proces moet je de volgende gegevens hebben:
 
 * Server adres, bijvoorbeeld ``login.gemeente.nl``

docs/configuration/authentication/oidc_machtigen.rst

@@ -4,28 +4,33 @@
 OpenID Connect voor inloggen met DigiD Machtigen en eHerkenning bewindvoering
 =============================================================================
 
-Open Formulieren ondersteunt `DigiD Machtigen`_ en eHerkenning bewindvoering login voor burgers via het OpenID Connect
-protocol (OIDC).
-Burgers kunnen inloggen op Open Formulieren met hun DigiD/eHerkenning account en een formulier invullen namens iemand
+Open Formulieren ondersteunt `DigiD Machtigen`_ en eHerkenning bewindvoering login voor
+burgers via het OpenID Connect protocol (OIDC). Burgers kunnen inloggen op Open
+Formulieren met hun DigiD/eHerkenning account en een formulier invullen namens iemand
 anders. In deze flow:
 
-* Een gebruiker klikt op de knop *Inloggen met DigiD Machtigen* of *Inloggen met eHerkenning bewindvoering* die op de startpagina van een formulier staat.
-* De gebruiker wordt via de omgeving van de OpenID Connect provider (bijv. `Keycloak`_) naar DigiD/eHerkenning geleid, waar de gebruiker kan inloggen met *hun eigen* DigiD/eHerkenning inloggegevens.
+* Een gebruiker klikt op de knop *Inloggen met DigiD Machtigen* of *Inloggen met
+  eHerkenning bewindvoering* die op de startpagina van een formulier staat.
+* De gebruiker wordt via de omgeving van de OpenID Connect provider (bijv. `Keycloak`_)
+  naar DigiD/eHerkenning geleid, waar de gebruiker kan inloggen met *hun eigen*
+  DigiD/eHerkenning inloggegevens.
 * De gebruiker kan dan kiezen namens wie ze het formulier willen invullen.
-* De gebruiker wordt daarna terug naar de OIDC omgeving gestuurd, die op zijn beurt de gebruiker weer terugstuurt naar Open Formulieren
+* De gebruiker wordt daarna terug naar de OIDC omgeving gestuurd, die op zijn beurt de
+  gebruiker weer terugstuurt naar Open Formulieren
 * De gebruiker kan verder met het invullen van het formulier
 
 .. _DigiD Machtigen: https://machtigen.digid.nl/
 .. _Keycloak: https://www.keycloak.org/
 
 .. _configuration_oidc_digid_machtigen_appgroup:
 
-Configureren van OIDC voor DigiD Machtigen
-==========================================
+Configureren van OIDC-provider voor DigiD Machtigen
+===================================================
 
-De stappen hier zijn dezelfde als voor :ref:`configuration_oidc_digid_appgroup`, maar de **Redirect URI**
-is ``https://open-formulieren.gemeente.nl/digid-oidc-machtigen/callback/`` (met het juiste domein in plaats van
-``open-formulieren.gemeente.nl``).
+De stappen hier zijn dezelfde als voor :ref:`configuration_oidc_digid_appgroup`.
+
+.. warning:: Indien je de legacy **Redirect URI** gebruikt, dan is de waarde
+   ``https://open-formulieren.gemeente.nl/digid-machtigen-oidc/callback/``.
 
 Aan het eind van dit proces moet u de volgende gegevens hebben:
 
@@ -60,12 +65,13 @@ Nu kan er een formulier aangemaakt worden met het authenticatie backend ``DigiD
 
 .. _configuration_oidc_eh_bewindvoering_appgroup:
 
-Configureren van OIDC voor eHerkenning bewindvoering
-====================================================
+Configureren van OIDC-provider voor eHerkenning bewindvoering
+=============================================================
+
+De stappen hier zijn dezelfde als voor :ref:`configuration_oidc_digid_machtigen_appgroup`.
 
-De stappen hier zijn dezelfde als voor :ref:`configuration_oidc_digid_machtigen_appgroup`, maar de **Redirect URI**
-is ``https://open-formulieren.gemeente.nl/eherkenning-bewindvoering-oidc/callback/`` (met het juiste domein in plaats van
-``open-formulieren.gemeente.nl``).
+.. warning:: Indien je de legacy **Redirect URI** gebruikt, dan is de waarde
+   ``https://open-formulieren.gemeente.nl/eherkenning-bewindvoering-oidc/callback/``.
 
 Aan het eind van dit proces moet u de volgende gegevens hebben:
 

docs/configuration/authentication/oidc_org.rst

@@ -11,29 +11,41 @@ OpenID Connect for organization members
   admins for the management interface, please go 
   :ref:`here <configuration_authentication_oidc>`.
 
-Open Forms supports login on forms by *organization members* through Single Sign On (SSO) via the OpenID Connect protocol (OIDC).
+Open Forms supports login on forms by *organization members* through Single Sign On
+(SSO) via the OpenID Connect protocol (OIDC).
 
-Members of the organization can login to forms for internal use by the organization using the same OpenID Connect configuration that is used for the management interface.
+Members of the organization can login to forms for internal use by the organization
+using the same OpenID Connect configuration that is used for the management interface.
 In this flow:
 
-1. The organization member clicks *Inloggen met OpenID Connect* on the internal form.
-2. The member gets redirected to the login flow of the OpenID Connect provider where the member logs in.
-3. After completion of the OpenID Connect provider login the member is redirected back to the form in Open Forms.
+1. The organization member clicks *Inloggen met OpenID Connect* on the (internal) form.
+2. The member gets redirected to the login flow of the OpenID Connect provider where
+   the member logs in.
+3. After completion of the OpenID Connect provider login the member is redirected back
+   to the form in Open Forms.
 4. The member is now logged into Open Forms and can proceed to complete the form.
-5. Open Forms optionally stores the employee ID (from the OIDC claims) on the user record _and_ the form submission.
+5. Open Forms optionally stores the employee ID (from the OIDC claims) on the user
+   record *and* the form submission.
 
 .. _configuration_authentication_oidc_org_appgroup:
 
 Configuring OIDC for login of organization members
 ==================================================
 
-The OpenID Connect configuration is shared with :ref:`the configuration of the management interface <configuration_authentication_oidc>` and follows the same steps with a few addtional notes:
+The OpenID Connect configuration is shared with
+:ref:`the configuration of the management interface <configuration_authentication_oidc>`
+and follows the same steps with a few addtional notes:
 
-- The plugin callback URL needs to be registered at the OpenID Connect provider. Contact the organizations IAM and ask them add to the whitelist ``https://open-formulieren.gemeente.nl/org-oidc/callback/`` (replace ``open-formulieren.gemeente.nl`` with the domain of your Open Forms installation).
+- It is not recommended to use the *Default groups* configuration option when using
+  OpenID Connect for organization members to authenticate on forms.
 
-- It is not recommended to use the *Default groups* configuration option when using OpenID Connect for organization members to authenticate on forms.
-
-- To store user information from OpenID and track an "Employee ID" it is required to configure the ``claim mapping``. This is JSON object where the claims from the OIDC user-info gets mapped to attributes on the user in Open Forms. For more info and options on configuring the mapping see `mozilla-django-oidc-db <https://github.com/maykinmedia/mozilla-django-oidc-db>`_ (Section 4.1, User profile) and the documentation of your OpenID Connect provider for the structure of the returned user-info.
+- To store user information from OpenID and track an "Employee ID" it is required to
+  configure the ``claim mapping``. This is JSON object where the claims from the OIDC
+  user-info gets mapped to attributes on the user in Open Forms. For more info and
+  options on configuring the mapping see
+  `mozilla-django-oidc-db <https://github.com/maykinmedia/mozilla-django-oidc-db>`_
+  (Section 4.1, User profile) and the documentation of your OpenID Connect provider for
+  the structure of the returned user-info.
 
   Example:
 
@@ -46,13 +58,13 @@ The OpenID Connect configuration is shared with :ref:`the configuration of the m
         "employee_id": "name_of_claim_with_employee_id"
     }
 
-  Note we set the ``employee_id`` to track the member on both the submission and the created user.
+  Note we set the ``employee_id`` to track the member on both the submission and the
+  created user.
 
 - We recommend configuring the roles on the OIDC provider side together with the
   ``Groups glob pattern`` to automatically assign the correct groups when an employee
   authenticates via OIDC. More information about permissions and groups is available
   in the :ref:`manual <manual_accounts>` (in Dutch).
 
-
-After completing these steps a form can be created with the authentication backend ``Organization via OpenID Connect``, see :ref:`manual_forms_basics`.
-
+After completing these steps a form can be created with the authentication backend
+``Organization via OpenID Connect``, see :ref:`manual_forms_basics`.

docs/configuration/general/oidc.rst

@@ -36,6 +36,21 @@ Configureren van OIDC-provider
 Contacteer de IAM beheerders in je organisatie om een *Client* of *App* aan te
 maken in de omgeving van de OpenID Connect provider.
 
+**Redirect URI (vanaf Open Formulieren 2.7.0)**
+
+.. warning::
+
+    Zorg dat Open Formulieren :ref:`geïnstalleerd <installation_index>` is met de
+    ``USE_LEGACY_OIDC_ENDPOINTS=false`` en ``USE_LEGACY_ORG_OIDC_ENDPOINTS=false``
+    :ref:`omgevingsvariabelen<installation_environment_config>`, anders worden de legacy
+    (zie hieronder) endpoints gebruikt.
+
+Voor de **Redirect URI** vul je ``https://open-formulieren.gemeente.nl/auth/oidc/callback/`` in,
+waarbij je ``open-formulieren.gemeente.nl`` vervangt door het relevante domein. Deze
+Redirect URI wordt ook gebruikt voor :ref:`configuration_authentication_oidc_org`.
+
+**Redirect URI (legacy)**
+
 Voor de **Redirect URI** vul je ``https://open-formulieren.gemeente.nl/oidc/callback/`` in,
 waarbij je ``open-formulieren.gemeente.nl`` vervangt door het relevante domein.
 
@@ -44,6 +59,8 @@ formulieren, voeg dan ook direct
 ``https://open-formulieren.gemeente.nl/oidc-org/callback/`` toe. Je kan hier 
 meer over lezen op :ref:`configuration_authentication_oidc_org`.
 
+**Gegevens**
+
 Aan het eind van dit proces moet je de volgende gegevens hebben (on premise):
 
 * Server adres, bijvoorbeeld ``login.gemeente.nl``

docs/installation/config.rst

@@ -242,9 +242,6 @@ Other settings
 * ``CACHE_AXES``: The Redis cache location for Axes (used to prevent brute
   force attacks). Defaults to ``localhost:6379/0``.
 
-* ``CACHE_OIDC``: The Redis cache location for the OIDC configuration. Defaults
-  to ``localhost:6379/0``.
-
 * ``ENVIRONMENT``: Short string to indicate the environment (test, production,
   etc.) Defaults to ``""``.
 
@@ -265,6 +262,23 @@ Other settings
   enable :ref:`Organization accounts <configuration_authentication_oidc>`. Defaults
   to ``False``.
 
+* ``USE_LEGACY_OIDC_ENDPOINTS``: Defaults to ``True`` for backwards compatibility
+  reasons. New installations should opt-out. If ``False``, the OIDC callback URL is
+  ``/auth/oidc/callback/``, if ``True``, it is ``/oidc/callback/``.
+
+* ``USE_LEGACY_DIGID_EH_OIDC_ENDPOINTS``: Defaults to ``True`` for backwards compatibility
+  reasons. New installations should opt-out. If ``False``, the OIDC callback URL is
+  ``/auth/oidc/callback/``, if ``True``, they are:
+
+      - ``/digid-oidc/callback/``
+      - ``/eherkenning-oidc/callback/``
+      - ``/digid-machtigen-oidc/callback/``
+      - ``/eherkenning-bewindvoering-oidc/callback/``
+
+* ``USE_LEGACY_ORG_OIDC_ENDPOINTS``: Defaults to ``True`` for backwards compatibility
+  reasons. New installations should opt-out. If ``False``, the OIDC callback URL is
+  ``/auth/oidc/callback/``, if ``True``, it is ``/org-oidc/callback/``.
+
 * ``SESSION_EXPIRE_AT_BROWSER_CLOSE``: Controls if sessions expire at browser close.
   This applies to both the session of end-users filling out forms and staff using the
   administrative interface. Enabling this forces users to log in every time they open