Add keycloak_realm_rolemapping module to map realm roles to groups (#7663)

* Add keycloak_realm_rolemapping module to map realm roles to groups

* Whitespace

* Description in plain English

* Casing

* Update error reporting as per #7645

* Add agross as maintainer of keycloak_realm_rolemapping module

* cid and client_id are not used here

* Credit other authors

* mhuysamen submitted #7645
* Gaetan2907 authored keycloak_client_rolemapping.py which I took as a
  basis

* Add integration tests

* With Keycloak 23 realmRoles are only returned if assigned

* Remove debug statement

* Add test verifying that unmap works when no realm roles are assigned

* Add license to readme

* Change version number this module was added

* Document which versions of the docker images have been tested

* Downgrade version_added

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

---------

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

tests/integration/targets/keycloak_group_rolemapping/README.md

@@ -0,0 +1,21 @@
+<!--
+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
+-->
+
+# `keycloak_group_rolemapping` Integration Tests
+
+## Test Server
+
+Prepare a development server, tested with Keycloak versions tagged 22.0 and 23.0:
+
+```sh
+docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=password --rm quay.io/keycloak/keycloak:22.0 start-dev
+```
+
+## Run Tests
+
+```sh
+ansible localhost --module-name include_role --args name=keycloak_group_rolemapping
+```

tests/integration/targets/keycloak_group_rolemapping/aliases

@@ -0,0 +1,4 @@
+# Copyright (c) 2023, Alexander Groß (@agross)
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+unsupported

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

@@ -0,0 +1,160 @@
+# Copyright (c) 2023, Alexander Groß (@agross)
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Create realm
+  community.general.keycloak_realm:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+
+    id: "{{ realm }}"
+    realm: "{{ realm }}"
+    state: present
+
+- name: Create realm roles
+  community.general.keycloak_role:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+
+    realm: "{{ realm }}"
+    name: "{{ item }}"
+    state: present
+  loop:
+    - "{{ role_1 }}"
+    - "{{ role_2 }}"
+
+- name: Create group
+  community.general.keycloak_group:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+
+    realm: "{{ realm }}"
+    name: "{{ group }}"
+    state: present
+
+- name: Map realm roles to group
+  community.general.keycloak_realm_rolemapping:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+
+    realm: "{{ realm }}"
+    group_name: "{{ group }}"
+    roles:
+      - name: "{{ role_1 }}"
+      - name: "{{ role_2 }}"
+    state: present
+  register: result
+
+- name: Assert realm roles are assigned to group
+  ansible.builtin.assert:
+    that:
+      - result is changed
+      - result.end_state | count == 2
+
+- name: Map realm roles to group again (idempotency)
+  community.general.keycloak_realm_rolemapping:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+
+    realm: "{{ realm }}"
+    group_name: "{{ group }}"
+    roles:
+      - name: "{{ role_1 }}"
+      - name: "{{ role_2 }}"
+    state: present
+  register: result
+
+- name: Assert realm roles stay assigned to group
+  ansible.builtin.assert:
+    that:
+      - result is not changed
+
+- name: Unmap realm role 1 from group
+  community.general.keycloak_realm_rolemapping:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+
+    realm: "{{ realm }}"
+    group_name: "{{ group }}"
+    roles:
+      - name: "{{ role_1 }}"
+    state: absent
+  register: result
+
+- name: Assert realm role 1 is unassigned from group
+  ansible.builtin.assert:
+    that:
+      - result is changed
+      - result.end_state | count == 1
+      - result.end_state[0] == role_2
+
+- name: Unmap realm role 1 from group again (idempotency)
+  community.general.keycloak_realm_rolemapping:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+
+    realm: "{{ realm }}"
+    group_name: "{{ group }}"
+    roles:
+      - name: "{{ role_1 }}"
+    state: absent
+  register: result
+
+- name: Assert realm role 1 stays unassigned from group
+  ansible.builtin.assert:
+    that:
+      - result is not changed
+
+- name: Unmap realm role 2 from group
+  community.general.keycloak_realm_rolemapping:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+
+    realm: "{{ realm }}"
+    group_name: "{{ group }}"
+    roles:
+      - name: "{{ role_2 }}"
+    state: absent
+  register: result
+
+- name: Assert no realm roles are assigned to group
+  ansible.builtin.assert:
+    that:
+      - result is changed
+      - result.end_state | count == 0
+
+- name: Unmap realm role 2 from group again (idempotency)
+  community.general.keycloak_realm_rolemapping:
+    auth_keycloak_url: "{{ url }}"
+    auth_realm: "{{ admin_realm }}"
+    auth_username: "{{ admin_user }}"
+    auth_password: "{{ admin_password }}"
+
+    realm: "{{ realm }}"
+    group_name: "{{ group }}"
+    roles:
+      - name: "{{ role_2 }}"
+    state: absent
+  register: result
+
+- name: Assert no realm roles are assigned to group
+  ansible.builtin.assert:
+    that:
+      - result is not changed
+      - result.end_state | count == 0

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

@@ -0,0 +1,15 @@
+---
+# Copyright (c) 2023, Alexander Groß (@agross)
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+url: http://localhost:8080
+admin_realm: master
+admin_user: admin
+admin_password: password
+realm: myrealm
+
+role_1: myrole-1
+role_2: myrole-2
+
+group: mygroup