{"id":28372998,"url":"https://github.com/googleworkspace/group-based-role-assignment-migration-util","last_synced_at":"2025-06-25T12:31:20.203Z","repository":{"id":212191888,"uuid":"709530791","full_name":"googleworkspace/group-based-role-assignment-migration-util","owner":"googleworkspace","description":null,"archived":false,"fork":false,"pushed_at":"2024-05-21T01:36:34.000Z","size":61,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-29T18:57:41.782Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/googleworkspace.png","metadata":{"files":{"readme":"README.md","changelog":"change_client/change_client_interface.py","contributing":"CONTRIBUTING","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-10-24T21:42:48.000Z","updated_at":"2025-04-14T17:55:42.000Z","dependencies_parsed_at":"2024-01-17T01:21:28.647Z","dependency_job_id":"17970baf-26a3-4fae-8787-304afa8261af","html_url":"https://github.com/googleworkspace/group-based-role-assignment-migration-util","commit_stats":null,"previous_names":["googleworkspace/group-based-role-assignment-migration-util"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/googleworkspace/group-based-role-assignment-migration-util","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleworkspace%2Fgroup-based-role-assignment-migration-util","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleworkspace%2Fgroup-based-role-assignment-migration-util/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleworkspace%2Fgroup-based-role-assignment-migration-util/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleworkspace%2Fgroup-based-role-assignment-migration-util/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/googleworkspace","download_url":"https://codeload.github.com/googleworkspace/group-based-role-assignment-migration-util/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleworkspace%2Fgroup-based-role-assignment-migration-util/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261874345,"owners_count":23223099,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-29T18:38:45.609Z","updated_at":"2025-06-25T12:31:20.172Z","avatar_url":"https://github.com/googleworkspace.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Group based role assignment migration utility\n\n## Overview\n\nThis utility helps migrate customer's role assignments to users, to\n[group based role assignments](https://support.google.com/a/users/answer/10385278).\nThis migration is limited to those role-assignments for a given role and\n[scope](https://developers.google.com/admin-sdk/directory/reference/rest/v1/roleAssignments#resource:-roleassignment)\nwhose count exceeds [limit](https://support.google.com/a/answer/9807615)\n(default : 500).\n\n### How does it work\n\nThe utility runs in 3 phases : READ-ONLY, MODIFY, CLEANUP which are presented to\nthe user for selection.\n\nA one-shot \"ALL\" option is also presented which runs following phases\nsequentially and in the order : READ-ONLY , MODIFY , CLEANUP.\n\n*   READ-ONLY :\n    *   Identify Roles and scopes ( Organizational units ) where the\n        role-assignments exceed a\n        [limit](https://support.google.com/a/answer/9807615) (default:500).\n        These will be referred to as role-assignments-to-be-migrated.\n*   MODIFY :\n    *   For each scope/organizational-unit where the number of assignments\n        exceed the limit.\n        *   We find the minimum set of roles to be migrated to group based\n            role-assignments at the scope.\n        *   For each of the roles in this minimum set\n            *   Create a\n                [security-group](https://support.google.com/a/answer/10607394?hl=en)\n                named \"\\\u003cRoleId\u003e-\\\u003cOrganizationUnitName\u003e\"\n            *   Create a role-assignment from the role to this group at the\n                given scope.\n            *   Insert the users belonging to role-assignments-to-be-migrated to\n                this group.\n*   CLEANUP :\n    *   Cleanup the duplicate role-assignments-to-be-migrated.\n\n### Authentication mechanism\n\n*   This utility presents\n    [OAuth-Client-ID-credentials to Google OAuth end-point](https://developers.google.com/workspace/guides/auth-overview#process_overview).\n*   A link to OAuth consent screen is presented to the user running utility.\n    *   This step requires user with super-admin credentials to login and\n        consent.\n*   The utility then obtains OAuth-token for the super-admin which will be used\n    in the course of its run.\n*   The token has a lifetime of 1 week during which time it will be exchanged ,\n    access-token refreshed by the utility in the background every hour.\n*   When the Oauth token refresh-lifetime of 1 week expires , the utility will\n    present the user with a link to the Oauth-consent screen for Super-admin to\n    consent and obtain a new Oauth-token.\n\n## Usage\n\n### Prerequisites\n\n\u003ca id=\"pre-req-client-id\"\u003e\u003c/a\u003e\n\n1.  Enable APIs from Google Cloud Console (\n    [How to enable APIs](https://cloud.google.com/apis/docs/getting-started#enabling_apis)\n    )\n\n    *   [ AdminSDK API ](https://console.cloud.google.com/apis/api/admin.googleapis.com)\n    *   [ Cloud identity API ](https://console.cloud.google.com/apis/library/cloudidentity.googleapis.com)\n    *   [ Google People API ](https://console.cloud.google.com/apis/library/people.googleapis.com)\n\n2.  Get\n    [ OAuth-Client ID credentials ](https://developers.google.com/workspace/guides/create-credentials#oauth-client-id)\n\n    *   For the use-case of this utility , the steps are modified to those below\n        *   In the\n            [Google Cloud console](https://console.cloud.google.com/apis/credentials),\n            go to Menu menu \u003e APIs \u0026 Services \u003e Credentials.\n        *   Click Create Credentials \u003e OAuth client ID.\n        *   Click Application type \u003e Desktop application.\n        *   Click Create. The OAuth client created screen appears, showing your\n            new Client ID and Client secret.\n        *   Click 'Download JSON' these credentials will be used by the utility\n            and referred to below as 'Oauth-Client-ID-Credentials'\n\n3.  A user with [super-admin](https://support.google.com/a/answer/2405986?hl=en)\n    role assigned is required to run utility.\n\n4.  `pip install -r requirements.txt` to install required libraries.\n\n### How to run the utility\n\n**Run the utility in dry-run/simulation mode, review the changes in the run-log\nbefore running in wet-run mode by setting the flag --wet_run.**\n\n**Note that the utility has no undo mechanism.**\n\n**Utility run times may be very long ( hours ), please run as background\nprocess**\n\nTo use the utility, you will need to provide the following:\n\n*   `--oa_client_id_creds` The path to the\n    [OAuth client ID credentials](#pre-req-client-id).\n*   `--output_path` The path to the output directory. The run-log and OAuth\n    tokens will be written to this directory.\n\n*   `--help` For explanation of flags\n\nThe following arguments are also available:\n\n*   `--dry_run`: Run the utility in the dry_run/read_only mode. Set\n    --dry_run=false only **after** you validate the changes to be made in the\n    run-log.\n*   `--roles_to_force_gbra`: Role ID that should be converted to\n    Group-based-role-assignments, regardless of the number of role assignments\n    per role scope. In order to provide a list , re-use the flag multiple times.\n    \"--roles_to_force_gbra=123 --roles_to_force_gbra=456\"\n*   `--roles_to_skip_gbra`: Role ID that should NOT be converted to\n    Group-based-role-assignments, regardless of the number of role assignments\n    per role scope. In order to provide a list , re-use the flag multiple times.\n    \"--roles_to_skip_gbra=123 --roles_to_skip_gbra=456\"\n*   `--delete_dup_ras_to_sa`: Delete duplicate role assignments to super admins.\n    Default = False.\n\nSample run command\n\n`python run_me.py --oa_client_id_creds=\"/path/to/oa-client-id-creds.json\"\n--output_path=\"/path/to/output/dir\" --dry_run=True`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogleworkspace%2Fgroup-based-role-assignment-migration-util","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogleworkspace%2Fgroup-based-role-assignment-migration-util","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogleworkspace%2Fgroup-based-role-assignment-migration-util/lists"}