Restore oauth_token backward compatibility for collection token auth (#16500)

* Restore oauth_token backward compatibility for collection token auth

The aap_token rename (c8981e321e) restored module-level token auth but
left two interfaces from earlier collection releases broken:

- The lookup (controller_api) and inventory (controller) plugins
  previously declared an oauth_token option. Add oauth_token as an
  alias of aap_token in the auth_plugin doc fragment and in
  AUTH_ARGSPEC so query(..., oauth_token=...) and inventory YAML keys
  keep working.

- tower_cli.cfg-style config files used an oauth_token key under
  [general]; it was silently ignored after the rename, quietly
  degrading auth. load_config() now also reads the legacy oauth_token
  key and maps it to aap_token, with the new aap_token key winning when
  both are present. aap_token remains the canonical attribute used by
  _parse_aap_token() and the Bearer header logic.

Also make the test helper compatible with ansible-core 2.21+, which
requires a serialization profile alongside _ANSIBLE_ARGS, and extend
the tests to cover the oauth_token alias and legacy config file key.

No changelog fragment added: awx_collection has no changelogs/
directory on devel.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Document oauth_token alias in module auth doc fragment

The oauth_token alias was added to aap_token in AUTH_ARGSPEC but not to
the module doc fragment, failing the validate-modules sanity check
(undocumented argument alias).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Generalize version references in compat comments

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

awx_collection/plugins/module_utils/controller_api.py

@@ -99,7 +99,7 @@ class ControllerModule(AnsibleModule):
         aap_token=dict(
             type='raw',
             no_log=True,
-            aliases=['controller_oauthtoken', 'tower_oauthtoken'],
+            aliases=['oauth_token', 'controller_oauthtoken', 'tower_oauthtoken'],
             required=False,
             fallback=(env_fallback, ['CONTROLLER_OAUTH_TOKEN', 'TOWER_OAUTH_TOKEN', 'AAP_TOKEN'])
         ),
@@ -298,7 +298,8 @@ class ControllerModule(AnsibleModule):
 
                     # If we made it here then we have values from reading the ini file, so let's pull them out into a dict
                     config_data = {}
-                    for honorred_setting in self.short_params:
+                    # 'oauth_token' is the legacy (pre-aap_token) config file key, kept for backward compatibility
+                    for honorred_setting in list(self.short_params) + ['oauth_token']:
                         try:
                             config_data[honorred_setting] = config.get('general', honorred_setting)
                         except NoOptionError:
@@ -310,6 +311,12 @@ class ControllerModule(AnsibleModule):
         except Exception as e:
             raise_from(ConfigFileException("An unknown exception occured trying to load config file: {0}".format(e)), e)
 
+        # Backward compatibility: config files written for older collection
+        # releases used the oauth_token key; map it to aap_token.
+        # If both keys are present, the new aap_token key wins.
+        if 'oauth_token' in config_data and 'aap_token' not in config_data:
+            config_data['aap_token'] = config_data['oauth_token']
+
         # If we made it here, we have a dict which has values in it from our config, any final settings logic can be performed here
         for honorred_setting in self.short_params:
             if honorred_setting in config_data: