[AAP-48822] Add default LDAP connection options to match documentation (#785)

## Description

This PR extends the work done in PR #756 by improving how LDAP
connection options are handled in the UI while maintaining the default
`OPT_REFERRALS` connection option functionality.

https://issues.redhat.com/browse/AAP-48822

**Building on PR #756:**
PR #756 added the default LDAP connection options that our documentation
says we have, specifically setting `OPT_REFERRALS` that was previously
missing. This PR continues that work by addressing the UI experience.

- What is being changed?
- Changed the default value of CONNECTION_OPTIONS field from
`default_connection_options` to an empty dict `{}`
- Updated backend logic to merge the default `OPT_REFERRALS` setting
with user-provided options when CONNECTION_OPTIONS is empty or not a
dict
- Builds upon the default `OPT_REFERRALS` connection option established
in PR #756

- Why is this change needed?
- While PR #756 correctly established the default `OPT_REFERRALS`
option, users should not be forced to see this default pre-populated in
the UI configuration form

- How does this change address the issue?
- UI now shows empty CONNECTION_OPTIONS field by default (cleaner user
experience)
- Backend properly merges the default `OPT_REFERRALS` setting with any
user-provided options
  - Maintains backward compatibility with existing configurations
- Preserves the `OPT_REFERRALS` default connection option functionality
from PR #756

## Type of Change
- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] 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
- [x] I have performed a self-review of my code
- [x] I have added relevant comments to complex code sections
- [ ] 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
### Prerequisites
- LDAP authenticator configuration environment

### Steps to Test
1. Add some debugger or logger to monitor the final value of the
`connection_options` variable
2. Run the `test_ldap_config_defaults` ATF test and put a breakpoint
before its teardown, this will setup a valid LDAP server into your AAP
3. Check the value of the `connection_options`, which must contain the
expected defaults

### Expected Results
- The `connection_options` must always have the `OPT_REFERRALS` key
- The default values must be used if the user didn't provide a different
one

## Additional Context

This PR is a continuation of the LDAP connection options work:
1. **PR #756**: Established the missing default LDAP connection options
that match our documentation
2. **This PR (#785)**: Improves the UI experience by not forcing the
`OPT_REFERRALS` default to be visible in the form while maintaining all
the backend functionality

The combination of both PRs provides the complete solution: proper
`OPT_REFERRALS` default that matches documentation + clean UI
experience.

### Required Actions
- [ ] Requires documentation updates
- [ ] Requires downstream repository changes  
- [ ] Requires infrastructure/deployment changes
- [ ] Requires coordination with other teams

---------

Co-authored-by: Pablo Hess <[email protected]>
Co-authored-by: John Westcott IV <[email protected]>

Author: 3 people

ansible_base/authentication/authenticator_plugins/ldap.py

@@ -27,6 +27,7 @@
 
 
 user_search_string = '%(user)s'
+default_connection_options = {'OPT_REFERRALS': 0}
 
 
 class PosixUIDGroupType(LDAPGroupType):
@@ -434,7 +435,14 @@ def __init__(self, prefix: str = 'AUTH_LDAP_', defaults: dict = {}):
         setattr(self, 'SERVER_URI', ','.join(defaults['SERVER_URI']))
 
         # Connection options need to be set as {"integer": "value"} but our configuration has {"friendly_name": "value"} so we need to convert them
-        connection_options = defaults.get('CONNECTION_OPTIONS', {})
+        connection_options = defaults.get('CONNECTION_OPTIONS')
+        if not isinstance(connection_options, dict):
+            logger.warning(f"Invalid CONNECTION_OPTIONS (not a dict): {connection_options}")
+            connection_options = {}
+        _tmp_connection_options = default_connection_options.copy()
+        _tmp_connection_options.update(connection_options)
+        connection_options = _tmp_connection_options
+        del _tmp_connection_options
         valid_options = dict([(v, k) for k, v in ldap.OPT_NAMES_DICT.items()])
         internal_data = {}
         for key in connection_options:

test_app/tests/authentication/authenticator_plugins/test_ldap.py

@@ -14,6 +14,7 @@
     LDAPSearchField,
     LDAPSettings,
     PosixUIDGroupType,
+    default_connection_options,
     find_class_in_modules,
     validate_ldap_filter,
 )
@@ -771,3 +772,118 @@ def test_is_member_missing_uid(group_type, ldap_user):
     ldap_user.attrs = {"gidNumber": ["1000"]}
     result = group_type.is_member(ldap_user, "cn=group,dc=example,dc=com")
     assert result is False
