[AAP-48680] Alter AzureAD to allow for flexable username creation (ansible#752)

## Description
<!-- Mandatory: Provide a clear, concise description of the changes and
their purpose -->
- What is being changed?
This adds a setting to the Azure AD authentication to allow for a
selected fields to be the UID we recieve.

- Why is this change needed?
A customer is trying to migrate users from LDAP to Azure AD but the
usernames do not match.

- How does this change address the issue?
This allows for custom usernames coming from AD so the logic which
migrates users in 2.5 should now be able to be leveraged if they alter
the username coming back from AD.

## 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 in an existing 2.5 and authenticate
as a user, note the user ID.
2. Apply this patch and restart your gateway service.
3. Log in through Azure AD again and ensure authentication works and you
are the same user as before.
4. Log out, log in as admin and delete your AD user.
5. Log in through AD again and ensure you got the same username.
6. Log out, log in as admin and delete your AD user.
7. Edit your AD authenticator and save (with no changes) (this will
inject the new setting into your authenticator).
8. Log in as your AD user, ensure you got the same username as before.
9. Log out, log in as admin and delete your AD user. Also alter your
authenticator and set the new setting (Field to use as username) to
`email`.
10. Log out and log in with your AD account. Ensure your new user id is
the email of the user instead of the old 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 -->

Author: john-westcott-iv

ansible_base/authentication/authenticator_plugins/azuread.py

@@ -45,6 +45,14 @@ class AzureADConfiguration(BaseAuthenticatorConfiguration):
         ui_field_label=_("Groups Claim"),
     )
 
+    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"),
+        required=False,
+        allow_null=True,
+        default=None,
+        ui_field_label=_("Field to use as username"),
+    )
+
 
 class AuthenticatorPlugin(SocialAuthMixin, SocialAuthValidateCallbackMixin, AzureADOAuth2, AbstractAuthenticatorPlugin):
     configuration_class = AzureADConfiguration
@@ -59,3 +67,14 @@ def groups_claim(self):
 
     def get_user_groups(self, extra_groups=[]):
         return extra_groups
+
+    def get_user_details(self, response):
+        """
+        Return user details from Azure AD account
+
+        This method is an override from social-core/social_core/backends/azuread.py
+        It allows us to control what the username is.
+        """
+        return_object = super().get_user_details(response)
+        return_object['username'] = response.get(self.setting("USERNAME_FIELD"), return_object['username'])
+        return return_object

test_app/tests/authentication/authenticator_plugins/test_azuread.py

@@ -109,3 +109,31 @@ def __init__(self):
     # assert that AD returns expected user groups
     assert ad.get_user_groups() == []
     assert ad.get_user_groups(["a", "b"]) == ["a", "b"]
+
+
+def test_get_user_details():
+
+    class MockedDb:
+        def __init__(self, username_field):
+            self.slug = "fake"
+            self.configuration = {"USERNAME_FIELD": username_field}
+
+    ad = get_authenticator_plugin("ansible_base.authentication.authenticator_plugins.azuread")
+    ad.database_instance = MockedDb(None)
+
+    username = 'bob'
+    email = '[email protected]'
+
+    response = {
+        "name": username,
+        "given_name": "Joe",
+        "family_name": "LastName",
+        "email": email,
+        "upn": "upn123",
+    }
+
+    assert ad.get_user_details(response)['username'] == username
+
+    ad.database_instance = MockedDb('email')
+
+    assert ad.get_user_details(response)['username'] == email