#!/usr/bin/python # # Copyright (c) 2021 Cole Neubauer, (@coleneubauer) # # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import absolute_import, division, print_function __metaclass__ = type DOCUMENTATION = ''' module: azure_rm_adgroup version_added: "1.6.0" short_description: Manage Azure Active Directory group description: - Create, update or delete Azure Active Directory group. options: state: description: - Assert the state of the resource group. Use C(present) to create or update and C(absent) to delete. default: present choices: - absent - present type: str object_id: description: - The object id for the ad group. - Can be used to reference when updating an existing group. - Ignored when attempting to create a group. type: str display_name: description: - The display name of the ad group. - Can be used with I(mail_nickname) instead of I(object_id) to reference existing group. - Required when creating a new ad group. type: str mail_nickname: description: - The mail nickname of the ad group. - Can be used with I(display_name) instead of I(object_id) to reference existing group. - Required when creating a new ad group. type: str present_members: description: - The azure ad objects asserted to be members of the group. - This list does not need to be all inclusive. Objects that are members and not on this list remain members. type: list elements: str absent_members: description: - The azure ad objects asserted to not be members of the group. type: list elements: str present_owners: description: - The azure ad objects asserted to be owners of the group. - This list does not need to be all inclusive. Objects that are owners and not on this list remain members. type: list elements: str absent_owners: description: - The azure ad objects asserted to not be owners of the group. type: list elements: str raw_membership: description: - By default the group_members return property is flattened and partially filtered of non-User objects before return. \ This argument disables those transformations. default: false type: bool description: description: - An optional description for the group. type: str extends_documentation_fragment: - azure.azcollection.azure author: - Cole Neubauer(@coleneubauer) ''' EXAMPLES = ''' - name: Create Group azure_rm_adgroup: display_name: "Group-Name" mail_nickname: "Group-Mail-Nickname" description: 'fortest' state: 'present' - name: Delete Group using display_name and mail_nickname azure_rm_adgroup: display_name: "Group-Name" mail_nickname: "Group-Mail-Nickname" state: 'absent' - name: Delete Group using object_id azure_rm_adgroup: object_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx state: 'absent' - name: Ensure Users are Members of a Group using display_name and mail_nickname azure_rm_adgroup: display_name: "Group-Name" mail_nickname: "Group-Mail-Nickname" state: 'present' present_members: - "{{ ad_object_1_object_id }}" - "{{ ad_object_2_object_id }}" - name: Ensure Users are Members of a Group using object_id azure_rm_adgroup: object_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx state: 'present' present_members: - "{{ ad_object_1_object_id }}" - "{{ ad_object_2_object_id }}" - name: Ensure Users are Members of a Group using object_id. Specify the group_membership return should be unfiltered azure_rm_adgroup: object_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx state: 'present' present_members: - "{{ ad_object_1_object_id }}" - "{{ ad_object_2_object_id }}" raw_membership: true - name: Ensure Users are not Members of a Group using display_name and mail_nickname azure_rm_adgroup: display_name: "Group-Name" mail_nickname: "Group-Mail-Nickname" state: 'present' absent_members: - "{{ ad_object_1_object_id }}" - name: Ensure Users are not Members of a Group using object_id azure_rm_adgroup: object_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx state: 'present' absent_members: - "{{ ad_object_1_object_id }}" - name: Ensure Users are Owners of a Group using display_name and mail_nickname azure_rm_adgroup: display_name: "Group-Name" mail_nickname: "Group-Mail-Nickname" state: 'present' present_owners: - "{{ ad_object_1_object_id }}" - "{{ ad_object_2_object_id }}" - name: Ensure Users are Owners of a Group using object_id azure_rm_adgroup: object_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx state: 'present' present_owners: - "{{ ad_object_1_object_id }}" - "{{ ad_object_2_object_id }}" - name: Ensure Users are not Owners of a Group using display_name and mail_nickname azure_rm_adgroup: display_name: "Group-Name" mail_nickname: "Group-Mail-Nickname" state: 'present' absent_owners: - "{{ ad_object_1_object_id }}" - "{{ ad_object_2_object_id }}" - name: Ensure Users are not Owners of a Group using object_id azure_rm_adgroup: object_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx state: 'present' absent_owners: - "{{ ad_object_1_object_id }}" - "{{ ad_object_2_object_id }}" ''' RETURN = ''' object_id: description: - The object_id for the group. type: str returned: always sample: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx display_name: description: - The display name of the group. returned: always type: str sample: GroupName mail_nickname: description: - The mail alias for the group. returned: always type: str sample: groupname mail_enabled: description: - Whether the group is mail-enabled. Must be false. This is because only pure security groups can be created using the Graph API. returned: always type: bool sample: False security_enabled: description: - Whether the group is security-enable. returned: always type: bool sample: False mail: description: - The primary email address of the group. returned: always type: str sample: group@contoso.com group_owners: description: - The owners of the group. returned: always type: list group_members: description: - The members of the group. If raw_membership is false, this contains the transitive members property. Otherwise, it contains the members property. returned: always type: list description: description: - An optional description for the group. type: str returned: always sample: 'fortest' ''' from ansible_collections.azure.azcollection.plugins.module_utils.azure_rm_common_ext import AzureRMModuleBase try: import asyncio from msgraph.generated.groups.groups_request_builder import GroupsRequestBuilder from msgraph.generated.models.group import Group from msgraph.generated.groups.item.transitive_members.transitive_members_request_builder import \ TransitiveMembersRequestBuilder from msgraph.generated.groups.item.group_item_request_builder import GroupItemRequestBuilder from msgraph.generated.models.reference_create import ReferenceCreate except ImportError: # This is handled in azure_rm_common pass class AzureRMADGroup(AzureRMModuleBase): def __init__(self): self.module_arg_spec = dict( object_id=dict(type='str'), display_name=dict(type='str'), mail_nickname=dict(type='str'), present_members=dict(type='list', elements='str'), present_owners=dict(type='list', elements='str'), absent_members=dict(type='list', elements='str'), absent_owners=dict(type='list', elements='str'), raw_membership=dict(type='bool', default=False), description=dict(type='str'), state=dict( type='str', default='present', choices=['present', 'absent'] ), ) self.display_name = None self.mail_nickname = None self.object_id = None self.present_members = [] self.present_owners = [] self.absent_members = [] self.absent_owners = [] self.state = None self.results = dict(changed=False) self._client = None self.raw_membership = False super(AzureRMADGroup, self).__init__(derived_arg_spec=self.module_arg_spec, supports_check_mode=False, supports_tags=False, is_ad_resource=True) def exec_module(self, **kwargs): for key in list(self.module_arg_spec.keys()): setattr(self, key, kwargs[key]) try: self._client = self.get_msgraph_client() ad_groups = [] if self.display_name and self.mail_nickname: filter = "displayName eq '{0}' and mailNickname eq '{1}'".format(self.display_name, self.mail_nickname) ad_groups = asyncio.get_event_loop().run_until_complete(self.get_group_list(filter)) if ad_groups: self.object_id = ad_groups[0].id if self.object_id: ad_groups = [asyncio.get_event_loop().run_until_complete(self.get_group(self.object_id))] if ad_groups: if self.state == "present": self.results["changed"] = False if self.description is not None and self.description != ad_groups[0].description: self.results["changed"] = True else: self.description = ad_groups[0].description if self.display_name is not None and self.display_name != ad_groups[0].display_name: self.results["changed"] = True else: self.display_name = ad_groups[0].display_name if self.mail_nickname is not None and self.mail_nickname != ad_groups[0].mail_nickname: self.results["changed"] = True else: self.mail_nickname = ad_groups[0].mail_nickname if self.results["changed"]: group = Group( mail_enabled=False, security_enabled=True, group_types=[], display_name=self.display_name, mail_nickname=self.mail_nickname, description=self.description ) asyncio.get_event_loop().run_until_complete(self.update_group(ad_groups[0].id, group)) ad_groups = [asyncio.get_event_loop().run_until_complete(self.get_group(self.object_id))] elif self.state == "absent": asyncio.get_event_loop().run_until_complete(self.delete_group(self.object_id)) ad_groups = [] self.results["changed"] = True else: if self.state == "present": if self.display_name and self.mail_nickname: group = Group( mail_enabled=False, security_enabled=True, group_types=[], display_name=self.display_name, mail_nickname=self.mail_nickname, description=self.description ) ad_groups = [asyncio.get_event_loop().run_until_complete(self.create_group(group))] self.results["changed"] = True else: raise ValueError( 'The group does not exist. Both display_name : {0} and mail_nickname : {1} must be passed to create a new group' .format(self.display_name, self.mail_nickname)) elif self.state == "absent": self.results["changed"] = False if ad_groups and ad_groups[0] is not None: self.update_members(ad_groups[0].id) self.update_owners(ad_groups[0].id) self.results.update(self.set_results(ad_groups[0])) except Exception as e: self.fail(e) return self.results def update_members(self, group_id): current_members = [] if self.present_members or self.absent_members: ret = asyncio.get_event_loop().run_until_complete(self.get_group_members(group_id)) current_members = [object.id for object in ret] if self.present_members: present_members_by_object_id = self.dictionary_from_object_urls(self.present_members) members_to_add = list(set(present_members_by_object_id.keys()) - set(current_members)) if members_to_add: for member_object_id in members_to_add: asyncio.get_event_loop().run_until_complete( self.add_group_member(group_id, present_members_by_object_id[member_object_id])) self.results["changed"] = True if self.absent_members: members_to_remove = list(set(self.absent_members).intersection(set(current_members))) if members_to_remove: for member in members_to_remove: asyncio.get_event_loop().run_until_complete(self.delete_group_member(group_id, member)) self.results["changed"] = True def update_owners(self, group_id): current_owners = [] if self.present_owners or self.absent_owners: ret = asyncio.get_event_loop().run_until_complete(self.get_group_owners(group_id)) current_owners = [object.id for object in ret.value] if self.present_owners: present_owners_by_object_id = self.dictionary_from_object_urls(self.present_owners) owners_to_add = list(set(present_owners_by_object_id.keys()) - set(current_owners)) if owners_to_add: for owner_object_id in owners_to_add: asyncio.get_event_loop().run_until_complete( self.add_group_owner(group_id, present_owners_by_object_id[owner_object_id])) self.results["changed"] = True if self.absent_owners: owners_to_remove = list(set(self.absent_owners).intersection(set(current_owners))) if owners_to_remove: for owner in owners_to_remove: asyncio.get_event_loop().run_until_complete(self.remove_group_owner(group_id, owner)) self.results["changed"] = True def dictionary_from_object_urls(self, object_urls): objects_by_object_id = {} for urls in object_urls: object_id = urls.split("/")[-1] objects_by_object_id[object_id] = urls return objects_by_object_id def application_to_dict(self, object): return dict( app_id=object.app_id, object_id=object.object_id, display_name=object.display_name, ) def serviceprincipal_to_dict(self, object): return dict( app_id=object.app_id, object_id=object.id, app_display_name=object.display_name, app_role_assignment_required=object.app_role_assignment_required ) def group_to_dict(self, object): return dict( object_id=object.id, display_name=object.display_name, mail_nickname=object.mail_nickname, mail_enabled=object.mail_enabled, security_enabled=object.security_enabled, mail=object.mail, description=object.description ) def user_to_dict(self, object): return dict( object_id=object.id, display_name=object.display_name, user_principal_name=object.user_principal_name, mail_nickname=object.mail_nickname, mail=object.mail, account_enabled=object.account_enabled, user_type=object.user_type ) def result_to_dict(self, object): if object.odata_type == "#microsoft.graph.group": return self.group_to_dict(object) elif object.odata_type == "#microsoft.graph.user": return self.user_to_dict(object) elif object.odata_type == "#microsoft.graph.application": return self.application_to_dict(object) elif object.odata_type == "#microsoft.graph.servicePrincipal": return self.serviceprincipal_to_dict(object) else: return object.odata_type def set_results(self, object): results = self.group_to_dict(object) if results["object_id"] and (self.present_owners or self.absent_owners): ret = asyncio.get_event_loop().run_until_complete(self.get_group_owners(results["object_id"])) results["group_owners"] = [self.result_to_dict(object) for object in ret.value] if results["object_id"] and (self.present_members or self.absent_members): ret = asyncio.get_event_loop().run_until_complete(self.get_group_members(results["object_id"])) results["group_members"] = [self.result_to_dict(object) for object in ret] return results async def update_group(self, group_id, group): return await self._client.groups.by_group_id(group_id).patch(body=group) async def create_group(self, create_group): return await self._client.groups.post(body=create_group) async def delete_group(self, group_id): await self._client.groups.by_group_id(group_id).delete() async def get_group(self, group_id): return await self._client.groups.by_group_id(group_id).get() async def get_group_list(self, filter=None): if filter: request_configuration = GroupsRequestBuilder.GroupsRequestBuilderGetRequestConfiguration( query_parameters=GroupsRequestBuilder.GroupsRequestBuilderGetQueryParameters( count=True, filter=filter, ), ) groups = await self._client.groups.get(request_configuration=request_configuration) else: groups = await self._client.groups.get() if groups and groups.value: return groups.value return [] async def get_group_members(self, group_id, filters=None): if self.raw_membership: return await self.get_raw_group_members(group_id, filters) else: return await self.get_transitive_group_members(group_id, filters) async def get_transitive_group_members(self, group_id, filters=None): request_configuration = TransitiveMembersRequestBuilder.TransitiveMembersRequestBuilderGetRequestConfiguration( query_parameters=TransitiveMembersRequestBuilder.TransitiveMembersRequestBuilderGetQueryParameters( count=True, ), ) if filters: request_configuration.query_parameters.filter = filters response = await self._client.groups.by_group_id(group_id).transitive_members.get( request_configuration=request_configuration) return response.value async def get_raw_group_members(self, group_id, filters=None): request_configuration = GroupItemRequestBuilder.GroupItemRequestBuilderGetRequestConfiguration( query_parameters=GroupItemRequestBuilder.GroupItemRequestBuilderGetQueryParameters( # this ensures service principals are returned # see https://learn.microsoft.com/en-us/graph/api/group-list-members?view=graph-rest-1.0&tabs=http expand=["members"] ), ) if filters: request_configuration.query_parameters.filter = filters group = await self._client.groups.by_group_id(group_id).get(request_configuration=request_configuration) return group.members async def add_group_member(self, group_id, obj_id): request_body = ReferenceCreate( odata_id="https://graph.microsoft.com/v1.0/directoryObjects/{0}".format(obj_id), ) await self._client.groups.by_group_id(group_id).members.ref.post(body=request_body) async def delete_group_member(self, group_id, member_id): await self._client.groups.by_group_id(group_id).members.by_directory_object_id(member_id).ref.delete() async def get_group_owners(self, group_id): request_configuration = GroupsRequestBuilder.GroupsRequestBuilderGetRequestConfiguration( query_parameters=GroupsRequestBuilder.GroupsRequestBuilderGetQueryParameters( count=True, ), ) return await self._client.groups.by_group_id(group_id).owners.get(request_configuration=request_configuration) async def add_group_owner(self, group_id, obj_id): request_body = ReferenceCreate( odata_id="https://graph.microsoft.com/v1.0/users/{0}".format(obj_id), ) await self._client.groups.by_group_id(group_id).owners.ref.post(body=request_body) async def remove_group_owner(self, group_id, obj_id): await self._client.groups.by_group_id(group_id).owners.by_directory_object_id(obj_id).ref.delete() def main(): AzureRMADGroup() if __name__ == '__main__': main()