Implement List SCIM groups

README.rst

@@ -115,6 +115,7 @@ The following commands are currently available:
 - ``preset-cli auth``: store authentication credentials.
 - ``preset-cli invite-users``: invite users to Preset.
 - ``preset-cli import-users``: automatically add users to Preset.
+- ``preset-cli list-group-membership``: List SCIM groups from a team and their memberships.
 - ``preset-cli superset sql``: run SQL interactively or programmatically against an analytical database.
 - ``preset-cli superset export-assets``: export resources (databases, datasets, charts, dashboards) into a directory as YAML files.
 - ``preset-cli superset export-ownership``: export resource ownership (UUID -> email) into a YAML file.
@@ -470,3 +471,7 @@ Exporting ownership
 ~~~~~~~~~~~~~~~~~~~
 
 The ``preset-cli superset export-ownership`` command generates a YAML file with information about ownership of different resources. The file maps resource UUIDs to user email address, and in the future will be used to recreate ownership on a different instance of Superset.
+
+Listing SCIM Groups
+~~~~~~~~~~~~~~~~~~~
+The ``preset-cli list-group-membership`` command prints all SCIM groups (including membership) associated with a Preset team. Instead of printing the results on the terminal (whcih can be useful for quick troubleshooting), it's possible to use ``--save-report=yaml`` or ``--save-report=csv`` to write results to a file. The file name would be ``{TeamSlug}__user_group_membership.{FileExtension}``.

src/preset_cli/api/clients/preset.py

@@ -5,7 +5,7 @@
 import json
 import logging
 from enum import Enum
-from typing import Any, Iterator, List, Optional, Union
+from typing import Any, Dict, Iterator, List, Optional, Union
 
 from bs4 import BeautifulSoup
 from yarl import URL
@@ -242,3 +242,23 @@ def get_base_url(self, version: Optional[str] = "v1") -> URL:
         Return the base URL for API calls.
         """
         return self.baseurl / version
+
+    def get_group_membership(
+        self,
+        team_name: str,
+        page: int,
+    ) -> Dict[str, Any]:
+        """
+        Lists all user/SCIM groups associated with a team
+        """
+        url = (
+            self.get_base_url()
+            / "teams"
+            / team_name
+            / "scim/v2/Groups"
+            % {"startIndex": str(page)}
+        )
+        self.session.headers["Accept"] = "application/scim+json"
+        _logger.debug("GET %s", url)
+        response = self.session.get(url)
+        return response.json()

src/preset_cli/cli/main.py

@@ -2,8 +2,10 @@
 Main entry point for the CLI.
 """
 
+import csv
 import getpass
 import logging
+import os.path
 import sys
 import webbrowser
 from collections import defaultdict
@@ -325,6 +327,138 @@ def invite_users(ctx: click.core.Context, teams: List[str], path: str) -> None:
         client.invite_users(teams, emails)
 
 