+
+
+def test_ldap_config_defaults():
+    from ansible_base.authentication.authenticator_plugins.ldap import LDAPConfiguration, LDAPSettings
+
+    config = LDAPConfiguration()
+    errors = []
+
+    # Verify basic field defaults
+    if config['START_TLS'].default is not False:
+        errors.append(f"START_TLS did not default to false, got {config['START_TLS'].default}")
+
+    # Verify CONNECTION_OPTIONS field default is empty (for clean UI)
+    if config['CONNECTION_OPTIONS'].default != {}:
+        errors.append(f"CONNECTION_OPTIONS field did not default to empty dict, got {config['CONNECTION_OPTIONS'].default}")
+
+    # Verify that LDAPSettings properly applies defaults when CONNECTION_OPTIONS is empty
+    test_config = {
+        'SERVER_URI': ['ldap://example.com'],
+        'CONNECTION_OPTIONS': {},  # Empty, should get merged with defaults
+        'GROUP_TYPE': 'PosixGroupType',
+        'GROUP_TYPE_PARAMS': {"name_attr": "cn"},
+    }
+    settings = LDAPSettings(defaults=test_config)
+
+    # Check that the defaults were applied in the settings object
+    import ldap
+
+    expected_referrals = ldap.OPT_REFERRALS in settings.CONNECTION_OPTIONS and settings.CONNECTION_OPTIONS[ldap.OPT_REFERRALS] == 0
+
+    if not expected_referrals:
+        errors.append("LDAPSettings did not apply OPT_REFERRALS default when CONNECTION_OPTIONS was empty")
+
+    assert errors == []
+
+
+def test_ldap_connection_options_user_override():
+    import ldap
+
+    from ansible_base.authentication.authenticator_plugins.ldap import LDAPSettings
+
+    errors = []
+
+    # Test scenario 1: User overrides default values
+    test_config_override = {
+        'SERVER_URI': ['ldap://example.com'],
+        'CONNECTION_OPTIONS': {
+            'OPT_REFERRALS': 1,  # Override default value of default_connection_options['OPT_REFERRALS']
+        },
+        'GROUP_TYPE': 'PosixGroupType',
+        'GROUP_TYPE_PARAMS': {"name_attr": "cn"},
+    }
+    settings = LDAPSettings(defaults=test_config_override)
+
+    # Verify user values override defaults
+    if settings.CONNECTION_OPTIONS[ldap.OPT_REFERRALS] != 1:
+        errors.append(f"Expected OPT_REFERRALS to be overridden to 1, got {settings.CONNECTION_OPTIONS[ldap.OPT_REFERRALS]}")
+
+    # Test scenario 2: User provides additional options not in defaults
+    test_config_additional = {
+        'SERVER_URI': ['ldap://example.com'],
+        'CONNECTION_OPTIONS': {
+            'OPT_PROTOCOL_VERSION': 3,  # New option not in defaults
+        },
+        'GROUP_TYPE': 'PosixGroupType',
+        'GROUP_TYPE_PARAMS': {"name_attr": "cn"},
+    }
+    settings = LDAPSettings(defaults=test_config_additional)
+
+    # Verify defaults are still applied
+    if settings.CONNECTION_OPTIONS[ldap.OPT_REFERRALS] != default_connection_options['OPT_REFERRALS']:
+        errors.append(
+            f"Expected OPT_REFERRALS default ({default_connection_options['OPT_REFERRALS']}) "
+            f"to be preserved, got {settings.CONNECTION_OPTIONS[ldap.OPT_REFERRALS]}"
+        )
+    # Verify additional option is included
+    if settings.CONNECTION_OPTIONS[ldap.OPT_PROTOCOL_VERSION] != 3:
+        errors.append(f"Expected OPT_PROTOCOL_VERSION to be set to 3, got {settings.CONNECTION_OPTIONS.get(ldap.OPT_PROTOCOL_VERSION)}")
+
+    # Test scenario 3: Mixed scenario - some overrides, some defaults, some new
+    test_config_mixed = {
+        'SERVER_URI': ['ldap://example.com'],
+        'CONNECTION_OPTIONS': {
+            'OPT_REFERRALS': 1,  # Override default
+            'OPT_PROTOCOL_VERSION': 3,  # New option
+        },
+        'GROUP_TYPE': 'PosixGroupType',
+        'GROUP_TYPE_PARAMS': {"name_attr": "cn"},
+    }
+    settings = LDAPSettings(defaults=test_config_mixed)
+
+    # Verify override
+    if settings.CONNECTION_OPTIONS[ldap.OPT_REFERRALS] != 1:
+        errors.append(f"Expected OPT_REFERRALS to be overridden to 1, got {settings.CONNECTION_OPTIONS[ldap.OPT_REFERRALS]}")
+    # Verify new option
+    if settings.CONNECTION_OPTIONS[ldap.OPT_PROTOCOL_VERSION] != 3:
+        errors.append(f"Expected OPT_PROTOCOL_VERSION to be set to 3, got {settings.CONNECTION_OPTIONS.get(ldap.OPT_PROTOCOL_VERSION)}")
+
+    # Test scenario 4: CONNECTION_OPTIONS is not a dict (edge case)
+    test_config_non_dict = {
+        'SERVER_URI': ['ldap://example.com'],
+        'CONNECTION_OPTIONS': "invaaalid",  # Not a dict
+        'GROUP_TYPE': 'PosixGroupType',
+        'GROUP_TYPE_PARAMS': {"name_attr": "cn"},
+    }
+    settings = LDAPSettings(defaults=test_config_non_dict)
+
+    # Should fall back to defaults only
+    if settings.CONNECTION_OPTIONS[ldap.OPT_REFERRALS] != default_connection_options['OPT_REFERRALS']:
+        errors.append(
+            f"Expected OPT_REFERRALS default ({default_connection_options['OPT_REFERRALS']}) "
+            f"when CONNECTION_OPTIONS is invalid, got {settings.CONNECTION_OPTIONS[ldap.OPT_REFERRALS]}"
+        )
+
+    assert errors == []