[AAP-48066] Allow login from multiple active authenticators (#774)

## Description

This PR is based off of the following
[PoC](#751).

[Jira](https://issues.redhat.com/browse/AAP-48066)

- What is being changed? This PR allows for multiple authenticators to
match to a given AAP user, based on the email as the unifying key. When
attempting to sign in via any authenticator with email -
`[email protected]`, we will sign you into the AAP user associated with
that email, provided only 1 AAP user exists with that email address.
- Why is this change needed? This change is needed to standardize our
users, and provide clear expectations about how users are signed in.
With this change, we will no longer have unique users for each
authenticator, and will instead be able to link multiple authenticators
to a given AAP user.
- How does this change address the issue?
This change addresses the issue by adjusting the logic used to match
users to usernames as described in the
[proposal](https://handbook.eng.ansible.com/proposals/0082-Handling-Sign-In-Via-Multiple-Authenticators).


Note -
This change allows users to log into existing AAP accounts if one
associated with their email exists. However in this flow -
1. Local AAP account created
2. Sign in via LDAP
The user will sign in successfully, but due to how django-auth-ldap
works, it will automatically unset the users local password preventing
them from then signing in via the local password. We may be able to
circumvent this. In my testing so far I have not yet been able too, but
upon thinking about it further, it may be best to avoid circumventing
it, to avoid messing with how django-auth-ldap handles its security.

## Type of Change
<!-- Mandatory: Check one or more boxes that apply -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] Documentation update
- [x] Test update
- [ ] Refactoring (no functional changes)
- [ ] Development environment change
- [ ] Configuration change

## Self-Review Checklist
<!-- These items help ensure quality - they complement our automated CI
checks -->
- [ ] I have performed a self-review of my code
- [ ] I have added relevant comments to complex code sections
- [ ] I have updated documentation where needed
- [ ] I have considered the security impact of these changes
- [ ] I have considered performance implications
- [ ] I have thought about error handling and edge cases
- [ ] I have tested the changes in my local environment

## Testing Instructions
<!-- Optional for test-only changes. Mandatory for all other changes -->
<!-- Must be detailed enough for reviewers to reproduce -->
### Prerequisites
<!-- List any specific setup required -->

### Steps to Test (using aap-dev)
1. `make configure-sources`, use this DAB PR
4. `make aap`
5. Configure multiple authenticators such as LDAP, GitHub, SAML, etc in
your AAP environment
6. (Optional) Create a local user, with same email address another
authenticator users, and sign in as local user. Sign in succeeds
7. Check the /api/gateway/v1/users/<ID> endpoint, we should see
associated_authenticators updated with this authenticator reference
8. Sign in via another authenticator (such as github), you should be
signed into the same AAP Account, and now associated_authenticators
should have multiple entries.
9. (Optional) Keep signing in with other authenticators, you should
continue to sign into the same AAP account as long as the same email
address is provided by authenticator

Next test -
1. Create a new local user, without an email
2. Sign in via local, see the user is created and linked to local
authenticator
3. Sign in via authenticator, a new AAP user should be created (Since no
email was available to match on)
4. Sign in via another authenticator (which provides email). We should
link to the AAP account created by the step 3 authenticator.

### Expected Results

User can sign into AAP using any authenticator, and expect to sign into
their existing AAP account, so long as it is associated with a matching
email.

## Additional Context
<!-- Optional but helpful information -->

### Required Actions
<!-- Check if changes require work in other areas -->
<!-- Remove section if no external actions needed -->
- [ ] Requires documentation updates
  <!-- API docs, feature docs, deployment guides -->
- [ ] Requires downstream repository changes
  <!-- Specify repos: django-ansible-base, eda-server, etc. -->
- [ ] Requires infrastructure/deployment changes
  <!-- CI/CD, installer updates, new services -->
- [ ] Requires coordination with other teams
  <!-- UI team, platform services, infrastructure -->
- [ ] Blocked by PR/MR: #XXX
  <!-- Reference blocking PRs/MRs with brief context -->

### Screenshots/Logs
<!-- Add if relevant to demonstrate the changes -->

Author: zkayyali812

ansible_base/authentication/authenticator_plugins/ldap.py

@@ -554,7 +554,13 @@ def authenticate(self, request, username=None, password=None, **kwargs) -> (obje
             # In unit testing there were cases where the function we are in was being called before get_or_build_user.
             # Its unclear if that was just a byproduct of mocking or a real scenario.
             # Since this call is idempotent we are just going to call it again to ensure the AuthenticatorUser is created for update_user_claims
-            get_or_create_authenticator_user(username.lower(), self.database_instance, user_details={}, extra_data=user_from_ldap.ldap_user.attrs.data)
+            get_or_create_authenticator_user(
+                uid=username.lower(),
+                email=user_from_ldap.email,
+                authenticator=self.database_instance,
+                user_details={},
+                extra_data=user_from_ldap.ldap_user.attrs.data,
+            )
             return update_user_claims(user_from_ldap, self.database_instance, users_groups)
         except Exception:
             logger.exception(f"Encountered an error authenticating to LDAP {self.database_instance.name}")
@@ -582,8 +588,9 @@ def get_or_build_user(self, username, ldap_user):
         This gets called by _LDAPUser to create the user in the database.
         """
         user, _authenticator_user, created = get_or_create_authenticator_user(
-            username.lower(),
-            self.database_instance,
+            uid=username.lower(),
+            email=ldap_user.attrs.data.get(ldap_user.settings.USER_ATTR_MAP['email'], ""),
+            authenticator=self.database_instance,
             user_details={
                 "username": username,
             },

ansible_base/authentication/authenticator_plugins/local.py

@@ -9,7 +9,7 @@
 from requests.auth import HTTPBasicAuth
 
 from ansible_base.authentication.authenticator_plugins.base import AbstractAuthenticatorPlugin, BaseAuthenticatorConfiguration
-from ansible_base.authentication.utils.authentication import determine_username_from_uid, get_or_create_authenticator_user
+from ansible_base.authentication.utils.authentication import get_or_create_authenticator_user
 from ansible_base.authentication.utils.claims import update_user_claims
 from ansible_base.lib.utils.settings import get_setting
 
@@ -50,16 +50,6 @@ def authenticate(self, request, username=None, password=None, **kwargs):
             logger.info(f"Local authenticator {self.database_instance.name} is disabled, skipping")
             return None
 
-        # Determine the user name for this authenticator, we have to call this so that we can "attach" to a pre-created user
-        new_username = determine_username_from_uid(username, self.database_instance)
-        # However we can't really accept a different username because we are the local authenticator imagine if:
-        #    User "a" is from another authenticator and has an AuthenticatorUser
-        #    User "a" tried to login from local authenticator
-        #    The above function will return a username of "a<hash>"
-        #    We then try to do local authentication with the database from a different username that will not exist in the database, so it would never work
-        if new_username != username:
-            return None
-
         user = super().authenticate(request, username, password, **kwargs)
         controller_login_results = None
         if (
@@ -84,7 +74,8 @@ def authenticate(self, request, username=None, password=None, **kwargs):
         # it has an AuthenticatorUser associated with it.
         if user:
             get_or_create_authenticator_user(
-                username,
+                uid=username,
+                email=user.email,
                 authenticator=self.database_instance,
                 user_details={},
                 extra_data={

ansible_base/authentication/authenticator_plugins/radius.py

@@ -87,7 +87,8 @@ def authenticate(self, request, username=None, password=None, **kwargs):
             return None
 
         user, _authenticator_user, _is_created = get_or_create_authenticator_user(
-            username,
+            uid=username,
+            email="",
             authenticator=self.database_instance,
             user_details={},
             extra_data={"username": username},

ansible_base/authentication/authenticator_plugins/tacacs.py

@@ -119,8 +119,9 @@ def authenticate(self, request, username=None, password=None, **kwargs):
 
             if reply.valid:
                 user, _authenticator_user, _created = get_or_create_authenticator_user(
-                    username,
-                    self.database_instance,
+                    uid=username,
+                    email="",
+                    authenticator=self.database_instance,
                     user_details={},
                     extra_data={'username': username},
                 )

ansible_base/authentication/social_auth.py

@@ -13,6 +13,7 @@
 
 from ansible_base.authentication.authenticator_plugins.utils import generate_authenticator_slug, get_authenticator_class, get_authenticator_plugins
 from ansible_base.authentication.models import Authenticator, AuthenticatorUser
+from ansible_base.authentication.utils.user import normalize_and_get_email
 from ansible_base.lib.utils.response import get_fully_qualified_url
 
 logger = logging.getLogger('ansible_base.authentication.social_auth')
@@ -189,6 +190,41 @@ def validate(self, serializer, data):
         return data
 
 
+def capture_oauth_email_pipeline(*args, backend, details, **kwargs):
+    """
+    Pipeline function to capture and store OAuth provider email in AuthenticatorUser.
+    """
+    if not backend or not hasattr(backend, 'database_instance') or not backend.database_instance:
+        logger.warning("No backend or database_instance found in OAuth email pipeline")
+        return
+
+    user = kwargs.get('user')
+    if not user:
+        return
+
+    uid = kwargs.get('uid')
+    if not uid:
+        logger.warning("No uid found in OAuth email pipeline")
+        return
+
+    email = normalize_and_get_email(details.get('email', ''))
+    if not email:
+        email = ''
+
+    logger.debug(f"Capturing OAuth email for user {user.username}: {email}")
+
+    # Get or update the AuthenticatorUser with the email
+    try:
+        from ansible_base.authentication.utils.authentication import get_or_create_authenticator_user
+
+        get_or_create_authenticator_user(
+            uid=uid, email=email, authenticator=backend.database_instance, user_details=details, extra_data=kwargs.get('response', {})
+        )
+        logger.info(f"Stored OAuth email {email} for user {user.username} from {backend.database_instance.name}")
+    except Exception as e:
+        logger.warning(f"Failed to store OAuth email for user {user.username}: {e}")
+
+
 def create_user_claims_pipeline(*args, backend, response, **kwargs):
     from ansible_base.authentication.utils.claims import update_user_claims
 

ansible_base/authentication/utils/authentication.py

@@ -1,5 +1,5 @@
 import logging
-from typing import Optional, Tuple
+from typing import Optional, Tuple, Union
 
 from django.conf import settings
 from django.contrib.auth import get_user_model
@@ -12,9 +12,12 @@
 from ansible_base.authentication.authenticator_plugins.utils import get_authenticator_class
 from ansible_base.authentication.models import Authenticator, AuthenticatorUser
 from ansible_base.authentication.social_auth import AuthenticatorStorage, AuthenticatorStrategy
+from ansible_base.authentication.utils.user import normalize_and_get_email
 
 logger = logging.getLogger('ansible_base.authentication.utils.authentication')
 
+merge_strategy = "Email fallback"
+
 
 class FakeBackend:
     def setting(self, *args, **kwargs):
@@ -125,18 +128,105 @@ def determine_username_from_uid_social(**kwargs) -> dict:
         )
 
     alt_uid = authenticator.get_alternative_uid(**kwargs)
+    email = kwargs.get('details', {}).get('email', None)
 
     if migrated_username := migrate_from_existing_authenticator(
         uid=kwargs.get("uid"), alt_uid=alt_uid, authenticator=authenticator.database_instance, preferred_username=selected_username
     ):
         username = migrated_username
     else:
-        username = determine_username_from_uid(selected_username, authenticator.database_instance)
+        username = determine_username_from_uid(selected_username, email, authenticator.database_instance)
 
     return {"username": username}
 
 
-def determine_username_from_uid(uid: str = None, authenticator: Authenticator = None, alt_uid: Optional[str] = None) -> str:
+def _handle_no_merge_strategy(uid: str, authenticator: Authenticator) -> str:
+    """Handles the merge strategy where users are unique for each authenticator."""
+    if AuthenticatorUser.objects.filter(Q(uid=uid) | Q(user__username=uid)).exists():
+        # Some other provider is providing this username so we need to create our own username
+        new_username = get_local_username({'username': uid})
+        logger.info(
+            f'Authenticator {authenticator.name} wants to authenticate {uid} but that'
+            f' username is already in use by another authenticator,'
+            f' the user from this authenticator will be {new_username}'
+        )
+        return new_username
+    else:
+        # We didn't have an exact match but no other provider is servicing this uid so lets return that for usage
+        logger.info(f"Authenticator {authenticator.name} is able to authenticate user {uid} as {uid}")
+        return uid
+
+
+def _handle_email_fallback_strategy(uid: str, email: Union[str, list[str], None], authenticator: Authenticator) -> str:
+    """Handles the merge strategy where AAP users are matched by email."""
+    ###
+    # AUTHENTICATION STRATEGY OVERVIEW
+    # For more detailed information, see the following proposal
+    # https://handbook.eng.ansible.com/proposals/0082-Handling-Sign-In-Via-Multiple-Authenticators#how
+    #
+    # The logic below maps to the proposal flowchart, indicated by comments starting with "PROPOSAL FLOW"
+    ###
+    user_model = get_user_model()
+    normalized_email = normalize_and_get_email(email)
+
+    # PROPOSAL FLOW: Authenticator No Email provided
+    if not normalized_email:
+        return _handle_no_merge_strategy(uid, authenticator)  # Logic is identical to the no-merge strategy
+
+    # PROPOSAL FLOW: Authenticator provides email
+    existing_user_match = user_model.objects.filter(email__iexact=normalized_email)
+    user_count = existing_user_match.count()
+
+    # PROPOSAL FLOW: Are there multiple AAP users with this Email? Yes
+    if user_count > 1:
+        logger.warning(f"Found more than 1 user matching {uid}/{email}, unable to determine which user to merge with!")
+        raise AuthException(f"Found more than 1 user matching {uid}/{email}, unable to determine which user to merge with!")
+    # PROPOSAL FLOW: Are there multiple AAP users with this Email? No only 1
+    elif user_count == 1:
+        return existing_user_match.first().username
+    # PROPOSAL FLOW: Does an AAP User with this email exist? No
+    else:
+        new_username = get_local_username({'username': uid})
+        logger.warning(
+            f"Authenticator {authenticator.name} wants to authenticate {uid}/{email} "
+            "but that username is already in use by another authenticator, "
+            f"the user from this authenticator will be {new_username}"
+        )
+        return new_username
+
+
+# def _handle_email_username_fallback_strategy(uid: str, email: Union[str, list[str], None], authenticator: Authenticator) -> str:
+#     """Handles the unused 'Email and Username fallback' strategy."""
+#     # This code is not used anywhere, but is kept here for reference, in case we later want to enable it.
+#     normalized_email = normalize_and_get_email(email)
+
+#     # Note: The original code uses .get(), which will raise an exception if zero or multiple
+#     # objects are found, and then tries to call .count() on the result, which will fail.
+#     # The logic is preserved here as-is.
+#     if not normalized_email:
+#         existing_user_match = Authenticator.objects.get(user__username=uid)
+#     else:
+#         existing_user_match = Authenticator.objects.get(user__email=normalized_email)
+
+#     if existing_user_match.count() == 1:
+#         existing_user = existing_user_match[0].user
+#         new_username = existing_user.username
+#         logger.info(f"Authenticator {authenticator.name} matched {uid}/{email} from provider {existing_user_match[0].provider.name}, combining users")
+#         return new_username
+#     elif existing_user_match.count() > 1:
+#         raise AuthException(f"Found more than 1 user matching {uid}/{email}, unable to determine which user to merge with!")
+#     else:
+#         # Some other provider is providing this username so we need to create our own username
+#         new_username = get_local_username({'username': uid})
+#         logger.info(
+#             f'Authenticator {authenticator.name} wants to authenticate {uid}/{email} but that'
+#             f' username is already in use by another authenticator,'
+#             f' the user from this authenticator will be {new_username}'
+#         )
+#         return new_username
+
+
+def determine_username_from_uid(uid: str = None, email: Union[str, list[str], None] = None, authenticator: Authenticator = None) -> str:
     """
     Determine what the username for the User object will be from the given uid and authenticator
     This will take uid like "bella" and search for an AuthenticatorUser and return:
@@ -157,30 +247,43 @@ def determine_username_from_uid(uid: str = None, authenticator: Authenticator =
         raise
 
     # If we have an AuthenticatorUser with the exact uid and provider than we have a match
-    exact_match = AuthenticatorUser.objects.filter(uid=uid, provider=authenticator)
-    if exact_match.count() == 1:
-        new_username = exact_match[0].user.username
+    if (exact_match := AuthenticatorUser.objects.filter(uid=uid, provider=authenticator)).exists():
+        new_username = exact_match.first().user.username
         logger.info(f"Authenticator {authenticator.name} already authenticated {uid} as {new_username}")
         return new_username
 
-    # We didn't get an exact match. If any other provider is using this uid our id will be uid<hash>
-    if AuthenticatorUser.objects.filter(Q(uid=uid) | Q(user__username=uid)).count() != 0:
-        # Some other provider is providing this username so we need to create our own username
-        new_username = get_local_username({'username': uid})
-        logger.info(
-            f'Authenticator {authenticator.name} wants to authenticate {uid} but that'
-            f' username is already in use by another authenticator,'
-            f' the user from this authenticator will be {new_username}'
-        )
-        return new_username
+    logger.debug(f"Authentication merge strategy is {merge_strategy}")
 
-    # We didn't have an exact match but no other provider is servicing this uid so lets return that for usage
-    logger.info(f"Authenticator {authenticator.name} is able to authenticate user {uid} as {uid}")
-    return uid
+    # Dispatch to the correct handler based on the merge strategy
+    # if merge_strategy == "": # AAP 2.5 Merge Strategy
+    #     return _handle_no_merge_strategy(uid, authenticator)
+    if merge_strategy == "Email fallback":  # AAP 2.6 Default Merge Strategy
+        return _handle_email_fallback_strategy(uid, email, authenticator)
+    # elif merge_strategy == "Email and Username fallback": # In the future, we may want to enable this
+    #     return _handle_email_username_fallback_strategy(uid, email, authenticator)
+    else:
+        raise AuthException(f"Got an invalid merge_strategy {merge_strategy}")
+
+
+def _validate_username_for_new_user(username: str, authenticator: Authenticator):
+    """
+    Prevents creating a user if the username is already tied to another authenticator.
+    Returns True if the username is available, False otherwise.
+
+    Note: This assumes `merge_strategy` is available in the scope, as in the original code.
+    """
+    if merge_strategy is None:
+        if conflicting_user := AuthenticatorUser.objects.filter(user__username=username).first():
+            logger.error(
+                f'Authenticator {authenticator.name} attempted to create an AuthenticatorUser for {username}'
+                f' but that id is already tied to authenticator {conflicting_user.provider.name}'
+            )
+            return False  # Validation failed
+    return True  # Validation passed
 
 
 def get_or_create_authenticator_user(
-    uid: str, authenticator: Authenticator, user_details: dict = dict, extra_data: dict = dict
+    uid: str, email: str, authenticator: Authenticator, user_details: dict = dict, extra_data: dict = dict
 ) -> Tuple[Optional[AbstractUser], Optional[AuthenticatorUser], Optional[bool]]:
     """
     Create the user object in the database along with it's associated AuthenticatorUser class.
@@ -200,47 +303,45 @@ def get_or_create_authenticator_user(
         logger.warning(f"AuthException: {e}")
         raise
 
+    # Step 1: Determine the username, running the migration logic FIRST. This is the key fix.
     if migrated_username := migrate_from_existing_authenticator(uid=uid, alt_uid=None, authenticator=authenticator, preferred_username=uid):
         username = migrated_username
     else:
-        username = determine_username_from_uid(uid, authenticator)
+        username = determine_username_from_uid(uid, email, authenticator)
 
+    # Step 2: Now that the username is finalized, try to find the AuthenticatorUser.
+    auth_user = None
     created = None
     try:
-        # First see if we have an auth user and if so update it
         auth_user = AuthenticatorUser.objects.get(uid=uid, provider=authenticator)
         auth_user.extra_data = extra_data
+        auth_user.email = email
         auth_user.save()
         created = False
     except AuthenticatorUser.DoesNotExist:
-        # Ensure that this username is not already tied to another authenticator
-        auth_user = AuthenticatorUser.objects.filter(user__username=username).first()
-        if auth_user is not None:
-            logger.error(
-                f'Authenticator {authenticator.name} attempted to create an AuthenticatorUser for {username}'
-                f' but that id is already tied to authenticator {auth_user.provider.name}'
-            )
+        # If the AuthenticatorUser doesn't exist, validate the username before creating a new one.
+        if not _validate_username_for_new_user(username, authenticator):
             return None, None, None
 
-    # ensure the authenticator isn't trying to pass along a cheeky is_superuser in user_details
+    # Step 3: Get or create the main User model instance.
     details = {k: user_details.get(k, "") for k in ["first_name", "last_name", "email"]}
-    # Create or get our user object
     local_user, user_created = get_user_model().objects.get_or_create(username=username, defaults=details)
     if user_created:
         logger.info(f"Authenticator {authenticator.name} created User {username}")
 
+    # Step 4: If the AuthenticatorUser was not found in Step 2, create it now.
     if created is None:
-        # Create or get the user object. The get shouldn't happen but just incase something snuck in on us
         auth_user, created = AuthenticatorUser.objects.get_or_create(
             user=local_user,
+            email=email,
             uid=uid,
             provider=authenticator,
             defaults={'extra_data': extra_data},
         )
         if created:
-            extra = ''
-            if not user_created:
-                extra = ' attaching to existing user'
+            extra = ' attaching to existing user' if not user_created else ''
             logger.debug(f"Authenticator {authenticator.name} created AuthenticatorUser for {username}{extra}")
 
-    return local_user, auth_user, created
+    # Ensure the returned user object is the one linked to the auth_user.
+    final_user = auth_user.user if auth_user else local_user
+    return final_user, auth_user, created