+@click.command()
+@click.option("--teams", callback=split_comma)
+@click.option(
+    "--save-report",
+    help="Save results to a YAML or CSV file instead of priting on the terminal",
+)
+@click.pass_context
+def list_group_membership(
+    ctx: click.core.Context,
+    teams: List[str],
+    save_report: str,
+) -> None:
+    """
+    List SCIM/user groups from Preset team(s)
+    """
+    client = PresetClient(ctx.obj["MANAGER_URL"], ctx.obj["AUTH"])
+    if not teams:
+        # prompt the user to specify the team(s), in case not specified via the `--teams` option
+        teams = get_teams(client)
+
+    # in case --save-report was used, confirm if a valid option was used before sending requests
+    if save_report and save_report.casefold() not in {"yaml", "csv"}:
+        click.echo(
+            click.style(
+                "Invalid option. Please use --save-report=csv or --save-report=yaml",
+                fg="bright_red",
+            ),
+        )
+        sys.exit(1)
+
+    for team in teams:
+
+        # print the team name in case multiple teams were provided and it's not an export
+        if not save_report and len(teams) > 1:
+            click.echo(f"## Team {team} ##")
+
+        # defining default start_at and group_count to execute it at least once
+        start_at = 1
+        group_count = 100
+
+        # account for pagination
+        while start_at <= group_count:
+
+            groups = client.get_group_membership(team, start_at)
+            group_count = groups["totalResults"]
+
+            if group_count > 0:
+
+                # print groups in console
+                if not save_report:
+                    print_group_membership(groups)
+
+                # write report to a YAML file
+                elif save_report.casefold() == "yaml":
+                    export_group_membership_yaml(groups, team)
+
+                # write report to a CSV file
+                else:
+                    export_group_membership_csv(groups, team)
+
+            else:
+                click.echo(f"Team {team} has no SCIM groups\n")
+
+            # increment start_at in case a new page is needed
+            start_at += 100
+
+
+def print_group_membership(groups: Dict[str, Any]) -> None:
+    """
+    Print group membership on the terminal
+    """
+    for group in groups["Resources"]:
+        click.echo(f'\nName: {group["displayName"]} ID: {group["id"]}')
+        if group.get("members"):
+            for member in group["members"]:
+                click.echo(
+                    f'# User: {member["display"]} Username: {member["value"]}',
+                )
+        else:
+            click.echo("# Group with no users\n")
+
+
+def export_group_membership_yaml(groups: Dict[str, Any], team: str) -> None:
+    """
+    Export group membership to a YAML file
+    """
+    yaml_name = team + "_user_group_membership.yaml"
+    with open(
+        yaml_name,
+        "a+",
+        encoding="UTF8",
+    ) as yaml_creator:
+        yaml.dump(groups, yaml_creator)
+
+
+def export_group_membership_csv(groups: Dict[str, Any], team: str) -> None:
+    """
+    Export group membership to a CSV file
+    """
+    csv_name = team + "_user_group_membership.csv"
+    for group in groups["Resources"]:
+
+        # CSV report would include a group only in case it has members
+        if group.get("members"):
+
+            # Assure we just write headers once
+            file_exists = os.path.isfile(csv_name)
+
+            with open(csv_name, "a+", encoding="UTF8") as csv_writer:
+                writer = csv.DictWriter(
+                    csv_writer,
+                    delimiter=",",
+                    fieldnames=[
+                        "Group Name",
+                        "Group ID",
+                        "User",
+                        "Username",
+                    ],
+                )
+                if not file_exists:
+                    writer.writeheader()
+                for member in group["members"]:
+                    writer.writerow(
+                        {
+                            "Group Name": group["displayName"],
+                            "Group ID": group["id"],
+                            "User": member["display"],
+                            "Username": member["value"],
+                        },
+                    )
+
+
 @click.command()
 @click.option("--teams", callback=split_comma)
 @click.argument(
@@ -503,3 +637,4 @@ def sync_user_role_to_workspace(
 preset_cli.add_command(import_users)
 preset_cli.add_command(sync_roles)
 preset_cli.add_command(superset)
+preset_cli.add_command(list_group_membership)

tests/api/clients/preset_test.py

@@ -361,3 +361,107 @@ def test_change_workspace_role(requests_mock: Mocker) -> None:
         "role_identifier": "PresetAlpha",
         "user_id": 2,
     }
+
+
+def test_get_group_membership(requests_mock: Mocker) -> None:
+    """
+    Test the ``get_groups`` method.
+    """
+    requests_mock.get(
+        "https://ws.preset.io/v1/teams/testSlug/scim/v2/Groups",
+        json={
+            "Resources": [
+                {
+                    "displayName": "SCIM First Test Group",
+                    "id": "b2a691ca-0ef8-464c-9601-9c50158c5426",
+                    "members": [
+                        {
+                            "display": "Test Account 01",
+                            "value": "samlp|example|testaccount01@example.com",
+                        },
+                        {
+                            "display": "Test Account 02",
+                            "value": "samlp|example|testaccount02@example.com",
+                        },
+                    ],
+                    "meta": {
+                        "resourceType": "Group",
+                    },
+                    "schemas": [
+                        "urn:ietf:params:scim:schemas:core:2.0:Group",
+                    ],
+                },
+                {
+                    "displayName": "SCIM Second Test Group",
+                    "id": "fba067fc-506a-452b-8cf4-7d98f6960a6b",
+                    "members": [
+                        {
+                            "display": "Test Account 02",
+                            "value": "samlp|example|testaccount02@example.com",
+                        },
+                    ],
+                    "meta": {
+                        "resourceType": "Group",
+                    },
+                    "schemas": [
+                        "urn:ietf:params:scim:schemas:core:2.0:Group",
+                    ],
+                },
+            ],
+            "itemsPerPage": 100,
+            "schemas": [
+                "urn:ietf:params:scim:api:messages:2.0:ListResponse",
+            ],
+            "startIndex": 1,
+            "totalResults": 2,
+        },
+    )
+
+    auth = Auth()
+    client = PresetClient("https://ws.preset.io/", auth)
+    assert client.get_group_membership("testSlug", 1) == {
+        "Resources": [
+            {
+                "displayName": "SCIM First Test Group",
+                "id": "b2a691ca-0ef8-464c-9601-9c50158c5426",
+                "members": [
+                    {
+                        "display": "Test Account 01",
+                        "value": "samlp|example|testaccount01@example.com",
+                    },
+                    {
+                        "display": "Test Account 02",
+                        "value": "samlp|example|testaccount02@example.com",
+                    },
+                ],
+                "meta": {
+                    "resourceType": "Group",
+                },
+                "schemas": [
+                    "urn:ietf:params:scim:schemas:core:2.0:Group",
+                ],
+            },
+            {
+                "displayName": "SCIM Second Test Group",
+                "id": "fba067fc-506a-452b-8cf4-7d98f6960a6b",
+                "members": [
+                    {
+                        "display": "Test Account 02",
+                        "value": "samlp|example|testaccount02@example.com",
+                    },
+                ],
+                "meta": {
+                    "resourceType": "Group",
+                },
+                "schemas": [
+                    "urn:ietf:params:scim:schemas:core:2.0:Group",
+                ],
+            },
+        ],
+        "itemsPerPage": 100,
+        "schemas": [
+            "urn:ietf:params:scim:api:messages:2.0:ListResponse",
+        ],
+        "startIndex": 1,
+        "totalResults": 2,
+    }