Group based role assignment migration utility

Overview

This utility helps migrate customer's role assignments to users, to group based role assignments. This migration is limited to those role-assignments for a given role and scope whose count exceeds limit (default : 500).

How does it work

The utility runs in 3 phases : READ-ONLY, MODIFY, CLEANUP which are presented to the user for selection.

A one-shot "ALL" option is also presented which runs following phases sequentially and in the order : READ-ONLY , MODIFY , CLEANUP.

• READ-ONLY :
  • Identify Roles and scopes ( Organizational units ) where the role-assignments exceed a limit (default:500). These will be referred to as role-assignments-to-be-migrated.
• MODIFY :
  • For each scope/organizational-unit where the number of assignments exceed the limit.
    • We find the minimum set of roles to be migrated to group based role-assignments at the scope.
    • For each of the roles in this minimum set
      • Create a security-group named "<RoleId>-<OrganizationUnitName>"
      • Create a role-assignment from the role to this group at the given scope.
      • Insert the users belonging to role-assignments-to-be-migrated to this group.
• CLEANUP :
  • Cleanup the duplicate role-assignments-to-be-migrated.

Authentication mechanism

• This utility presents OAuth-Client-ID-credentials to Google OAuth end-point.
• A link to OAuth consent screen is presented to the user running utility.
  • This step requires user with super-admin credentials to login and consent.
• The utility then obtains OAuth-token for the super-admin which will be used in the course of its run.
• The token has a lifetime of 1 week during which time it will be exchanged , access-token refreshed by the utility in the background every hour.
• When the Oauth token refresh-lifetime of 1 week expires , the utility will present the user with a link to the Oauth-consent screen for Super-admin to consent and obtain a new Oauth-token.

Usage

Prerequisites

1. Enable APIs from Google Cloud Console ( How to enable APIs )

   • AdminSDK API
   • Cloud identity API
   • Google People API

2. Get OAuth-Client ID credentials

   • For the use-case of this utility , the steps are modified to those below
     • In the Google Cloud console, go to Menu menu > APIs & Services > Credentials.
     • Click Create Credentials > OAuth client ID.
     • Click Application type > Desktop application.
     • Click Create. The OAuth client created screen appears, showing your new Client ID and Client secret.
     • Click 'Download JSON' these credentials will be used by the utility and referred to below as 'Oauth-Client-ID-Credentials'

3. A user with super-admin role assigned is required to run utility.

4. pip install -r requirements.txt to install required libraries.

How to run the utility

Run the utility in dry-run/simulation mode, review the changes in the run-log before running in wet-run mode by setting the flag --wet_run.

Note that the utility has no undo mechanism.

Utility run times may be very long ( hours ), please run as background process

To use the utility, you will need to provide the following:

• --oa_client_id_creds The path to the OAuth client ID credentials.

• --output_path The path to the output directory. The run-log and OAuth tokens will be written to this directory.

• --help For explanation of flags

The following arguments are also available:

• --dry_run: Run the utility in the dry_run/read_only mode. Set --dry_run=false only after you validate the changes to be made in the run-log.
• --roles_to_force_gbra: Role ID that should be converted to Group-based-role-assignments, regardless of the number of role assignments per role scope. In order to provide a list , re-use the flag multiple times. "--roles_to_force_gbra=123 --roles_to_force_gbra=456"
• --roles_to_skip_gbra: Role ID that should NOT be converted to Group-based-role-assignments, regardless of the number of role assignments per role scope. In order to provide a list , re-use the flag multiple times. "--roles_to_skip_gbra=123 --roles_to_skip_gbra=456"
• --delete_dup_ras_to_sa: Delete duplicate role assignments to super admins. Default = False.

Sample run command

python run_me.py --oa_client_id_creds="/path/to/oa-client-id-creds.json" --output_path="/path/to/output/dir" --dry_run=True