How to create and manage Verily Workbench groups

How to create and manage Verily Workbench groups

Verily 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.

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.

The terra group subcommands are as follows:

Usage: terra group [COMMAND]
Manage groups of users.
  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
amyu-test-workspace-group            1  [ADMIN]
companyA-users                                     6  [ADMIN]
my-team                                       unknown  [MEMBER]

Type 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 ADMIN.

$ 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>
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.

The --policy argument determines whether the user is added as a MEMBER or ADMIN.

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 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