collection 교체

collection/community/general/plugins/modules/keycloak_group.py

@@ -2,7 +2,8 @@
 # -*- coding: utf-8 -*-
 
 # Copyright (c) 2019, Adam Goossens <adam.goossens@gmail.com>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# 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
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
@@ -21,7 +22,7 @@ description:
       to your needs and a user having the expected roles.
 
     - The names of module options are snake_cased versions of the camelCase ones found in the
-      Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
+      Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/20.0.2/rest-api/index.html).
 
     - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will
       be returned that way by this module. You may pass single values for attributes when calling the module,
@@ -30,13 +31,20 @@ description:
     - When updating a group, where possible provide the group ID to the module. This removes a lookup
       to the API to translate the name into the group ID.
 
+attributes:
+    check_mode:
+        support: full
+    diff_mode:
+        support: full
 
 options:
     state:
         description:
             - State of the group.
-            - On C(present), the group will be created if it does not yet exist, or updated with the parameters you provide.
-            - On C(absent), the group will be removed if it exists.
+            - On V(present), the group will be created if it does not yet exist, or updated with the parameters you provide.
+            - >-
+              On V(absent), the group will be removed if it exists. Be aware that absenting
+              a group with subgroups will automatically delete all its subgroups too.
         default: 'present'
         type: str
         choices:
@@ -68,13 +76,45 @@ options:
             - A dict of key/value pairs to set as custom attributes for the group.
             - Values may be single values (e.g. a string) or a list of strings.
 
+    parents:
+        version_added: "6.4.0"
+        type: list
+        description:
+            - List of parent groups for the group to handle sorted top to bottom.
+            - >-
+              Set this to create a group as a subgroup of another group or groups (parents) or
+              when accessing an existing subgroup by name.
+            - >-
+              Not necessary to set when accessing an existing subgroup by its C(ID) because in
+              that case the group can be directly queried without necessarily knowing its parent(s).
+        elements: dict
+        suboptions:
+          id:
+            type: str
+            description:
+              - Identify parent by ID.
+              - Needs less API calls than using O(parents[].name).
+              - A deep parent chain can be started at any point when first given parent is given as ID.
+              - Note that in principle both ID and name can be specified at the same time
+                but current implementation only always use just one of them, with ID
+                being preferred.
+          name:
+            type: str
+            description:
+              - Identify parent by name.
+              - Needs more internal API calls than using O(parents[].id) to map names to ID's under the hood.
+              - When giving a parent chain with only names it must be complete up to the top.
+              - Note that in principle both ID and name can be specified at the same time
+                but current implementation only always use just one of them, with ID
+                being preferred.
+
 notes:
-    - Presently, the I(realmRoles), I(clientRoles) and I(access) attributes returned by the Keycloak API
+    - Presently, the RV(end_state.realmRoles), RV(end_state.clientRoles), and RV(end_state.access) attributes returned by the Keycloak API
       are read-only for groups. This limitation will be removed in a later version of this module.
 
 extends_documentation_fragment:
-- community.general.keycloak
-
+    - community.general.keycloak
+    - community.general.attributes
 
 author:
     - Adam Goossens (@adamgoossens)
@@ -91,6 +131,7 @@ EXAMPLES = '''
     auth_realm: master
     auth_username: USERNAME
     auth_password: PASSWORD
+  register: result_new_kcgrp
   delegate_to: localhost
 
 - name: Create a Keycloak group, authentication with token
@@ -156,6 +197,64 @@ EXAMPLES = '''
             - list
             - items
   delegate_to: localhost
+
+- name: Create a Keycloak subgroup of a base group (using parent name)
+  community.general.keycloak_group:
+    name: my-new-kc-group-sub
+    realm: MyCustomRealm
+    state: present
+    auth_client_id: admin-cli
+    auth_keycloak_url: https://auth.example.com/auth
+    auth_realm: master
+    auth_username: USERNAME
+    auth_password: PASSWORD
+    parents:
+      - name: my-new-kc-group
+  register: result_new_kcgrp_sub
+  delegate_to: localhost
+
+- name: Create a Keycloak subgroup of a base group (using parent id)
+  community.general.keycloak_group:
+    name: my-new-kc-group-sub2
+    realm: MyCustomRealm
+    state: present
+    auth_client_id: admin-cli
+    auth_keycloak_url: https://auth.example.com/auth
+    auth_realm: master
+    auth_username: USERNAME
+    auth_password: PASSWORD
+    parents:
+      - id: "{{ result_new_kcgrp.end_state.id }}"
+  delegate_to: localhost
+
+- name: Create a Keycloak subgroup of a subgroup (using parent names)
+  community.general.keycloak_group:
+    name: my-new-kc-group-sub-sub
+    realm: MyCustomRealm
+    state: present
+    auth_client_id: admin-cli
+    auth_keycloak_url: https://auth.example.com/auth
+    auth_realm: master
+    auth_username: USERNAME
+    auth_password: PASSWORD
+    parents:
+      - name: my-new-kc-group
+      - name: my-new-kc-group-sub
+  delegate_to: localhost
+
+- name: Create a Keycloak subgroup of a subgroup (using direct parent id)
+  community.general.keycloak_group:
+    name: my-new-kc-group-sub-sub
+    realm: MyCustomRealm
+    state: present
+    auth_client_id: admin-cli
+    auth_keycloak_url: https://auth.example.com/auth
+    auth_realm: master
+    auth_username: USERNAME
+    auth_password: PASSWORD
+    parents:
+      - id: "{{ result_new_kcgrp_sub.end_state.id }}"
+  delegate_to: localhost
 '''
 
 RETURN = '''
