Create & manage user groups in Verily Workbench

Purpose: This document provides details for creating, using, and managing user groups in Verily Workbench.

Introduction

Verily Workbench allows you to define and manage groups of registered users, called Workbench groups. Workbench groups are useful for many reasons.

You can use them to define and manage sets of users that have different semantics for your purposes. For example,

• Users who are workspace Readers vs users who are workspace Writers
• Users from Company A vs users from Company B

You can also share a workspace and its resources with a given group, (e.g., "customers from Company A"). 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 Cloud Storage bucket to be readable by a group of users. For more information, see Access sharing best practices.

Every Workbench user has their own "workspace service account." 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 apps are configured to "act as" your workspace SA.

Adding a member to a Workbench group implicitly adds their workspace service account to the group as well. So, by sharing a resource with a Workbench group, you're sharing that resource with the group members' service accounts as well, and this will allow them to, for example, access that resource from their apps 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. When you need to grant a user access to data on Google Cloud, it's best practice to grant access to a Workbench group instead of an individual user.

Each Workbench user has an associated automatically-created proxy group that holds only that user and their workspace 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 wb command-line tool. If you don't want to install the wb tool locally, you can create an app in a Workbench workspace, which will have wb already installed and configured for you. One easy way to access the command-line tool from an app 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 of another group.

The wb group subcommands are as follows:

Usage: wb group [COMMAND]
Manage groups of Workbench users.
Commands:
  add-user     Add a user to a group with a given policy.
  create       Create a new Workbench group.
  delete       Delete an existing Workbench 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:

$ wb group list

The output will look similar to this:

$ wb group list
NAME                            EMAIL                                          MEMBERS  POLICIES
amy-test-workspace-group        amy-test-workspace-group@verily-bvdp.com             1  [ADMIN]
companyA-users                  companyA@verily-bvdp.com                             6  [ADMIN]
my-team                         my-team@verily-bvdp.com                        unknown  [MEMBER]

Note that your proxy group is not included in the wb group list output.

Type wb group <subcommand> to see usage details for a subcommand. For example:

$ wb group create
Missing required option: '--name=<name>'
Usage: wb group create [--format=<format>] --name=<name>
Create a new Workbench 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.

$ wb group list-users --name=amyu-test-workspace-group

Adding a user to a group

To add a user to a group you administer, use wb group add-user:

Usage: wb 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.

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 "workspace service account" for the current workspace, by running the command:

wb auth status

You can also see the proxy group listed in Your profile:

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 wb command-line tool:

$ wb workspace add-user
Usage: wb 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: