Manage groups

Prior reading: Manage organizations

Purpose: This document provides details for creating, using, and managing 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.

Organization-scoped groups and legacy groups

The Workbench group system has been changed to place groups under the control of an organization. That has several benefits:

• Organization admins can create and manage the groups in their organization. They can control who is allowed to create a new group.
• Group names are scoped to an organization. Users are free to pick names that are unique within their organization.
• The member role can be set to expire after some number of days.

Legacy groups, also called global groups, continue to work as they did before. Eventually, all groups will be migrated into an organization. Workbench personnel will assist in this process.

Managing Groups

Group roles and permissions

The set of roles and permissions on a group are as follows:

Group Commands

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:

Manage groups of Workbench users.
Usage: wb group [COMMAND]
Commands:
  add-user      DEPRECATED: please use 'role grant'
  create        Create a new Workbench group.
  delete        Delete an existing group.
  describe      Describe a group.
  list          List the groups the current user has a role on.
  list-users    DEPRECATED: please use 'role list'
  role, member  Manage roles of groups.
  migrate       Migrate a global group to an organization group.
  remove-user   DEPRECATED: please use 'role revoke'
  update        Update the attributes of a Workbench group.

The role command is standardized across groups, pods, and organizations. The non-standard commands (add-user, list-users, remove-users) are deprecated, but continue to work.

To see the Workbench groups that you currently belong to use:

wb group list

The output will look similar to this:

$ wb group list
NAME                   ORGANIZATION  ROLES 
example-group          example-org   ADMIN, MEMBER
example-org-users      example-org   MEMBER
legacy-group           (unset)       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:

Creating a new group

You create a group with this command:

$ wb group create
Usage: wb group create --name=<name> --org=<id>
                       [--description=<description>]
                       [--expiration=<expiration>]
                       [--expiration-notification[=<expirationNotification>]]
                       [--require-grant-reason[=<requireGrantReason>]]
                       [--sync[=<syncToGoogle>]]
                       [--format=<format>]
Create a new Workbench group.
      --description=<description>
                          Description of the group
      --expiration=<expiration>
                          The default and maximimum MEMBER role expiration in
                            days. Zero means the MEMBER role does not expire.
      --expiration-notification[=<expirationNotification>]
                          Notify group admins about member expirations
      --format=<format>   Set the format for printing command output: JSON,
                            TEXT. Defaults to the config format property.
                            Default: null
      --name=<name>       Group name.
      --org, --organization=<id>
                          Organization ID (unique).
      --require-grant-reason[=<requireGrantReason>]
                          Require a reason on grants to the group
      --sync, --sync-to-google[=<syncToGoogle>]
                          Synchronize the workbench group with a Google Group.

At a minimum, give the group a name and specify which organization it will belong to. You also have a number of other attributes you can set on the group.

When the group is created, you, the creator, will have the admin role on the group. You can then populate your group by granting roles to other users and groups. The term "principal" refers to a user or a group that is granted a role.

Member Role Expiration

By default, when a group is created it has an expiration of zero (0), which means membership never expires. You can set an expiration time for a group as the number of days before membership expires. The value you set is both the default and the maximum expiration days.

When a user or group is granted the MEMBER role on the group, the expiration date is computed. When the expiration date has passed, the MEMBER role is revoked. The principal may have other roles on the group. Those are not subject to expiration. For example, a user might have both MEMBER and READER roles. After expiration, the user would have the READER role.

