[PR #6256/bc228d82 backport][stable-6] Add keycloak_authz_authorization scope module (#6400)

Add keycloak_authz_authorization scope module (#6256)

* Add keycloak_authz_authorization scope module

This module allows managing Keycloak client authorization scopes. The client has
to have authorization enable for this to work.

* botmeta: make mattock maintainer of keycloak_authz_authorization_scope

* botmeta: add mattock to team_keycloak

* keycloak_authz_authorization_scope: documentation and code layout fixes

* keycloak_authz_authorization_scope: do not fail on names with whitespace

* keycloak_authz_authorization_scope: use url quote method

Co-authored-by: Felix Fontein <felix@fontein.de>

* keycloak_authz_authorization_scope: style fixes to documentation

* keycloak_authz_authorization_scope: do not claim check/diff mode support

* keycloak_authz_authorization_scope: fix documentation

* keycloak_authz_authorization_scope: support check_mode and diff_mode

* keycloak_authz_authorization_scope: use more common terminology

Most keycloak modules use before_<object_type> and desired_<object_type> to
designate current and desired states of objects. Do the same for authorization
scopes.

* keycloak_authz_authorization_scope: fixes to check_mode and docs

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit bc228d82be)

Co-authored-by: Samuli Seppänen <samuli.seppanen@gmail.com>

tests/integration/targets/keycloak_authz_authorization_scope/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

tests/integration/targets/keycloak_authz_authorization_scope/readme.adoc

@@ -0,0 +1,27 @@
+// 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
+
+To be able to run these integration tests a keycloak server must be
+reachable under a specific url with a specific admin user and password.
+The exact values expected for these parameters can be found in
+'vars/main.yml' file. A simple way to do this is to use the official
+keycloak docker images like this:
+
+----
+docker run --name mykeycloak -p 8080:8080 -e KC_HTTP_RELATIVE_PATH=<url-path> -e KEYCLOAK_ADMIN=<admin_user> -e KEYCLOAK_ADMIN_PASSWORD=<admin_password> quay.io/keycloak/keycloak:20.0.2 start-dev
+----
+
+Example with concrete values inserted:
+
+----
+docker run --name mykeycloak -p 8080:8080 -e KC_HTTP_RELATIVE_PATH=/auth -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=password quay.io/keycloak/keycloak:20.0.2 start-dev
+----
+
+This test suite can run against a fresh unconfigured server instance
+(no preconfiguration required) and cleans up after itself (undoes all
+its config changes) as long as it runs through completly. While its active
+it changes the server configuration in the following ways:
+
+  * creating, modifying and deleting some keycloak groups
+

tests/integration/targets/keycloak_authz_authorization_scope/tasks/main.yml

@@ -0,0 +1,234 @@
+---
+# 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
+- name: Remove keycloak client to avoid failures from previous failed runs
+  community.general.keycloak_client:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+    realm: "{{ realm }}"
+    client_id: "{{ client_id }}"
+    state: absent
+
+- name: Create keycloak client with authorization services enabled
+  community.general.keycloak_client:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+    realm: "{{ realm }}"
+    client_id: "{{ client_id }}"
+    state: present
+    enabled: true
+    public_client: false
+    service_accounts_enabled: true
+    authorization_services_enabled: true
+
+- name: Create an authorization scope (check mode)
+  community.general.keycloak_authz_authorization_scope:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+    state: present
+    name: "file:delete"
+    display_name: "File delete"
+    icon_uri: "http://localhost/icon.png"
+    client_id: "{{ client_id }}"
+    realm: "{{ realm }}"
+  check_mode: true
+  diff: true
+  register: result
+
+- name: Assert that authorization scope was not created in check mode
+  assert:
+    that:
+      - result is changed
+      - result.end_state == {}
+      - result.msg == 'Authorization scope would be created'
+      - result.diff.before == {}
+      - result.diff.after.name == 'file:delete'
+      - result.diff.after.displayName == 'File delete'
+      - result.diff.after.iconUri == 'http://localhost/icon.png'
+
+- name: Create authorization scope
+  community.general.keycloak_authz_authorization_scope:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+    state: present
+    name: "file:delete"
+    display_name: "File delete"
+    icon_uri: "http://localhost/icon.png"
+    client_id: "{{ client_id }}"
+    realm: "{{ realm }}"
+  register: result
+
+- name: Assert that authorization scope was created
+  assert:
+    that:
+      - result is changed
+      - result.end_state != {}
+      - result.end_state.name == "file:delete"
+      - result.end_state.iconUri == "http://localhost/icon.png"
+      - result.end_state.displayName == "File delete"
+
+- name: Create authorization scope (test for idempotency)
+  community.general.keycloak_authz_authorization_scope:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+    state: present
+    name: "file:delete"
+    display_name: "File delete"
+    icon_uri: "http://localhost/icon.png"
+    client_id: "{{ client_id }}"
+    realm: "{{ realm }}"
+  register: result
+
+- name: Assert that nothing has changed
+  assert:
+    that:
+      - result is not changed
+      - result.end_state != {}
+      - result.end_state.name == "file:delete"
+      - result.end_state.iconUri == "http://localhost/icon.png"
+      - result.end_state.displayName == "File delete"
+
+- name: Authorization scope update (check mode)
+  community.general.keycloak_authz_authorization_scope:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+    state: present
+    name: "file:delete"
+    client_id: "{{ client_id }}"
+    realm: "{{ realm }}"
+  diff: true
+  check_mode: true
+  register: result
+
+- name: Assert that authorization scope was not updated in check mode
+  assert:
+    that:
+      - result is changed
+      - result.msg == 'Authorization scope would be updated'
+      - result.diff.before.displayName == 'File delete'
+      - result.diff.before.iconUri == 'http://localhost/icon.png'
+      - result.diff.after.displayName == ''
+      - result.diff.after.iconUri == ''
+
+- name: Authorization scope update (remove optional parameters)
+  community.general.keycloak_authz_authorization_scope:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+    state: present
+    name: "file:delete"
+    client_id: "{{ client_id }}"
+    realm: "{{ realm }}"
+  register: result
+
+- name: Assert that optional parameters have been removed
+  assert:
+    that:
+      - result is changed
+      - result.end_state != {}
+      - result.end_state.name == "file:delete"
+      - result.end_state.iconUri == ""
+      - result.end_state.displayName == ""
+
+- name: Authorization scope update (test for idempotency)
+  community.general.keycloak_authz_authorization_scope:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+    state: present
+    name: "file:delete"
+    client_id: "{{ client_id }}"
+    realm: "{{ realm }}"
+  register: result
+
+- name: Assert that nothing has changed
+  assert:
+    that:
+      - result is not changed
+      - result.end_state != {}
+      - result.end_state.name == "file:delete"
+      - result.end_state.iconUri == ""
+      - result.end_state.displayName == ""
+
+- name: Authorization scope remove (check mode)
+  community.general.keycloak_authz_authorization_scope:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+    state: absent
+    name: "file:delete"
+    client_id: "{{ client_id }}"
+    realm: "{{ realm }}"
+  diff: true
+  check_mode: true
+  register: result
+
+- name: Assert that authorization scope has not been removed in check mode
+  assert:
+    that:
+      - result is changed
+      - result.msg == 'Authorization scope would be removed'
+      - result.diff.before.name == 'file:delete'
+      - result.diff.after == {}
+
+- name: Authorization scope remove
+  community.general.keycloak_authz_authorization_scope:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+    state: absent
+    name: "file:delete"
+    client_id: "{{ client_id }}"
+    realm: "{{ realm }}"
+  register: result
+
+- name: Assert that authorization scope has been removed
+  assert:
+    that:
+      - result is changed
+      - result.end_state == {}
+
+- name: Authorization scope remove (test for idempotency)
+  community.general.keycloak_authz_authorization_scope:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+    state: absent
+    name: "file:delete"
+    client_id: "{{ client_id }}"
+    realm: "{{ realm }}"
+  register: result
+
+- name: Assert that nothing has changed
+  assert:
+    that:
+      - result is not changed
+      - result.end_state == {}
+
+- name: Remove keycloak client
+  community.general.keycloak_client:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+    realm: "{{ realm }}"
+    client_id: "{{ client_id }}"
+    state: absent

tests/integration/targets/keycloak_authz_authorization_scope/vars/main.yml

@@ -0,0 +1,11 @@
+---
+# 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
+
+url: http://localhost:8080/auth
+admin_realm: master
+admin_user: admin
+admin_password: password
+realm: master
+client_id: authz