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

Keycloak module cleanup and consistency (#3280)

Browse source 
* Consistent Modules - Rename updated_?? to desired_?? in all the keycloak modules.

* Consistent Modules - Rename the comments, and add whitespace so that all the modules are a lot more consistent between each other.

* Consistent Modules - Remove final elif where a final else doesn't exist.

This is to address the inconsistency between the other modules.

Whilst I can see it being more descriptive, there should be a final "else:" to cater if the values is neither 'absent' or 'present'.

* Consistent Modules - Use dict() instead of {} like most of the other keycloak modules.

* Consistent Modules - Update keycloak authentication so that the if ordering is consistent for no-item.

* Consistent Modules - Move the 'Filter and map' process to always occur before getting an existing item.

* Consistent Modules - Be consistent with how to initialse before_?? and set it to dict() if it is None.

* Consistent Modules - Add module.exit_?? in the locations as per the other modules.

* Consistent Modules - Represent result['diff'] using dict(before=.., after=...) as per all the other modules.

* Consistent Modules - Add / Move location of when result['end_state'] is getting defined.

* Consistent modules - Add result['changed'] = False where we do nothing and exit because item exists.

* Consistent Modules - Set the value result['changed'] to True earlier so it shows up when in checking mode only.

* Consistent Modules - test for equality with a dict to assert there was no realm in the first place as per the other modules.

* Consistent Modules - Address the spelling.

* Consistent Modules - keycloak_group - Remove result['group'] as result['end_state'] is the consistent value used in the other modules.

* Consistent Modules - Order the lines in the section, Do nothing and exit consistently.

* Consistent Modules - Add result['end_state'] and still add deprecated `flow` return value.

* Consistent Modules - Add missing return documentation for `msg`.

* Consistent Modules - Tweak whitespace in the RETURN variable.

* Consistent Modules - Add result['group'] in addition to deprecated result['group'] response.

* Consistent Modules - Add return property, 'contains' to address test errors.

* Consistent Modules - Rename updated_?? to desired_?? in new modules since initial PR.

* Consistent Modules - Rename the comments, and add whitespace so that all the (recently added) modules are a lot more consistent between each other.

* Consistent Modules - Make indentation consistent within the response document.

* Consistent Modules - Use B(DEPRECATED) in a seperate line in the description.

* Consistent Modules - Add a lot of full stops to sentences.

* Consistent Modules - Use C(...) and I(...) formatting methods.

* Consistent Modules - Use "on success" everywhere for end_state response documentation.

* Consistent Modules - Update the documents for RETURN.proposed, RETURN.existing, RETURN.end_state to be the same.

* Consistent Modules - Add fragment.

* Remove period after short_description.

* Update changelog fragment.

* Consistent Modules - PRFeedback - Remove `module.exit_json(**result)` within the `Delete` section of the if statement.

There's a exit_json(..) immediately after.

* Consistent Modules - PRFeedback - Use `if not x_repr` instead of `if x_repr == dict()`.

* keycloak_authentication - Add a sample of the output.

* Replace `dict()` with `{}` for all the keycloak modules.

* Add the requested deprecated notices

* Update changelogs/fragments/3280-keycloak-module-cleanup-and-consistency.yml

Co-authored-by: Pierre Dumuid <pierre@knowyourdata.com.au>
Co-authored-by: Felix Fontein <felix@fontein.de>
This commit is contained in:
Pierre Dumuid 2021-10-22 16:27:18 +10:30 • committed by GitHub
commit 996dc617ed
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
11 changed files with 593 additions and 346 deletions
Download patch file Download diff file Expand all files Collapse all files

159
plugins/modules/identity/keycloak/keycloak_group.py
View file

@ -159,34 +159,91 @@ EXAMPLES = '''
'''
RETURN = '''
msg:
description: Message as to what action was taken.
returned: always
type: str
end_state:
description: Representation of the group after module execution (sample is truncated).
returned: on success
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
group:
description: Group representation of the group after module execution (sample is truncated).
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
description: GUID that identifies the group.
type: str
returned: always
sample: 23f38145-3195-462c-97e7-97041ccea73e
name:
description: Name of the group
description: Name of the group.
type: str
returned: always
sample: grp-test-123
attributes:
description: Attributes applied to this group
description: Attributes applied to this group.
type: dict
returned: always
sample:
attr1: ["val1", "val2", "val3"]
path:
description: URI path to the group
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
description: An array of the realm-level roles granted to this group.
type: list
returned: always
sample: []
@ -196,7 +253,7 @@ group:
type: list
returned: always
clientRoles:
description: A list of client-level roles granted to this group
description: A list of client-level roles granted to this group.
type: list
returned: always
sample: []
@ -208,6 +265,7 @@ group:
manage: true
manageMembership: true
view: true
'''
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
@ -222,6 +280,7 @@ def main():
:return:
"""
argument_spec = keycloak_argument_spec()
meta_args = dict(
state=dict(default='present', choices=['present', 'absent']),
realm=dict(default='master'),
@ -254,16 +313,6 @@ def main():
name = module.params.get('name')
attributes = module.params.get('attributes')
before_group = None # current state of the group, for merging.
# does the group already exist?
if gid is None:
before_group = kc.get_group_by_name(name, realm=realm)
else:
before_group = kc.get_group_by_groupid(gid, realm=realm)
before_group = {} if before_group is None else before_group
# 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.
@ -271,81 +320,103 @@ def main():
for key, val in module.params['attributes'].items():
module.params['attributes'][key] = [val] if not isinstance(val, list) else val
# 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
module.params.get(x) is not None]
# build a changeset
# See if it already exists in Keycloak
if gid is None:
before_group = kc.get_group_by_name(name, realm=realm)
else:
before_group = kc.get_group_by_groupid(gid, realm=realm)
if before_group is None:
before_group = {}
# Build a proposed changeset from parameters given to this module
changeset = {}
for param in group_params:
new_param_value = module.params.get(param)
old_value = before_group[param] if param in before_group else None
if new_param_value != old_value:
changeset[camel(param)] = new_param_value
# prepare the new group
updated_group = before_group.copy()
updated_group.update(changeset)
# Prepare the desired values using the existing values (non-existence results in a dict that is save to use as a basis)
desired_group = before_group.copy()
desired_group.update(changeset)
# if before_group is none, the group doesn't exist.
if before_group == {}:
# Cater for when it doesn't exist (an empty dict)
if not before_group:
if state == 'absent':
# nothing to do.
# Do nothing and exit
if module._diff:
result['diff'] = dict(before='', after='')
result['changed'] = False
result['end_state'] = {}
result['group'] = result['end_state']
result['msg'] = 'Group does not exist; doing nothing.'
result['group'] = dict()
module.exit_json(**result)
# for 'present', create a new group.
# Process a creation
result['changed'] = True
if name is None:
module.fail_json(msg='name must be specified when creating a new group')
if module._diff:
result['diff'] = dict(before='', after=updated_group)
result['diff'] = dict(before='', after=desired_group)
if module.check_mode:
module.exit_json(**result)
# do it for real!
kc.create_group(updated_group, realm=realm)
# create it
kc.create_group(desired_group, realm=realm)
after_group = kc.get_group_by_name(name, realm)
result['group'] = after_group
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'])
module.exit_json(**result)
else:
if state == 'present':
# Process an update
# no changes
if updated_group == before_group:
if desired_group == before_group:
result['changed'] = False
result['group'] = updated_group
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)
# update the existing group
# doing an update
result['changed'] = True
if module._diff:
result['diff'] = dict(before=before_group, after=updated_group)
result['diff'] = dict(before=before_group, after=desired_group)
if module.check_mode:
module.exit_json(**result)
# do the update
kc.update_group(updated_group, realm=realm)
kc.update_group(desired_group, realm=realm)
after_group = kc.get_group_by_groupid(updated_group['id'], realm=realm)
after_group = kc.get_group_by_groupid(desired_group['id'], realm=realm)
result['end_state'] = after_group
result['group'] = result['end_state']
result['group'] = after_group
result['msg'] = "Group {id} has been updated".format(id=after_group['id'])
module.exit_json(**result)
elif state == 'absent':
result['group'] = dict()
else:
# Process a deletion (because state was not 'present')
result['changed'] = True
if module._diff:
result['diff'] = dict(before=before_group, after='')
@ -353,14 +424,14 @@ def main():
if module.check_mode:
module.exit_json(**result)
# delete for real
# delete it
gid = before_group['id']
kc.delete_group(groupid=gid, realm=realm)
result['changed'] = True
result['msg'] = "Group {name} has been deleted".format(name=before_group['name'])
result['end_state'] = {}
result['group'] = result['end_state']
module.exit_json(**result)
result['msg'] = "Group {name} has been deleted".format(name=before_group['name'])
module.exit_json(**result)