If you set --expiration-notification or --expiration-notification=true, then the users with the admin role will receive an email roughly a day before a principal's membership expires. That gives you time to update the member's expiration (see group role update-expiration before their membership expires. Users with the admin role will also receive email after the membership has been revoked.

Workbench Groups and Google Groups

By default, all Workbench groups are synchronized with a Google Group. The Workbench system automatically keeps the Google Group current with the membership of the Workbench group. Changes to the Workbench group are typically applied to the Google Group within minutes.

Maintaining a synchronized Google Group has some overhead. If you are not using the Google Group for external access control, you can disable the synchronization by specifying --sync-to-google=false. See Access sharing best practices for more information about using Google Groups for external access.

Note that your group may still get synchronized if a group your group is a member of is synchronized. For example, group A has group B as a member. If group A is set to synchronize, then group B will get synchronized to support group A.

Requiring a reason for a grant

You may supply a reason when granting or revoking a role on a group. The reason is written to the Workbench log for auditing purposes. Some compliance schemes require that a reason be recorded and entered into the audit log when a principal is granted access to a group. You can meet that requirement by setting --require-grant-reason or --require-grant-reason=true.

Describing a group

If you have the admin role on a group, then you can view the attributes of a group:

wb group describe --name=example-group --org=example-org

If the group is synchronized with a Google Group, this will show the Google Group email address for use in external access control.

Updating a group

You can update group attributes using this command:

 $ wb group update
Usage: wb group update --name=<name> --org=<id>
                       [--description=<description>]
                       [--expiration=<expiration>]
                       [--expiration-notification[=<expirationNotification>]]
                       [--require-grant-reason[=<requireGrantReason>]]
                       [--sync[=<syncToGoogle>]]
                       [--format=<format>]
Update the attributes of a Workbench group.
      --description=<description>
                          Description of the group
      --expiration=<expiration>
                          The default and maximimum MEMBER role expiration in
                            days. Zero means the MEMBER role does not expire.
      --expiration-notification[=<expirationNotification>]
                          Notify group admins about member expirations
      --format=<format>   Set the format for printing command output: JSON,
                            TEXT. Defaults to the config format property.
                            Default: null
      --name=<name>       Group name.
      --org, --organization=<id>
                          Organization ID (unique).
      --require-grant-reason[=<requireGrantReason>]
                          Require a reason on grants to the group
      --sync, --sync-to-google[=<syncToGoogle>]
                          Synchronize the workbench group with a Google Group.
738 2025-04-07T13:50:42 cli $ 

Updating Group Expiration

If you change expiration from enabled (value greater than zero) to disabled (value equal to zero), then all MEMBER role expiration dates are removed.

If you change expiration from disabled (value equal to zero) to enabled (value greater than zero), then all MEMBER role expiration dates are set to that number of days from now.

If you modify the expiration time from one value to another, then existing expiration dates are not changed.

Updating Synchronization

You can trigger an unsynchronized group to be synchronized with a Google Group by updating and setting --sync or --sync-to-google=true. However, once synchronized, you cannot stop the group from being synchronized. That is, you cannot go from --sync-to-google=true to --sync-to-google=false.

Managing Group Roles

If you have the admin role on a group, you will be able to list the users in a group. The creator of a group automatically gets the admin role.

You can list the principals with roles on your group like this:

wb group role list --name=example-group --org=example-org

You can list the principals of a legacy group by omitting the --org option.

Granting a role

To add a principal to a group you administer, use wb group role grant. There are three forms depending on whether the principal is a user, another group, or public.

In the samples below, the --role argument determines whether the principal is added as a MEMBER, READER or ADMIN. You may grant more than one role to a principal by issuing more than one role grant command. Also, the samples show the example group as an organization-scoped group. You can use the command to grant roles on a legacy group by omitting the --org argument.

Grant a role to a user

Example granting a user the MEMBER role on the example-group in the example-org:

wb group role grant user --name=example-group --org=example-org 
                         --role=MEMBER
                         --email=user@example.com
                         --reason="Add user as a member so they can help on the example project"

Grant a role to a group

Example granting the other-group in the other-org the MEMBER role on the example-group:

wb group role grant group --name=example-group --org=example-org
                          --role=MEMBER
                          --group-name=other-group
                          --group-org=other-org

The member group can be from the same organization or a different one.

You can grant a role to a legacy group by leaving out the --group-org clause.

Grant a role to the public principal

The public principal is a built-in group containing all the users registered in Workbench. It is intended as a way for the Workbench team to make useful data collections and workspaces available to all Workbench users.

Example granting public the MEMBER role in the example-group:

wb group role grant public --name=example-group --org=example-org --role=MEMBER

Revoking a role

The revoke syntax is identical to the grant syntax, except for using the revoke keyword. Use:

• `wb group role revoke user`
• `wb group role revoke group`
• `wb group role revoke public`

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:

The command syntax is similar to granting and revoking group roles. However, you cannot yet grant the public principal on a workspace.

$ wb workspace role grant user
Usage: wb workspace role grant user --email=<email> --role=<role>
                                    [--workspace=<id>]
Grants a workspace role to a user.
      --email=<email>    User email.
      --role=<role>      Workspace role. Valid values are READER, WRITER,
                           OWNER, DISCOVERER.
      --workspace=<id>   Workspace id to use for this command only.

$ wb workspace role grant group
Usage: wb workspace role grant group --group-name=<groupMemberName>
                                     [--group-org=<groupOrg>] --role=<role>
                                     [--workspace=<id>]
Grants a workspace role to a group.
      --group-name=<groupMemberName>
                         Group name.
      --group-org=<groupOrg>
                         Organization of the group.
      --role=<role>      Workspace role. Valid values are READER, WRITER,
                           OWNER, DISCOVERER, SUPPORT.
      --workspace=<id>   Workspace id to use for this command only.

You can make other Google Cloud resources accessible to a workspace group: