diff --git a/.github/workflows/ansible-test.yml b/.github/workflows/ansible-test.yml new file mode 100644 index 0000000..271d1ce --- /dev/null +++ b/.github/workflows/ansible-test.yml @@ -0,0 +1,58 @@ +name: CI +on: +- pull_request + +jobs: + sanity: + runs-on: ubuntu-latest + steps: + + - name: Check out code + uses: actions/checkout@v1 + with: + path: ansible_collections/total/azuread + + - name: Set up Python 3.6 + uses: actions/setup-python@v1 + with: + python-version: 3.6 + + - name: Install ansible-base + run: pip install git+https://github.com/ansible-collection-migration/ansible-base.git --disable-pip-version-check + + - name: Run sanity tests + run: ansible-test sanity --docker -v --color --python 3.6 + + integration: + runs-on: ubuntu-latest + strategy: + matrix: + python_version: ["3.6"] + container: + image: python:${{ matrix.python_version }}-alpine + steps: + + - name: Install requirements on alpine + run: apk add bash git gcc python3-dev libc-dev libffi-dev openssl-dev + + - name: Check out code + uses: actions/checkout@v1 + with: + path: ansible_collections/total/azuread + + - name: Create credentials for the tests + run: tests/gen_creds.sh + env: + ARM_CLIENT_ID: ${{ secrets.ARM_CLIENT_ID }} + ARM_CLIENT_SECRET: ${{ secrets.ARM_CLIENT_SECRET }} + ARM_SUBSCRIPTION_ID: ${{ secrets.ARM_SUBSCRIPTION_ID }} + ARM_TENANT_ID: ${{ secrets.ARM_TENANT_ID }} + + - name: Install ansible-base + run: pip install git+https://github.com/ansible-collection-migration/ansible-base.git --disable-pip-version-check + + - name: Install Pyhton deps + run: pip install -r requirements.txt + + - name: Run integration tests on Python ${{ matrix.python_version }} + run: ansible-test integration -v --color --retry-on-error --python ${{ matrix.python_version }} --continue-on-error --diff diff --git a/.gitignore b/.gitignore index b6e4761..4059d0c 100644 --- a/.gitignore +++ b/.gitignore @@ -127,3 +127,9 @@ dmypy.json # Pyre type checker .pyre/ + + +.idea + +# ansible-test +tests/output/* diff --git a/.idea/.gitignore b/.idea/.gitignore new file mode 100644 index 0000000..e7e9d11 --- /dev/null +++ b/.idea/.gitignore @@ -0,0 +1,2 @@ +# Default ignored files +/workspace.xml diff --git a/.idea/azuread-msgraph.iml b/.idea/azuread-msgraph.iml new file mode 100644 index 0000000..100080f --- /dev/null +++ b/.idea/azuread-msgraph.iml @@ -0,0 +1,10 @@ + + + + + + + + + + \ No newline at end of file diff --git a/.idea/inspectionProfiles/profiles_settings.xml b/.idea/inspectionProfiles/profiles_settings.xml new file mode 100644 index 0000000..105ce2d --- /dev/null +++ b/.idea/inspectionProfiles/profiles_settings.xml @@ -0,0 +1,6 @@ + + + + \ No newline at end of file diff --git a/.idea/misc.xml b/.idea/misc.xml new file mode 100644 index 0000000..b4364fb --- /dev/null +++ b/.idea/misc.xml @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100644 index 0000000..fee6665 --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 0000000..94a25f7 --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/README.md b/README.md index 5000623..a928ae6 100644 --- a/README.md +++ b/README.md @@ -1 +1,107 @@ -# azuread-msgraph \ No newline at end of file +# Azure Active Directory Collection for Ansible + +![](https://github.com/octo-technology/azuread-msgraph/workflows/CI/badge.svg?branch=master) + +This repo hosts the `octo.azuread` Ansible Collection. +The collection includes a variety of Ansible content to help automate the management of Active Directory resources through the **Microsft Graph API**. + + + +## Included content + +Click on the name of a plugin or module to view that content's documentation: + + - **Connection Plugins**: + - **Filter Plugins**: + - **Inventory Source**: + - **Callback Plugins**: + - **Lookup Plugins**: + - **Modules**: + - azuread_group + + +## Installation and Usage + +### Installing the Collection from Ansible Galaxy + +Before using the AzureAD collection, you need to install it with the Ansible Galaxy CLI: + + ansible-galaxy collection install octo.azuread + +You can also include it in a `requirements.yml` file and install it via `ansible-galaxy collection install -r requirements.yml`, using the format: + +```yaml +--- +collections: + - name: octo.azuread + version: v0.1.0 +``` + +### Using modules from the Grafana Collection in your playbooks + +You can either call modules by their Fully Qualified Collection Namespace (FQCN), like `octo.azuread.azuread_group`, or you can call modules by their short name if you list the `octo.azuread` collection in the playbook's `collections`, like so: + +```yaml +--- +- hosts: localhost + gather_facts: false + connection: local + + collections: + - octo.azuread + + tasks: + - name: Create a group with a owner + azuread_group: + name: "{{ azuread_group.name }}" + description: "{{ azuread_group.description }}" + mail_nickname: "{{ azuread_group.mail_nickname }}" + owners: + - "https://graph.microsoft.com/v1.0/users/a802c037-468d-4dca-a21d-f60965f62313" + state: "present" + client_id: "{{ client_id }}" + client_secret: "{{ client_secret }}" + tenant_id: "{{ tenant_id }}" +``` + +For documentation on how to use individual modules and other content included in this collection, please see the links in the 'Included content' section earlier in this README. + +## Testing and Development + +If you want to develop new content for this collection or improve what's already here, the easiest way to work on the collection is to clone it into one of the configured [`COLLECTIONS_PATHS`](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#collections-paths), and work on it there. + +### Testing with `ansible-test` + +The `tests` directory contains configuration for running sanity and integration tests using [`ansible-test`](https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html). + +You can run the collection's test suites with the commands: + + ansible-test sanity --docker -v --color + ansible-test integration --docker -v --color + +## Publishing New Versions + +The current process for publishing new versions of the Collection is manual, and outside Ansible Galaxy. + + 1. Ensure `CHANGELOG.md` contains all the latest changes. + 2. Update `galaxy.yml` and this README's `requirements.yml` example with the new `version` for the collection. + 3. Tag the version in Git and push to GitHub. + 4. Run the following commands to build and release the new version on Galaxy: + + ``` + ansible-galaxy collection build + ``` + +Upload the archive as an artifact of the github release. + +## License + +GNU General Public License v3.0 or later + +See LICENCE to see the full text. + +## Contributing + +Any contribution is welcome and we only ask contributors to: +* Provide *at least* integration tests for any contribution. +* Create an issues for any significant contribution that would change a large portion of the code base. diff --git a/galaxy.yml b/galaxy.yml new file mode 100644 index 0000000..8cb669f --- /dev/null +++ b/galaxy.yml @@ -0,0 +1,57 @@ +### REQUIRED + +# The namespace of the collection. This can be a company/brand/organization or product namespace under which all +# content lives. May only contain alphanumeric lowercase characters and underscores. Namespaces cannot start with +# underscores or numbers and cannot contain consecutive underscores +namespace: octo + +# The name of the collection. Has the same character restrictions as 'namespace' +name: azuread + +# The version of the collection. Must be compatible with semantic versioning +version: 0.1.0 + +# The path to the Markdown (.md) readme file. This path is relative to the root of the collection +readme: README.md + +# A list of the collection's content authors. Can be just the name or in the format 'Full Name (url) +# @nicks:irc/im.site#channel' +authors: +- your name + + +### OPTIONAL but strongly recommended + +# A short summary description of the collection +description: your collection description + +# Either a single license or a list of licenses for content inside of a collection. Ansible Galaxy currently only +# accepts L(SPDX,https://spdx.org/licenses/) licenses. This key is mutually exclusive with 'license_file' +license: +- GPL-2.0-or-later + +# The path to the license file for the collection. This path is relative to the root of the collection. This key is +# mutually exclusive with 'license' +license_file: '' + +# A list of tags you want to associate with the collection for indexing/searching. A tag name has the same character +# requirements as 'namespace' and 'name' +tags: [] + +# Collections that this collection requires to be installed for it to be usable. The key of the dict is the +# collection label 'namespace.name'. The value is a version range +# L(specifiers,https://python-semanticversion.readthedocs.io/en/latest/#requirement-specification). Multiple version +# range specifiers can be set and are separated by ',' +dependencies: {} + +# The URL of the originating SCM repository +repository: http://example.com/repository + +# The URL to any online docs +documentation: http://docs.example.com + +# The URL to the homepage of the collection/project +homepage: http://example.com + +# The URL to the collection issue tracker +issues: http://example.com/issue/tracker diff --git a/plugins/README.md b/plugins/README.md new file mode 100644 index 0000000..6541cf7 --- /dev/null +++ b/plugins/README.md @@ -0,0 +1,31 @@ +# Collections Plugins Directory + +This directory can be used to ship various plugins inside an Ansible collection. Each plugin is placed in a folder that +is named after the type of plugin it is in. It can also include the `module_utils` and `modules` directory that +would contain module utils and modules respectively. + +Here is an example directory of the majority of plugins currently supported by Ansible: + +``` +└── plugins + ├── action + ├── become + ├── cache + ├── callback + ├── cliconf + ├── connection + ├── filter + ├── httpapi + ├── inventory + ├── lookup + ├── module_utils + ├── modules + ├── netconf + ├── shell + ├── strategy + ├── terminal + ├── test + └── vars +``` + +A full list of plugin types can be found at [Working With Plugins](https://docs.ansible.com/ansible/2.9/plugins/plugins.html). \ No newline at end of file diff --git a/plugins/modules/azuread_group.py b/plugins/modules/azuread_group.py new file mode 100644 index 0000000..483e555 --- /dev/null +++ b/plugins/modules/azuread_group.py @@ -0,0 +1,513 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- + +# Copyright: (c) 2020, OCTO TECHNOLOGY +# 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 + +ANSIBLE_METADATA = { + 'status': ['preview'], + 'supported_by': 'community', + 'metadata_version': '1.1' +} + +DOCUMENTATION = ''' +--- +module: azuread_group +author: + - Rémi REY (@rrey) + - Roberto Duarte (@DuarteRoberto) +version_added: "2.10" +short_description: Manage azure ad groups +description: + - Create/update/delete AzureAD Groups through the Microsoft Graph API. +options: + state: + description: + - The desired state for the group + required: true + type: str + choices: ["present", "absent"] + client_id: + description: + - the client id. + required: true + type: str + client_secret: + description: + - the client secret. + required: true + type: str + tenant_id: + description: + - id of the azure tenant. + required: true + type: str + display_name: + description: + - The display name for the group. + required: true + aliases: + - name + type: str + description: + description: + - An optional description for the group. + required: true + type: str + group_types: + description: + - Specifies the group type and its membership. + default: "Unified" + required: false + type: list + elements: str + choices: ["Unified","DynamicMembership"] + mail_enabled: + description: + - Specifies whether the group is mail-enabled. + default: true + type: bool + mail_nickname: + description: + - he mail alias for the group, unique in the organization. + required: true + type: str + security_enabled: + description: + - Specifies whether the group is a security group. + default: true + type: bool + owners: + description: + - This property represents the owners for the group at creation time. + - directoryObject + required: true + type: list + elements: str + enforce_owners: + description: + - Enforce the list of owners provided in C(owners) by removing owners + - not in the list and adding missing ones. + required: false + type: bool +extends_documentation_fragment: +- url +''' + +EXAMPLES = ''' +--- +- name: create group in aad + azuread_group: + desired_name: "{{ azuread_group.name }}" + description: "{{ azuread_group.description }}" + mail_nickname: "{{ azuread_group.mail_nickname }}" + state: "present" + client_id: "{{ client_id }}" + client_secret: "{{ client_secret }}" + tenant_id: "{{ tenant_id }}" + +- name: delete group in aad + azuread_group: + desired_name: "{{ azuread_group.name }}" + description: "{{ azuread_group.description }}" + mail_nickname: "{{ azuread_group.mail_nickname }}" + client_id: "{{ client_id }}" + client_secret: "{{ client_secret }}" + tenant_id: "{{ tenant_id }}" + state: absent +''' + +RETURN = ''' +--- +team: + description: Information about the Team + returned: On success + type: complex + contains: + context: + description: Object context + returned: always + type: str + sample: + - "https://graph.microsoft.com/v1.0/$metadata#groups/$entity" + id: + description: The unique identifier for the group. + returned: always + type: str + sample: + - "502df398-d59c-469d-944f-34a50e60db3f" + deletedDateTime: + description: + - For some Azure Active Directory objects (user, group, application), if the object is deleted, + - it is first logically deleted, and this property is updated with the date and time when the object + - was deleted. Otherwise this property is null. If the object is restored, + - this property is updated to null. + returned: always + type: str + sample: + - null + classification: + description: Describes a classification for the group (such as low, medium or high business impact). + returned: always + type: str + sample: + - null + createdDateTime: + description: + - Timestamp of when the group was created. + - The value cannot be modified and is automatically populated when the group is created. + - The Timestamp type represents date and time using ISO 8601 format and is always in UTC time. + returned: always + type: str + sample: + - "2018-12-27T22:17:07Z" + creationOptions: + description: ??? + returned: always + type: list + sample: + - [] + description: + description: An optional description for the group. + returned: always + type: str + sample: + - "Group with designated owner and members" + displayName: + description: + - The display name for the group. + - This property is required when a group is created and cannot be cleared during updates. + returned: always + type: str + sample: + - "Operations group" + groupTypes: + description: Specifies the group type and its membership. + returned: always + type: list + sample: + - ["Unified"] + mail: + description: The SMTP address for the group. + returned: always + type: str + sample: + - "operations2019@contoso.com" + mailEnabled: + description: Specifies whether the group is mail-enabled. + returned: always + type: bool + sample: + - true + mailNickname: + description: + - The mail alias for the group, unique in the organization. + - This property must be specified when a group is created. + returned: always + type: str + sample: + - "operations2019" + onPremisesLastSyncDateTime: + description: Indicates the last time at which the group was synced with the on-premises directory. + returned: always + type: str + sample: + - null + onPremisesSecurityIdentifier: + description: + - Contains the on-premises security identifier (SID) for the group that was synchronized + - from on-premises to the cloud. + returned: always + type: str + sample: + - null + onPremisesSyncEnabled: + description: + - true if this group is synced from an on-premises directory; false if this group was originally + - synced from an on-premises directory but is no longer synced; + - null if this object has never been synced from an on-premises directory (default). + returned: always + type: str + sample: + - null + preferredDataLocation: + description: The preferred data location for the group. + returned: always + type: str + sample: + - "CAN" + proxyAddresses: + description: Email addresses for the group that direct to the same group mailbox. + returned: always + type: str + sample: + - ["SMTP:operations2019@contoso.com"] + renewedDateTime: + description: + - Timestamp of when the group was last renewed. + - This cannot be modified directly and is only updated via the renew service action. + returned: always + type: str + sample: + - "2018-12-27T22:17:07Z" + resourceBehaviorOptions: + description: ??? + returned: always + type: list + sample: + - [] + resourceProvisioningOptions: + description: ??? + returned: always + type: list + sample: + - [] + securityEnabled: + description: securityEnabled + returned: always + type: bool + sample: + - false + visibility: + description: Specifies the visibility of an Office 365 group. + returned: always + type: str + sample: + - "Public" + onPremisesProvisioningErrors: + description: Errors when using Microsoft synchronization product during provisioning. + returned: always + type: list + sample: + - [] +''' + +import json +from ansible.module_utils.basic import AnsibleModule +from ansible.module_utils.urls import fetch_url, url_argument_spec +from ansible.module_utils.common.dict_transformations import snake_dict_to_camel_dict + +try: + from requests_oauthlib import OAuth2Session + from oauthlib.oauth2 import BackendApplicationClient + + HAS_DEPS = True +except ImportError: + HAS_DEPS = False + +__metaclass__ = type + + +class AzureActiveDirectoryInterface(object): + ms_graph_api_url = "https://graph.microsoft.com/v1.0" + + def __init__(self, module): + self._module = module + token = self._get_token() + self.headers = {"Content-Type": "application/json", "Authorization": "Bearer %s" % token.get("access_token")} + + def _send_request(self, url, data=None, headers=None, method="GET"): + if data is not None: + data = json.dumps(data, sort_keys=True) + if not headers: + headers = [] + + full_url = "{ms_graph_api_url}{path}".format(ms_graph_api_url=self.ms_graph_api_url, path=url) + resp, info = fetch_url(self._module, full_url, data=data, headers=headers, method=method) + status_code = info["status"] + if status_code == 404: + return None + elif status_code == 401: + self._module.fail_json(failed=True, msg="Unauthorized to perform action '%s' on '%s'" % (method, full_url)) + elif status_code == 403: + self._module.fail_json(failed=True, msg="Permission Denied") + elif 200 <= status_code < 299: + body = resp.read() + if body: + return self._module.from_json(body) + return + self._module.fail_json(failed=True, msg="Microsoft Graph API answered with HTTP %d" % status_code) + + def _get_token(self): + client_id = self._module.params.get("client_id") + client_secret = self._module.params.get("client_secret") + scope = ["https://graph.microsoft.com/.default"] + token_url = "https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token".format( + tenant_id=self._module.params.get("tenant_id")) + + client = BackendApplicationClient(client_id=client_id) + oauth = OAuth2Session(client=client) + token = oauth.fetch_token(token_url=token_url, + client_id=client_id, + client_secret=client_secret, + scope=scope) + return token + + def create_group(self, group): + url = "/groups" + owners = group.pop("owners") + group["owners@odata.bind"] = owners + self._module.warn("creating : %s" % str(group)) + response = self._send_request(url, data=group, headers=self.headers, method="POST") + return response + + def get_groups(self): + url = "/groups" + response = self._send_request(url, headers=self.headers, method="GET") + return response.get("value") + + def get_group(self, name): + groups = self.get_groups() + for group in groups: + if group.get("displayName") == name: + return group + + def update_group(self, group_id, group): + url = "/groups/{group_id}".format(group_id=group_id) + self._module.warn("update group: %s" % group) + self._send_request(url, data=group, headers=self.headers, method="PATCH") + + def delete_group(self, group_id): + url = "/groups/{group_id}".format(group_id=group_id) + response = self._send_request(url, headers=self.headers, method="DELETE") + return response + + def converge_owners(self, group_id, current, new, enforce): + changed = False + for owner in new: + if owner not in current: + changed = True + self.add_owner(group_id, owner) + if enforce: + for owner in current: + if owner not in new: + changed = True + self.remove_owner(group_id, owner) + return changed + + def get_owners(self, group_id): + url = "/groups/{group_id}/owners".format(group_id=group_id) + response = self._send_request(url, headers=self.headers, method="GET") + return response.get("value") + + def get_owners_id(self, group_id): + owners = self.get_owners(group_id) + owners_id = ["https://graph.microsoft.com/v1.0/users/" + owner.get('id') for owner in owners] + return owners_id + + def add_owner(self, group_id, owner): + url = "/groups/{group_id}/owners/$ref".format(group_id=group_id) + data = {"@odata.id": owner} + self._module.warn("add_owner: %s" % data) + response = self._send_request(url, data=data, headers=self.headers, method="POST") + return response + + def remove_owner(self, group_id, owner): + owner_id = owner.split("/")[-1] + url = "/groups/{group_id}/owners/{owner_id}/$ref".format(group_id=group_id, owner_id=owner_id) + self._module.warn("remove_owner") + response = self._send_request(url, headers=self.headers, method="DELETE") + return response + + +def setup_module_object(): + module = AnsibleModule( + argument_spec=argument_spec, + supports_check_mode=False, + ) + return module + + +def build_group_from_params(params): + GROUP_PARAMS = ["display_name", "description", "group_types", "mail_enabled", + "mail_nickname", "security_enabled", "owners"] + group = {} + for param in GROUP_PARAMS: + if not params[param]: + continue + group[param] = params[param] + return snake_dict_to_camel_dict(group) + + +argument_spec = url_argument_spec() +argument_spec.update( + state=dict(type='str', required=True, choices=["present", "absent"]), + client_id=dict(type='str', required=True), + client_secret=dict(type='str', required=True, no_log=True), + tenant_id=dict(type='str', required=True), + display_name=dict(type='str', required=True, aliases=["name"]), + description=dict(type='str', required=True), + group_types=dict(type='list', elements='str', default="Unified", choices=["Unified", "DynamicMembership"]), + mail_enabled=dict(type='bool', default=True), + mail_nickname=dict(type='str', required=True), + security_enabled=dict(type='bool', default=True), + owners=dict(type='list', elements='str', required=True), + enforce_owners=dict(type='bool', required=False, default=False), +) + + +def compare_groups(current, new): + current_keys = current.keys() + new_keys = new.keys() + current_keys_to_remove = [item for item in current_keys if item not in new_keys] + new_keys_to_remove = ["owners", "members"] + # Remove the unknown keys from remote group + for item in current_keys_to_remove: + if item in current: + current.pop(item) + # Remove the keys that are not returned by Get method from new group + for item in new_keys_to_remove: + if item in new: + new.pop(item) + if current != new: + return dict(before=current, after=new) + + +def main(): + module = setup_module_object() + + if not HAS_DEPS: + module.fail_json(msg="module requires requests and requests-oauthlib") + + state = module.params['state'] + name = module.params['display_name'] + owners = module.params['owners'] + enforce_owners = module.params['enforce_owners'] + + azuread_iface = AzureActiveDirectoryInterface(module) + group = azuread_iface.get_group(name) + + changed = False + diff = None + if state == 'present': + new_group = build_group_from_params(module.params) + if group is None: + group = azuread_iface.create_group(new_group) + changed = True + else: + diff = compare_groups(group.copy(), new_group.copy()) + module.warn(str(diff)) + if diff is not None: + azuread_iface.update_group(group.get("id"), diff["after"]) + changed = True + current_owners = azuread_iface.get_owners_id(group.get("id")) + module.warn(str(current_owners)) + module.warn(str(owners)) + if current_owners != owners: + owners_changed = azuread_iface.converge_owners(group.get("id"), current_owners, owners, enforce_owners) + if owners_changed: + changed = True + group = azuread_iface.get_group(name) + group["owners"] = azuread_iface.get_owners(group.get("id")) + module.exit_json(changed=changed, group=group, diff=diff) + elif state == 'absent': + if group is None: + module.exit_json(failed=False, changed=False, message="No group found") + azuread_iface.delete_group(group.get("id")) + module.exit_json(failed=False, changed=True, message="Group deleted") + + +if __name__ == '__main__': + main() diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..8680084 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +requests==2.23.0 +requests-oauthlib==1.3.0 diff --git a/tests/gen_creds.sh b/tests/gen_creds.sh new file mode 100755 index 0000000..5db1886 --- /dev/null +++ b/tests/gen_creds.sh @@ -0,0 +1,10 @@ +#!/bin/bash -e + +REPO_DIR=$(git rev-parse --show-toplevel) + +mkdir "$REPO_DIR/tests/integration/targets/azuread_group/vars" +cat > tests/integration/targets/azuread_group/vars/main.yml <