✨(backend) add associate_by_email step to social auth pipeline

Add social auth pipeline step `associate_by_email`
when RENATER_FER_SAML switch is active.

Author: kernicPanel

CHANGELOG.md

@@ -13,6 +13,10 @@ Versioning](https://semver.org/spec/v2.0.0.html).
 - Remove all legacy Cloudfront code and mentions
 - Remove all legacy Lambdas
 
+### Changed
+
+- Use associate_by_email when RENATER_FER_SAML switch is enabled
+
 ## [5.11.1] - 2025-07-17
 
 ### Fixed

src/backend/marsha/account/social_pipeline/__init__.py

@@ -24,10 +24,20 @@
     set(_steps_mapping.keys()) & set(DEFAULT_EDU_FED_AUTH_PIPELINE)
 ) == len(_steps_mapping)
 
+MARSHA_DEFAULT_AUTH_PIPELINE = []
+for step in DEFAULT_EDU_FED_AUTH_PIPELINE:
+    if step == "social_edu_federation.pipeline.user.create_user":
+        # Associate by email must be before user creation
+        MARSHA_DEFAULT_AUTH_PIPELINE.append(
+            "marsha.account.social_pipeline.social_auth.associate_by_email"
+        )
 
-MARSHA_DEFAULT_AUTH_PIPELINE = tuple(
-    _steps_mapping.get(step, step) for step in DEFAULT_EDU_FED_AUTH_PIPELINE
-) + (
+    if step in _steps_mapping:
+        MARSHA_DEFAULT_AUTH_PIPELINE.append(_steps_mapping[step])
+    else:
+        MARSHA_DEFAULT_AUTH_PIPELINE.append(step)
+
+MARSHA_DEFAULT_AUTH_PIPELINE += [
     "marsha.account.social_pipeline.organization.create_organization_from_saml",
     "marsha.account.social_pipeline.playlist.create_playlist_from_saml",
-)
+]

src/backend/marsha/account/social_pipeline/social_auth.py

@@ -1,6 +1,7 @@
 """Marsha's specific Python Social Auth pipeline steps for authentication."""
 
 from social_core.pipeline.social_auth import (
+    associate_by_email as social_associate_by_email,
     auth_allowed as social_auth_allowed,
     social_details as social_social_details,
 )
@@ -47,3 +48,13 @@ def social_details(backend, details, response, *args, **kwargs):
         details["last_name"] = fullname
 
     return results_dict
+
+
+def associate_by_email(backend, details, *args, user=None, **kwargs):
+    """
+    Associates user by email when the RENATER_FER_SAML feature is enabled.
+    """
+    if not waffle.switch_is_active(RENATER_FER_SAML):
+        return None
+
+    return social_associate_by_email(backend, details, user, *args, **kwargs)

src/backend/marsha/account/tests/test_social_pipeline_social_auth.py

@@ -9,7 +9,11 @@
 from waffle.testutils import override_switch
 
 from marsha.account.social_pipeline import MARSHA_DEFAULT_AUTH_PIPELINE
-from marsha.account.social_pipeline.social_auth import auth_allowed, social_details
+from marsha.account.social_pipeline.social_auth import (
+    associate_by_email,
+    auth_allowed,
+    social_details,
+)
 from marsha.core.defaults import RENATER_FER_SAML
 
 
@@ -188,3 +192,87 @@ def test_social_details_step_without_names(self):
                 social_details(backend, details, response=None),
                 {"details": {"first_name": "", "last_name": ""}},
             )
+
+
+class AssociateByEmailPipelineTestCase(TestCase):
+    """Test case for the `associate_by_email` pipeline step."""
+
+    maxDiff = None
+
+    def test_marsha_pipeline_includes_associate_by_email_step(self):
+        """Asserts the `associate_by_email` step is in Marsha's default pipeline."""
+        self.assertListEqual(
+            [
+                "marsha.account.social_pipeline.social_auth.social_details",
+                "social_core.pipeline.social_auth.social_uid",
+                "marsha.account.social_pipeline.social_auth.auth_allowed",
+                "social_core.pipeline.social_auth.social_user",
+                "social_core.pipeline.user.get_username",
+                "marsha.account.social_pipeline.social_auth.associate_by_email",
+                "social_edu_federation.pipeline.user.create_user",
+                "social_core.pipeline.social_auth.associate_user",
+                "social_core.pipeline.social_auth.load_extra_data",
+                "social_core.pipeline.user.user_details",
+                "marsha.account.social_pipeline.organization.create_organization_from_saml",
+                "marsha.account.social_pipeline.playlist.create_playlist_from_saml",
+            ],
+            MARSHA_DEFAULT_AUTH_PIPELINE,
+            msg="MARSHA_DEFAULT_AUTH_PIPELINE must be fixed to include `associate_by_email`",
+        )
+
+        self.assertListEqual(
+            [
+                "marsha.account.social_pipeline.social_auth.social_details",
+                "social_core.pipeline.social_auth.social_uid",
+                "marsha.account.social_pipeline.social_auth.auth_allowed",
+                "social_core.pipeline.social_auth.social_user",
+                "social_core.pipeline.user.get_username",
+                "marsha.account.social_pipeline.social_auth.associate_by_email",
+                "social_edu_federation.pipeline.user.create_user",
+                "social_core.pipeline.social_auth.associate_user",
+                "social_core.pipeline.social_auth.load_extra_data",
+                "social_core.pipeline.user.user_details",
+                "marsha.account.social_pipeline.organization.create_organization_from_saml",
+                "marsha.account.social_pipeline.playlist.create_playlist_from_saml",
+            ],
+            settings.SOCIAL_AUTH_SAML_FER_PIPELINE,
+            msg="SOCIAL_AUTH_SAML_FER_PIPELINE must be fixed to include `associate_by_email`",
+        )
+
+    @override_switch(RENATER_FER_SAML, active=True)
+    def test_associate_by_email_step_enabled(self):
+        """Asserts the email is used to associate the user when the waffle switch is enabled."""
+        strategy = load_strategy()
+        backend = load_backend(strategy, "saml_fer", None)
+        with mock.patch(
+            "marsha.account.social_pipeline.social_auth.social_associate_by_email"
+        ) as social_associate_by_email_mock:
+            details = {"not": "relevant"}
+
+            associate_by_email(backend, details, strategy, 42, some_kwargs=18)
+
+            social_associate_by_email_mock.assert_called_once_with(
+                backend,
+                details,
+                None,
+                strategy,
+                42,
+                some_kwargs=18,
+            )
+
+    @override_switch(RENATER_FER_SAML, active=False)
+    def test_associate_by_email_step_disabled(self):
+        """
+        Asserts the email is not used to associate the user when the waffle switch is disabled.
+        """
+        strategy = load_strategy()
+        backend = load_backend(strategy, "saml_fer", None)
+        with mock.patch(
+            "marsha.account.social_pipeline.social_auth.social_associate_by_email"
+        ) as social_associate_by_email_mock:
+            details = {"not": "relevant"}
+
+            self.assertIsNone(
+                associate_by_email(backend, details, strategy, 42, some_kwargs=18)
+            )
+            self.assertFalse(social_associate_by_email_mock.called)