Keycloak modules retry request on authentication error, support refresh token parameter

changelogs/fragments/9494-keycloak-modules-retry-request-on-authentication-error.yaml

@@ -0,0 +1,2 @@
+major_changes:
+  - keycloak_* modules - ``refresh_token`` parameter added. When multiple authentication parameters are provided (``token``, ``refresh_token``, and ``auth_username``/``auth_password``), modules will now automatically retry requests upon authentication errors (401), using in order the token, refresh token, and username/password (https://github.com/ansible-collections/community.general/pull/9494).

plugins/doc_fragments/keycloak.py

@@ -57,6 +57,12 @@ class ModuleDocFragment(object):
     type: str
     version_added: 3.0.0
 
+  refresh_token:
+    description:
+      - Authentication refresh token for Keycloak API.
+    type: str
+    version_added: 10.3.0
+
   validate_certs:
     description:
       - Verify TLS certificates (do not disable this in production).

plugins/modules/keycloak_authentication.py

@@ -359,7 +359,8 @@ def main():
     module = AnsibleModule(argument_spec=argument_spec,
                            supports_check_mode=True,
                            required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']])
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
                            )
 
     result = dict(changed=False, msg='', flow={})

plugins/modules/keycloak_authentication_required_actions.py

@@ -238,7 +238,8 @@ def main():
         argument_spec=argument_spec,
         supports_check_mode=True,
         required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
-        required_together=([['auth_realm', 'auth_username', 'auth_password']])
+        required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+        required_by={'refresh_token': 'auth_realm'},
     )
 
     result = dict(changed=False, msg='', end_state={}, diff=dict(before={}, after={}))

plugins/modules/keycloak_authz_authorization_scope.py

