Creating and managing user groups
Introduction to Verily Workbench groups
Workbench allows you to define and manage groups of registered users, called Workbench Groups. Workbench Groups are useful for many reasons.
First, you can use them to define and manage sets of users that have different semantics for your purposes (e.g. “users who are workspace
READERS” vs workspace
WRITERS, or “users from Company A” vs “users from Company B”). You can share a workspace and its resources with a given group (e.g., “Customers from Company A”), and if a particular user should no longer have access, you can simply remove them from the group.
In addition, Workbench Groups can be used to give access to resources in “external” (non-Workbench) Google Cloud projects, e.g. to configure a GCS bucket to be readable by a group of users.
Every Workbench user has their own “pet service account” (per workspace). A service account (SA) is a special type of Google account that lets Workbench interface directly with Google Cloud on your behalf. For example, the Workbench Cloud Environments are configured to “act as” your pet SA.
Adding a member to a Workbench Group implicitly adds their “pet service account” to the group as well. So, by sharing a resource with a Workbench group, you’re sharing that resource with the users’ service accounts as well, and this will allow them to, e.g., access that resource from their Cloud Environments and other workspace contexts. When a group is granted access to a resource, the group members are able to access that resource from any of their Workbench workspaces.
Each Workbench user has an associated automatically-created proxy group that holds only that user and their pet service account(s). The proxy group can be used to set up access permissions as well. See the next section for more detail.
Creating and managing groups
Workbench groups are defined and managed via the
terra command-line tool. If you don’t want to install the
terra tool locally, you can create a Cloud Environment in a Workbench workspace, which will have
terra already installed and configured for you. One easy way to access the command-line tool from a Cloud Environment is to launch a Terminal window from the JupyterLab server.
Note: If you’d prefer not to use the command-line tool directly, this notebook provided in the First Hour on Verily Workbench series can be run in a cloud environment to produce tooling which enables you to create and manage groups without using the terminal.
You can only add email addresses of registered Workbench users to a group. However, groups may be nested— you can add a group as a member as another group.
terra group subcommands are as follows:
Usage: terra group [COMMAND] Manage groups of users. Commands: add-user Add a user to a group with a given policy. create Create a new Workspace group. delete Delete an existing Workspace group. describe Describe the group. list List the groups to which the current user belongs. list-users List the users in a group. remove-user Remove a user from a group with a given policy.
To see the Workbench Groups that you currently belong to, run:
$ terra group list
(Your proxy group is not included in this list). The output will look similar to this:
$ terra group list NAME EMAIL MEMBERS POLICIES amy-test-workspace-group email@example.com 1 [ADMIN] companyA-users companyA@verily-bvdp.com 6 [ADMIN] my-team firstname.lastname@example.org unknown [MEMBER]
terra group <subcommand> to see usage details for a subcommand. For example:
$ terra group create Missing required option: '--name=<name>' Usage: terra group create [--format=<format>] --name=<name> Create a new Terra group. --format=<format> Set the format for printing command output: JSON, TEXT. Defaults to the config format property. Default: null --name=<name> Group name.
If you are a group
ADMIN, you will be able to list the users in a group. The creator of a group is automatically an
$ terra group list-users --name=amyu-test-workspace-group
Adding a user to a group
To add a user to a group you administer, use
terra group add-user:
Usage: terra group add-user --email=<email> [--format=<format>] --name=<name> --policy=<policy> Add a user to a group with a given policy. --email=<email> User (or other group) email. --format=<format> Set the format for printing command output: JSON, TEXT. Defaults to the config format property. Default: null --name=<name> Group name. --policy=<policy> Group policy: MEMBER, ADMIN.
--policy argument determines whether the user is added as a
Finding your proxy group
You can see the address of your own proxy group— along with your “pet service account” for the current workspace— by running the command:
terra auth status
You can also see the proxy group listed in your ‘profile’ information:
Using Workbench Groups
Once you’ve defined a group, you can share a workspace or cloud resource with that group.
You can share a workspace via the Workbench UI:
You can also share a workspace via the
terra command-line tool:
$ terra workspace add-user Usage: terra workspace add-user --email=<email> [--format=<format>] --role=<role> [--workspace=<id>] Add a user or group to the workspace. --email=<email> User or group email. --format=<format> Set the format for printing command output: JSON, TEXT. Defaults to the config format property. Default: null --role=<role> Role to grant: READER, WRITER, OWNER. --workspace=<id> Workspace id to use for this command only.
You can make other Google Cloud resources accessible to a Workspace Group:
Note: The Workspace group addresses have the domain name
verily-bvdp.com. Your company may have instituted an organization policy for its own Google Cloud projects that prevents setting up IAM permissions for addresses outside your domain. If that is the case, you can create a Google group under your org, add the Workspace Group(s) as members, and share the resource with the Google Group.
Last Modified: 16 November 2023