[AAP-53405] Expand how AzureAd searches for the USERNAME_FIELD (#838)

- Enhanced get_user_details method to search for USERNAME_FIELD across:
  * Original response data
  * ID token data (via user_data() method)
  * Standard user info from super().get_user_details()
- Added comprehensive error handling with logging when USERNAME_FIELD
not found
- Improved data merging logic with proper precedence handling
- Added deepcopy to ensure original response data immutability
- Added comprehensive parameterized unit tests covering:
  * 5 different USERNAME_FIELD configurations
  * 3 error handling scenarios with missing fields
  * 4 token processing combinations (access_token, id_token, both, none)
  * 3 data merging behavior scenarios
  * 3 data immutability test cases
- Total test coverage: 23 parameterized test scenarios

## Description
<!-- Mandatory: Provide a clear, concise description of the changes and
their purpose -->
- What is being changed?
The AzureAD will look in more places for the specified field to use for
username.
Additionally updated some of the help text.

- Why is this change needed?
Its a bit confusing for admins.

- How does this change address the issue?
It overlays a bunch of possible sources ad then checks in the results of
all of them.

## 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
- [ ] 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 -->
- [X] I have performed a self-review of my code
- [X] I have added relevant comments to complex code sections
- [X] I have updated documentation where needed
- [X] I have considered the security impact of these changes
- [X] I have considered performance implications
- [X] I have thought about error handling and edge cases
- [X] 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
1. Create an Azure AD authenticator leaving the Username field blank.
2. Log in as an AD user note your username, log out.
3. Log in as admin, delete the user your logged in as in step 2.
4. Alter the Azure AD authenticator to use a different field for the
username (like email).
5. Log out as admin.
6. Log in as the AD user your email should now be your username.

### Expected Results
<!-- Describe what should happen after following the steps -->

## 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 -->

Co-authored-by: Claude (Anthropic) <[email protected]>

Author: john-westcott-iv

ansible_base/authentication/authenticator_plugins/azuread.py

@@ -1,4 +1,5 @@
 import logging
+from copy import deepcopy
 
 from django.utils.translation import gettext_lazy as _
 from social_core.backends.azuread import AzureADOAuth2
@@ -26,15 +27,15 @@ class AzureADConfiguration(BaseAuthenticatorConfiguration):
     )
 
     KEY = CharField(
-        help_text=_("The OIDC key (Client ID) from your IDP. Will also be used as the 'audience' for JWT decoding."),
+        help_text=_("The Client ID (OIDC Key) from Azure AD. Will also be used as the 'audience' for JWT decoding."),
         allow_null=False,
-        ui_field_label=_('OIDC Key'),
+        ui_field_label=_('Client ID'),
     )
 
     SECRET = CharField(
-        help_text=_("'The OIDC secret (Client Secret) from your IDP."),
+        help_text=_("'The Client Secret (OIDC Secret) from Azure AD."),
         allow_null=True,
-        ui_field_label=_('OIDC Secret'),
+        ui_field_label=_('Secret'),
     )
 
     GROUPS_CLAIM = CharField(
@@ -46,7 +47,11 @@ class AzureADConfiguration(BaseAuthenticatorConfiguration):
     )
 
     USERNAME_FIELD = CharField(
-        help_text=_("The name of the field from the assertion to use as the username. If not set will default to name"),
+        help_text=_(
+            "The name of the field to use as the username. "
+            "This field can be in: the assertion, the id token or the standard user info. "
+            "If not available this will default to the username."
+        ),
         required=False,
         allow_null=True,
         ui_field_label=_("Field to use as username"),
@@ -74,6 +79,25 @@ def get_user_details(self, response):
         This method is an override from social-core/social_core/backends/azuread.py
         It allows us to control what the username is.
         """
+        # start with the assertion we got back
+        user_details = deepcopy(response)
+        # At this point the response has not been overlaid with the info in the id token
+        # so we need to get the info from the id token and overlay it
+        if 'access_token' in response and 'id_token' in response:
+            user_details.update(self.user_data(response['access_token'], response=response))
+        # Finally overlay the fields from what we want to return initially
         return_object = super().get_user_details(response)
-        return_object['username'] = response.get(self.setting("USERNAME_FIELD"), return_object['username'])
+        user_details.update(return_object)
+
+        if self.setting("USERNAME_FIELD"):
+            alternate_username = user_details.get(self.setting("USERNAME_FIELD"))
+            if alternate_username:
+                return_object['username'] = alternate_username
+            else:
+                valid_keys = list(user_details.keys())
+                valid_keys.sort()
+                logger.warning(
+                    f"Username field '{self.setting('USERNAME_FIELD')}' not found in AD response, using default username of {return_object['username']}."
+                )
+                logger.warning(f"Valid keys are: {valid_keys}")
         return return_object