@@ -153,7 +153,9 @@ def main():
                            supports_check_mode=True,
                            required_one_of=(
                                [['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     result = dict(changed=False, msg='', end_state={}, diff=dict(before={}, after={}))
 

plugins/modules/keycloak_authz_custom_policy.py

@@ -138,7 +138,9 @@ def main():
                            supports_check_mode=True,
                            required_one_of=(
                                [['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     result = dict(changed=False, msg='', end_state={})
 

plugins/modules/keycloak_authz_permission.py

@@ -252,7 +252,9 @@ def main():
                            supports_check_mode=True,
                            required_one_of=(
                                [['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     # Convenience variables
     state = module.params.get('state')

plugins/modules/keycloak_authz_permission_info.py

@@ -134,7 +134,9 @@ def main():
                            supports_check_mode=True,
                            required_one_of=(
                                [['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     # Convenience variables
     name = module.params.get('name')

plugins/modules/keycloak_client.py

@@ -903,7 +903,9 @@ def main():
                            supports_check_mode=True,
                            required_one_of=([['client_id', 'id'],
                                              ['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
 

plugins/modules/keycloak_client_rolemapping.py

@@ -265,7 +265,9 @@ def main():
     module = AnsibleModule(argument_spec=argument_spec,
                            supports_check_mode=True,
                            required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
 

plugins/modules/keycloak_clientscope.py

@@ -353,7 +353,9 @@ def main():
                            supports_check_mode=True,
                            required_one_of=([['id', 'name'],
                                              ['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
 

plugins/modules/keycloak_clientscope_type.py

@@ -148,11 +148,13 @@ def keycloak_clientscope_type_module():
             ['default_clientscopes', 'optional_clientscopes']
         ]),
         required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+        required_by={'refresh_token': 'auth_realm'},
         mutually_exclusive=[
             ['token', 'auth_realm'],
             ['token', 'auth_username'],
             ['token', 'auth_password']
-        ])
+        ],
+    )
 
     return module
 

plugins/modules/keycloak_clienttemplate.py

@@ -293,7 +293,9 @@ def main():
                            supports_check_mode=True,
                            required_one_of=([['id', 'name'],
                                              ['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
 

plugins/modules/keycloak_component.py

@@ -155,7 +155,9 @@ def main():
     module = AnsibleModule(argument_spec=argument_spec,
                            supports_check_mode=True,
                            required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     result = dict(changed=False, msg='', end_state={}, diff=dict(before={}, after={}))
 

plugins/modules/keycloak_group.py

@@ -330,7 +330,9 @@ def main():
                            supports_check_mode=True,
                            required_one_of=([['id', 'name'],
                                              ['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     result = dict(changed=False, msg='', diff={}, group='')
 

plugins/modules/keycloak_identity_provider.py

@@ -496,7 +496,9 @@ def main():
     module = AnsibleModule(argument_spec=argument_spec,
                            supports_check_mode=True,
                            required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
 

plugins/modules/keycloak_realm.py

@@ -705,7 +705,9 @@ def main():
                            supports_check_mode=True,
                            required_one_of=([['id', 'realm', 'enabled'],
                                              ['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
 

plugins/modules/keycloak_realm_key.py

@@ -257,7 +257,9 @@ def main():
     module = AnsibleModule(argument_spec=argument_spec,
                            supports_check_mode=True,
                            required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     # Initialize the result object. Only "changed" seems to have special
     # meaning for Ansible.

plugins/modules/keycloak_realm_keys_metadata_info.py

@@ -105,7 +105,8 @@ def main():
         argument_spec=argument_spec,
         supports_check_mode=True,
         required_one_of=([["token", "auth_realm", "auth_username", "auth_password"]]),
-        required_together=([["auth_realm", "auth_username", "auth_password"]]),
+        required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+        required_by={'refresh_token': 'auth_realm'},
     )
 
     result = dict(changed=False, msg="", keys_metadata="")

plugins/modules/keycloak_realm_rolemapping.py

@@ -250,7 +250,9 @@ def main():
     module = AnsibleModule(argument_spec=argument_spec,
                            supports_check_mode=True,
                            required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
 

plugins/modules/keycloak_role.py

@@ -246,7 +246,9 @@ def main():
     module = AnsibleModule(argument_spec=argument_spec,
                            supports_check_mode=True,
                            required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
 

plugins/modules/keycloak_user.py

@@ -408,7 +408,9 @@ def main():
     module = AnsibleModule(argument_spec=argument_spec,
                            supports_check_mode=True,
                            required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
 

plugins/modules/keycloak_user_federation.py

@@ -828,7 +828,9 @@ def main():
                            supports_check_mode=True,
                            required_one_of=([['id', 'name'],
                                              ['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
 

plugins/modules/keycloak_user_rolemapping.py

@@ -238,7 +238,9 @@ def main():
                            supports_check_mode=True,
                            required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password'],
                                              ['uid', 'target_username', 'service_account_user_client_id']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
 

plugins/modules/keycloak_userprofile.py

@@ -533,7 +533,9 @@ def main():
     module = AnsibleModule(argument_spec=argument_spec,
                            supports_check_mode=True,
                            required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
-                           required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+                           required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+                           required_by={'refresh_token': 'auth_realm'},
+                           )
 
     # Initialize the result object. Only "changed" seems to have special
     # meaning for Ansible.

tests/integration/targets/keycloak_modules_authentication/README.md

@@ -0,0 +1,26 @@
+<!--
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+# Running keycloak module authentication integration test
+
+To run the Keycloak module authentication integration test, start a keycloak server using Docker or Podman:
+
+```sh
+    podman|docker run -d --rm --name mykeycloak -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=password quay.io/keycloak/keycloak:latest start-dev --http-relative-path /auth
+```
+
+Source Ansible env-setup from ansible github repository.
+
+Run the integration tests:
+
+```sh
+    ansible-test integration keycloak_role --python 3.10 --allow-unsupported
+```
+
+To cleanup, run:
+
+```sh
+    podman|docker stop mykeycloak
+```

tests/integration/targets/keycloak_modules_authentication/aliases

@@ -0,0 +1,5 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+unsupported