@@ -213,59 +312,6 @@ end_state:
                 manage: true
                 manageMembership: true
                 view: true
-
-group:
-  description:
-    - Representation of the group after module execution.
-    - Deprecated return value, it will be removed in community.general 6.0.0. Please use the return value I(end_state) instead.
-  returned: always
-  type: complex
-  contains:
-    id:
-      description: GUID that identifies the group.
-      type: str
-      returned: always
-      sample: 23f38145-3195-462c-97e7-97041ccea73e
-    name:
-      description: Name of the group.
-      type: str
-      returned: always
-      sample: grp-test-123
-    attributes:
-      description: Attributes applied to this group.
-      type: dict
-      returned: always
-      sample:
-        attr1: ["val1", "val2", "val3"]
-    path:
-      description: URI path to the group.
-      type: str
-      returned: always
-      sample: /grp-test-123
-    realmRoles:
-      description: An array of the realm-level roles granted to this group.
-      type: list
-      returned: always
-      sample: []
-    subGroups:
-      description: A list of groups that are children of this group. These groups will have the same parameters as
-                   documented here.
-      type: list
-      returned: always
-    clientRoles:
-      description: A list of client-level roles granted to this group.
-      type: list
-      returned: always
-      sample: []
-    access:
-      description: A dict describing the accesses you have to this group based on the credentials used.
-      type: dict
-      returned: always
-      sample:
-        manage: true
-        manageMembership: true
-        view: true
-
 '''
 
 from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
@@ -287,6 +333,13 @@ def main():
         id=dict(type='str'),
         name=dict(type='str'),
         attributes=dict(type='dict'),
+        parents=dict(
+            type='list', elements='dict',
+            options=dict(
+                id=dict(type='str'),
+                name=dict(type='str')
+            ),
+        ),
     )
 
     argument_spec.update(meta_args)
@@ -313,6 +366,8 @@ def main():
     name = module.params.get('name')
     attributes = module.params.get('attributes')
 
+    parents = module.params.get('parents')
+
     # attributes in Keycloak have their values returned as lists
     # via the API. attributes is a dict, so we'll transparently convert
     # the values to lists.
@@ -322,12 +377,12 @@ def main():
 
     # Filter and map the parameters names that apply to the group
     group_params = [x for x in module.params
-                    if x not in list(keycloak_argument_spec().keys()) + ['state', 'realm'] and
+                    if x not in list(keycloak_argument_spec().keys()) + ['state', 'realm', 'parents'] and
                     module.params.get(x) is not None]
 
     # See if it already exists in Keycloak
     if gid is None:
-        before_group = kc.get_group_by_name(name, realm=realm)
+        before_group = kc.get_group_by_name(name, realm=realm, parents=parents)
     else:
         before_group = kc.get_group_by_groupid(gid, realm=realm)
 
@@ -355,7 +410,6 @@ def main():
                 result['diff'] = dict(before='', after='')
             result['changed'] = False
             result['end_state'] = {}
-            result['group'] = result['end_state']
             result['msg'] = 'Group does not exist; doing nothing.'
             module.exit_json(**result)
 
@@ -371,12 +425,17 @@ def main():
         if module.check_mode:
             module.exit_json(**result)
 
-        # create it
-        kc.create_group(desired_group, realm=realm)
-        after_group = kc.get_group_by_name(name, realm)
+        # create it ...
+        if parents:
+            # ... as subgroup of another parent group
+            kc.create_subgroup(parents, desired_group, realm=realm)
+        else:
+            # ... as toplvl base group
+            kc.create_group(desired_group, realm=realm)
+
+        after_group = kc.get_group_by_name(name, realm, parents=parents)
 
         result['end_state'] = after_group
-        result['group'] = result['end_state']
 
         result['msg'] = 'Group {name} has been created with ID {id}'.format(name=after_group['name'],
                                                                             id=after_group['id'])
@@ -390,7 +449,6 @@ def main():
             if desired_group == before_group:
                 result['changed'] = False
                 result['end_state'] = desired_group
-                result['group'] = result['end_state']
                 result['msg'] = "No changes required to group {name}.".format(name=before_group['name'])
                 module.exit_json(**result)
 
@@ -409,7 +467,6 @@ def main():
             after_group = kc.get_group_by_groupid(desired_group['id'], realm=realm)
 
             result['end_state'] = after_group
-            result['group'] = result['end_state']
 
             result['msg'] = "Group {id} has been updated".format(id=after_group['id'])
             module.exit_json(**result)
@@ -429,7 +486,6 @@ def main():
             kc.delete_group(groupid=gid, realm=realm)
 
             result['end_state'] = {}
-            result['group'] = result['end_state']
 
             result['msg'] = "Group {name} has been deleted".format(name=before_group['name'])