AAP-49757: Add setting ANSIBLE_BASE_AUTHENTICATION_LOCAL_FALLBACK_AUTHENTICATORS (ansible#878)

- Added comprehensive tests for the new
`ANSIBLE_BASE_AUTHENTICATION_LOCAL_FALLBACK_AUTHENTICATORS` setting
- Added detailed documentation explaining how to configure and implement
fallback authenticators

Author: BrennanPaciorek

ansible_base/authentication/management/commands/authenticators.py

@@ -5,6 +5,7 @@
 except ImportError:
     HAS_TABULATE = False
 
+from django.conf import settings
 from django.contrib.auth import get_user_model
 from django.core.management.base import BaseCommand, CommandError
 from django.utils.translation import gettext_lazy as _
@@ -82,11 +83,14 @@ def initialize_authenticators(self):
             creator = None
             self.stderr.write("Neither system user nor admin user were defined, local authenticator will be created without created_by set")
 
+        fallback_authenticators = getattr(settings, "ANSIBLE_BASE_AUTHENTICATION_LOCAL_FALLBACK_AUTHENTICATORS", [])
+        configuration = {"fallback_authentication": fallback_authenticators} if fallback_authenticators else {}
+
         Authenticator.objects.create(
             name='Local Database Authenticator',
             enabled=True,
             create_objects=True,
-            configuration={},
+            configuration=configuration,
             created_by=creator,
             modified_by=creator,
             remove_users=False,

docs/apps/authentication/authentication.md

@@ -59,6 +59,72 @@ ANSIBLE_BASE_AUTHENTICATOR_CLASS_PREFIXES = ["ansible_base.authentication.authen
 
 If you are going to create a different class to hold the plugins you can change or add to this as needed.
 
+#### ANSIBLE_BASE_AUTHENTICATION_LOCAL_FALLBACK_AUTHENTICATORS
+This setting allows you to configure fallback authenticators for the local database authenticator plugin. When the `authenticators --initialize` management command creates the default local authenticator, it will include these fallback authenticators in the configuration.
+
+```
+ANSIBLE_BASE_AUTHENTICATION_LOCAL_FALLBACK_AUTHENTICATORS = [
+    "my_service.authentication.fallbacks.my_fallback_service",
+    "another_app.auth.fallback_handler"
+]
+```
+
+The setting expects a list of Python module paths. Each path should point to a module containing a `FallbackAuthenticator` class. When set, these authenticators will be configured as fallback options in the local authenticator's configuration under the `fallback_authentication` key. If the setting is not provided or is empty, no fallback configuration will be added.
+
+This is useful when you want the local authenticator to fall back to other authentication methods when local authentication fails. The fallback authenticators are tried in the order specified.
+
+##### Creating a FallbackAuthenticator Class
+
+Each fallback authenticator module must contain a class named `FallbackAuthenticator` with an `authenticate` method that takes the same arguments as an authenticator plugin:
+
+```python
+class FallbackAuthenticator:
+    def authenticate(self, request, username=None, password=None, **kwargs):
+        """
+        Authenticate a user using fallback authentication logic.
+        
+        Args:
+            request: The HTTP request object
+            username: The username to authenticate
+            password: The password to authenticate  
+            **kwargs: Additional authentication parameters
+            
+        Returns:
+            User object if authentication successful, None otherwise
+        """
+        # Your custom authentication logic here
+        # Return a User object on success, None on failure
+        pass
+```
+
+Example implementation:
+
+```python
+# my_service/authentication/fallbacks/my_fallback_service.py
+import logging
+from django.contrib.auth import get_user_model
+
+logger = logging.getLogger(__name__)
+User = get_user_model()
+
+class FallbackAuthenticator:
+    def authenticate(self, request, username=None, password=None, **kwargs):
+        # Example: authenticate against an external service
+        if self._validate_with_external_service(username, password):
+            try:
+                user = User.objects.get(username=username)
+                logger.info(f"Fallback authentication successful for {username}")
+                return user
+            except User.DoesNotExist:
+                logger.warning(f"User {username} authenticated but not found in database")
+                return None
+        return None
+    
+    def _validate_with_external_service(self, username, password):
+        # Your external authentication logic
+        return False
+```
+
 #### REST_FRAMEWORK
 If you are using DRF and enable django-ansible-base authentication we prepend our authentication class to your REST_FRAMEWORK settings if our class is not already present:
 ```

test_app/tests/authentication/management/test_authenticators.py

@@ -200,3 +200,59 @@ def test_authenticators_cli_enable_disable_nonexisting(flag):
         call_command('authenticators', flag, 1337, stdout=out, stderr=err)
 
     assert "Authenticator 1337 does not exist" in str(e.value)
+
+
+@pytest.mark.parametrize(
+    "fallback_setting,expected_config",
+    [
+        (["test_fallback_auth"], {"fallback_authentication": ["test_fallback_auth"]}),
+        (["auth1", "auth2"], {"fallback_authentication": ["auth1", "auth2"]}),
+        ([], {}),
+        (None, {}),
+    ],
+)
+def test_authenticators_cli_initialize_with_fallback_setting(django_user_model, fallback_setting, expected_config):
+    """
+    Test that the ANSIBLE_BASE_AUTHENTICATION_LOCAL_FALLBACK_AUTHENTICATORS setting
+    is properly applied when initializing the local authenticator.
+    """
+    out = StringIO()
+    err = StringIO()
+
+    # Ensure no authenticators exist initially
+    assert Authenticator.objects.count() == 0
+
+    # Create admin user for the test
+    django_user_model.objects.create(username="admin")
+
+    with override_settings(ANSIBLE_BASE_AUTHENTICATION_LOCAL_FALLBACK_AUTHENTICATORS=fallback_setting):
+        call_command('authenticators', "--initialize", stdout=out, stderr=err)
+
+        assert Authenticator.objects.count() == 1
+        authenticator = Authenticator.objects.first()
+        assert authenticator.name == "Local Database Authenticator"
+        assert authenticator.type == "ansible_base.authentication.authenticator_plugins.local"
+        assert authenticator.configuration == expected_config
+
+
+def test_authenticators_cli_initialize_fallback_setting_preserves_existing_config(django_user_model, local_authenticator):
+    """
+    Test that when a local authenticator already exists, the initialize command
+    doesn't modify its configuration even if the fallback setting is present.
+    """
+    out = StringIO()
+    err = StringIO()
+
+    # Store the original configuration
+    original_config = local_authenticator.configuration.copy()
+
+    with override_settings(ANSIBLE_BASE_AUTHENTICATION_LOCAL_FALLBACK_AUTHENTICATORS=["test_fallback"]):
+        call_command('authenticators', "--initialize", stdout=out, stderr=err)
+
+        # Should still only have one authenticator
+        assert Authenticator.objects.count() == 1
+        authenticator = Authenticator.objects.first()
+
+        # Configuration should remain unchanged
+        assert authenticator.configuration == original_config
+        assert "Local authenticator already exists, skipping" in out.getvalue()