Managing organizations and users

Note: The organization and user management features described below will be rolled out over a period of weeks starting in March 2024, with planned improvements and extensions in future releases. Contact Workbench Support if you are interested in learning more.

Introduction

Flexible and structured management of users is a core requirement for enterprise software platforms. Organizational administrators should have visibility into the status of their population of managed users. IT and security administrators should be able to set organization-wide defaults and policy requirements, and well-defined organizational roles should support self-service actions where possible to ensure scalability.

To support these needs, Verily Workbench maintains a top-level Organization concept, representing a set of users linked by their employer or primary institutional identity. Each user, workspace, and data collection belongs to exactly one organization, creating a clear boundary of ownership, management, and control.

Most Workbench customers will identify an organization admin from within their team to manage the organization and user lifecycle, enable self-service onboarding and offboarding of researchers, and direct control over policy and billing details. In some cases (and depending on the license agreement) a Workbench customer may delegate this responsibility to the Workbench Support team instead. For more information about admin and user roles, see Organization roles and permissions.

Key concepts

Organization

An organization in Workbench represents the top level of tenancy within the enterprise platform. Every workspace, data collection, and user can trace back to a single owning organization, providing a logical unit of separation, administration, and ownership.

Conceptually, a Workbench organization is somewhat similar to a Google Cloud organization (where Google Cloud projects are all housed under a single Google Cloud organization) or to an Active Directory domain (where Active Directory users are housed under a single domain). Of course, there are differences in how exactly this concept is applied to the Workbench system.

Each organization contains the following:

• Metadata and configuration (e.g., name, description, and an optional default cloud billing configuration).
• Users and roles.
• Resources (e.g., workspaces and data collections).

User lifecycle

The lifecycle of a Workbench user involves the following states:

• Invited: The user has been invited to join Workbench and (if required by license) acknowledge the terms of service.
• Active: The user is in good standing and may access Workbench features subject to their parent organization’s configuration.
• Disabled: The user has been disabled by an organization or Workbench administrator. The user may be re-enabled with all prior permissions kept intact.
• Archived: The user has been permanently removed from all access to Workbench. All permissions and group memberships have been removed. To regain access, the individual must be re-invited to Workbench.

Every Workbench user must be a member of exactly one organization. It is typically an organization admin who invites new users to the system (see Invite a new user to your organization). Administrators may also transition a user to a temporary Disabled state (if they expect to regain access in the near future), or a more permanent Archived state (if they are no longer an employee or have left the sponsoring organization).

Managing organizations

Organization roles and permissions

The set of roles and permissions at the organization level is as follows:

Note: There is a separate Workbench “superadmin” role, which allows for creating new organizations and configuring organization admins. This role is only ever assumed by the Workbench Support and Operations teams.

Request a new organization

New organizations are created by a Workbench superadmin. Generally a new organization will be created as part of the onboarding process of a new Workbench customer.

In some scenarios, it may make sense to create a new organization to represent a new group of users who will access Workbench under an existing license agreement (i.e., collaborators from a new institution or customer organization). In this case, please contact Workbench Support to request a new organization. Include at least the following information:

Name: Example Organization
Short name: example-org
Administrator emails: admin.1@example.com, admin.2@example.com

To verify the details of the new organization (and to confirm that you’ve been granted administrative permissions), use the wb org describe and wb org user list commands from the command-line interface (CLI):

$ wb org describe --org=example-org

ID: example-org
Name: Example Organization
ToS Required: true
Description: (unset)

$ wb org user list --org=example-org

EMAIL                           STATE       TOS STATUS           ROLES
admin.1@example.com             ENABLED     TOS_OK               ADMIN

Grant the organization admin role

The individual(s) entrusted to administer a given organization may change over time. An admin can grant admin privileges to another user with the wb org role grant CLI command:

$ wb org role grant --org=example-org --email=admin.2@example.com --role=ADMIN
Granted ADMIN role to admin.2@example.com in example-org.

Note: It is possible for a Workbench user who is a member of one organization to be an administrator of one or more other organizations by having the “organization admin” role granted to them on multiple organizations. This setup may make sense in a setting where one Workbench customer is coordinating a research collaboration between researchers from multiple home institutions. Each institution would have a distinct organization, but an administrator from the customer organization might be granted “organization admin” access across all collaborating institutions, for the sake of efficiency.

Set organization-level defaults

Organization administrators may update metadata related to the organization and set defaults which will apply to certain aspects of Workbench usage by members of the organization. This may be done using the wb org update CLI command:

wb org update --org=example-org --new-description="Researchers working under Example Corp to access the Foo Bar dataset in Workbench"

Managing users

Note: Most user management functionality requires use of the Workbench CLI. This provides a base level of support for administrative and automation-driven usage. Addition of user management functionality to the Workbench web portal is expected in a future release.

Invite a new user to your organization

An organization admin is responsible for inviting new users to Workbench.

A typical user invite flow involves the following steps:

1. Organization admin invites the user with the wb org user invite command:

   $ wb org user invite --org=example-org --email=user.1@example.com
   

2. (Optional, but necessary for creating new workspaces) Organization admin grants the user access to billing resources within the organization.

3. Organization admin notifies the user that they’ve been invited and to visit https://workbench.verily.com/ to acknowledge the terms of service and gain access to Workbench.

4. The invited user logs in, acknowledges the terms of service, and continues to Workbench.

Acknowledge the terms of service

Depending on licensing terms, when a new user first logs in to Workbench, they may be asked to first acknowledge the standard terms of service:

After clicking “Accept,” the user is redirected to the Workbench homepage and may access workspaces and data collections shared with them.

View users in your organization

An organization admin may get an overview of all users within the organization with the wb org user list command:

$ wb org user list --org=example-org

EMAIL                        STATE            TOS STATUS      ROLES
admin.1@example.com          ACTIVE           TOS_OK          ADMIN
user.1@example.com           ARCHIVED         TOS_OK          USER

Note: In some cases, a user who belongs to one organization may have been granted the “organization admin” role on another organization. In this case, the admin user will show up in the wb org user list output for the second organization, but the STATE and TOS STATUS columns will be (Unset).

Disable or archive a user

If a user should no longer have access to Workbench, an organization admin may temporarily disable or permanently remove a user’s access.

First, disable a user with the wb org user disable command:

$ wb org user disable --email=user.1@example.com --org=example-org

User user.1@example.com disabled in the organization example-org.

Disabling a user in Workbench will cause their login access to Workbench to be revoked, without permanently removing that user’s presence in workspace and organization ACLs and permission sets. This allows the operation to be completed quickly and to be easily reversible, e.g., if an employee is on temporary leave.

Once disabled, a user may be more permanently removed from Workbench with the wb org user archive command:

$ wb org user archive --org=example-org --email=user.1@example.com
Email: user.1@example.com
State: DISABLED
ToS Status: TOS_OK
Org Roles: USER
Archiving users cannot be undone. Are you sure you want to archive this user? (y/N) y
User user.1@example.com has been archived in the organization example-org.

Note: Currently, once a user with a given email address has been archived, they may not be re-invited to Workbench. This restriction is expected to be relaxed in a future release.