ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-04-27 12:51:25 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

keycloak_group: support keycloak subgroups (#5814)

Browse source 
* feat(module/keycloak_group): add support for ...

... handling subgroups

* added changelog fragment and fixing sanity ...

... test issues

* more sanity fixes

* fix missing version and review issues

* added missing licence header

* fix docu

* fix line beeing too long

* replaced suboptimal string type prefixing ...

... with better subdict based approach

* fix sanity issues

* more sanity fixing

* fixed more review issues

* fix argument list too long

* why is it failing? something wrong with the docu?

* is it this line then?

* undid group attribute removing, it does not ...

... belong into this PR

* fix version_added for parents parameter

---------

Co-authored-by: Mirko Wilhelmi <Mirko.Wilhelmi@sma.de>
This commit is contained in:
morco 2023-02-25 11:12:35 +01:00 • committed by GitHub
parent 1877ef1510
commit 7d3e6d1bb7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 796 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

138
plugins/module_utils/identity/keycloak/keycloak.py
View file

@ -42,6 +42,7 @@ URL_CLIENTTEMPLATE = "{url}/admin/realms/{realm}/client-templates/{id}"
URL_CLIENTTEMPLATES = "{url}/admin/realms/{realm}/client-templates"
URL_GROUPS = "{url}/admin/realms/{realm}/groups"
URL_GROUP = "{url}/admin/realms/{realm}/groups/{groupid}"
URL_GROUP_CHILDREN = "{url}/admin/realms/{realm}/groups/{groupid}/children"
URL_CLIENTSCOPES = "{url}/admin/realms/{realm}/client-scopes"
URL_CLIENTSCOPE = "{url}/admin/realms/{realm}/client-scopes/{id}"
@ -1249,7 +1250,7 @@ class KeycloakAPI(object):
self.module.fail_json(msg="Could not fetch group %s in realm %s: %s"
% (gid, realm, str(e)))
def get_group_by_name(self, name, realm="master"):
def get_group_by_name(self, name, realm="master", parents=None):
""" Fetch a keycloak group within a realm based on its name.
The Keycloak API does not allow filtering of the Groups resource by name.
@ -1259,10 +1260,19 @@ class KeycloakAPI(object):
If the group does not exist, None is returned.
:param name: Name of the group to fetch.
:param realm: Realm in which the group resides; default 'master'
:param parents: Optional list of parents when group to look for is a subgroup
"""
groups_url = URL_GROUPS.format(url=self.baseurl, realm=realm)
try:
all_groups = self.get_groups(realm=realm)
if parents:
parent = self.get_subgroup_direct_parent(parents, realm)
if not parent:
return None
all_groups = parent['subGroups']
else:
all_groups = self.get_groups(realm=realm)
for group in all_groups:
if group['name'] == name:
@ -1274,6 +1284,102 @@ class KeycloakAPI(object):
self.module.fail_json(msg="Could not fetch group %s in realm %s: %s"
% (name, realm, str(e)))
def _get_normed_group_parent(self, parent):
""" Converts parent dict information into a more easy to use form.
:param parent: parent describing dict
"""
if parent['id']:
return (parent['id'], True)
return (parent['name'], False)
def get_subgroup_by_chain(self, name_chain, realm="master"):
""" Access a subgroup API object by walking down a given name/id chain.
Groups can be given either as by name or by ID, the first element
must either be a toplvl group or given as ID, all parents must exist.
If the group cannot be found, None is returned.
:param name_chain: Topdown ordered list of subgroup parent (ids or names) + its own name at the end
:param realm: Realm in which the group resides; default 'master'
"""
cp = name_chain[0]
# for 1st parent in chain we must query the server
cp, is_id = self._get_normed_group_parent(cp)
if is_id:
tmp = self.get_group_by_groupid(cp, realm=realm)
else:
# given as name, assume toplvl group
tmp = self.get_group_by_name(cp, realm=realm)
if not tmp:
return None
for p in name_chain[1:]:
for sg in tmp['subGroups']:
pv, is_id = self._get_normed_group_parent(p)
if is_id:
cmpkey = "id"
else:
cmpkey = "name"
if pv == sg[cmpkey]:
tmp = sg
break
if not tmp:
return None
return tmp
def get_subgroup_direct_parent(self, parents, realm="master", children_to_resolve=None):
""" Get keycloak direct parent group API object for a given chain of parents.
To succesfully work the API for subgroups we actually dont need
to "walk the whole tree" for nested groups but only need to know
the ID for the direct predecessor of current subgroup. This
method will guarantee us this information getting there with
as minimal work as possible.
Note that given parent list can and might be incomplete at the
upper levels as long as it starts with an ID instead of a name
If the group does not exist, None is returned.
:param parents: Topdown ordered list of subgroup parents
:param realm: Realm in which the group resides; default 'master'
"""
if children_to_resolve is None:
# start recursion by reversing parents (in optimal cases
# we dont need to walk the whole tree upwarts)
parents = list(reversed(parents))
children_to_resolve = []
if not parents:
# walk complete parents list to the top, all names, no id's,
# try to resolve it assuming list is complete and 1st
# element is a toplvl group
return self.get_subgroup_by_chain(list(reversed(children_to_resolve)), realm=realm)
cp = parents[0]
unused, is_id = self._get_normed_group_parent(cp)
if is_id:
# current parent is given as ID, we can stop walking
# upwards searching for an entry point
return self.get_subgroup_by_chain([cp] + list(reversed(children_to_resolve)), realm=realm)
else:
# current parent is given as name, it must be resolved
# later, try next parent (recurse)
children_to_resolve.append(cp)
return self.get_subgroup_direct_parent(
parents[1:],
realm=realm, children_to_resolve=children_to_resolve
)
def create_group(self, grouprep, realm="master"):
""" Create a Keycloak group.
@ -1288,6 +1394,34 @@ class KeycloakAPI(object):
self.module.fail_json(msg="Could not create group %s in realm %s: %s"
% (grouprep['name'], realm, str(e)))
def create_subgroup(self, parents, grouprep, realm="master"):
""" Create a Keycloak subgroup.
:param parents: list of one or more parent groups
:param grouprep: a GroupRepresentation of the group to be created. Must contain at minimum the field name.
:return: HTTPResponse object on success
"""
parent_id = "---UNDETERMINED---"
try:
parent_id = self.get_subgroup_direct_parent(parents, realm)
if not parent_id:
raise Exception(
"Could not determine subgroup parent ID for given"
" parent chain {0}. Assure that all parents exist"
" already and the list is complete and properly"
" ordered, starts with an ID or starts at the"
" top level".format(parents)
)
parent_id = parent_id["id"]
url = URL_GROUP_CHILDREN.format(url=self.baseurl, realm=realm, groupid=parent_id)
return open_url(url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
data=json.dumps(grouprep), validate_certs=self.validate_certs)
except Exception as e:
self.module.fail_json(msg="Could not create subgroup %s for parent group %s in realm %s: %s"
% (grouprep['name'], parent_id, realm, str(e)))
def update_group(self, grouprep, realm="master"):
""" Update an existing group.

122
plugins/modules/keycloak_group.py
View file

@ -22,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,
@ -42,7 +42,9 @@ options:
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 C(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:
@ -74,6 +76,38 @@ 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 I(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 I(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
are read-only for groups. This limitation will be removed in a later version of this module.
@ -97,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
@ -162,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 = '''
@ -240,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)
@ -266,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.
@ -275,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)
@ -323,9 +425,15 @@ 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