Identity Providers & Access Grants Setup Guide

Wharby workspaces use a Zero-Trust Access Grants model (w_<workspace>.grants). Users authenticate through your workspace's configured Identity Provider (GitHub or Google Workspace), and Wharby evaluates their verified email, domain, organization, and group/team memberships against your workspace's active Access Grants.

1. Access Grant Principal Types

In your workspace's Settings $\rightarrow$ Access Grants & Gerrit Roles portal (https://<workspace>.wharby.dev/settings/workspace-roles), administrators can grant Gerrit roles (Administrators, Core Developers, Reviewers, Read Only, or custom groups) using five principal types:

Grant Type Match Key Format Example Description
Email (email) user@domain.com alice@acme.com Matches a single verified email address.
Domain (email_domain) domain.com acme.com Matches any user with a verified email in that domain.
Group / Team (group) group@domain.com or org/team-slug engineering@acme.com or acme-corp/core-devs Matches a Google Workspace Group email or a GitHub Team slug. Must be fully qualified.
Organization (org) github-org-login acme-corp Matches any member of the specified GitHub Organization.
All Users (all) * * Matches any authenticated user (useful for open-source workspaces granting Read Only or Reviewers).

Important Multi-Domain Rule: Bare group or team names (such as engineers or core-devs without @domain.com or org/) are rejected to guarantee strict multi-tenant isolation.

2. Setting Up GitHub Identity, Orgs & Teams

When your workspace uses GitHub as its Identity Provider:

  1. Install the Official Wharby GitHub App on Your Organization:
    • Have a GitHub Organization Owner install the official Wharby GitHub App on your GitHub organization:
    • Installing the GitHub App enables two essential capabilities for your organization:
      1. Private Organization & Team Discovery: Allows Wharby to verify private organization (acme-corp) and team (acme-corp/core-devs) memberships when your engineers sign in.
      2. Real-Time Access Revocation Webhooks: Whenever a user is removed from your GitHub organization or team (organization.member_removed, membership.removed, team.deleted), GitHub notifies Wharby in real time to immediately invalidate their workspace role cache and revoke active sessions.
  2. Add Organization or Team Access Grants:
    • For an entire GitHub organization, choose Organization (org) and enter the organization login (e.g. acme-corp).
    • For a specific GitHub team, choose IdP Group (group) and enter the fully-qualified <org>/<team-slug> identifier (e.g. acme-corp/core-devs).

3. Setting Up Google Workspace Identity & Google Groups

When your workspace uses Google Workspace as its Identity Provider:

  1. Google Workspace Group Grants (group@domain.com):
    • Choose IdP Group (group) and enter the full email address of the Google Group (e.g. engineering@acme.com).
  2. Ensure Group Member Visibility in Google Workspace:
    • Wharby queries the Google Cloud Identity Groups API (cloud-identity.groups.readonly) using the signing-in user's OAuth token—requiring zero domain-wide admin service account setup.
    • In your Google Admin Console (or Google Groups settings for engineering@acme.com), ensure "Who can view members" is set to Group members (or Entire organization). If a group hides its membership list from its own members, Google's API will not return that group for non-admin users.
  3. Personal @gmail.com Accounts:
    • Personal @gmail.com accounts work out of the box with Email (email) grants (e.g. developer@gmail.com).
    • Note that consumer @googlegroups.com mailing lists are not exposed by Google's Cloud Identity API; use direct email grants for @gmail.com collaborators.

4. Switching Identity Providers & Emergency Admin Reset

Workspace owners can switch a workspace's active Identity Provider or perform an Emergency Administrator Reset at any time from the Wharby Management Portal (https://wharby.dev/workspaces/<workspace> under Danger Zone).