Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

fix: expand group membership in workspace discovery and auth (#19699)

ecmadaoa83562479902
diff --git a/backend/api/auth/auth.go b/backend/api/auth/auth.go
index 9ce3c822ba..86725eb46f 100644
--- a/backend/api/auth/auth.go
+++ b/backend/api/auth/auth.go
@@ -238,6 +238,7 @@ func (in *APIAuthInterceptor) verifyWorkspaceMembership(ctx context.Context, wor
case storepb.PrincipalType_END_USER:
// END_USER membership is verified via workspace IAM policy.
+ // Check direct membership, group membership, and allUsers.
iamPolicy, err := in.store.GetWorkspaceIamPolicy(ctx, workspaceID)
if err != nil {
return errs.Wrap(err, "failed to get workspace IAM policy")
@@ -251,6 +252,13 @@ func (in *APIAuthInterceptor) verifyWorkspaceMembership(ctx context.Context, wor
if member == common.AllUsers && !in.profile.SaaS {
return nil
}
+ // Check group membership.
+ if strings.HasPrefix(member, common.GroupPrefix) {
+ groupMembers, _ := in.store.GetGroupMembersSnapshot(ctx, workspaceID, member)
+ if groupMembers != nil && groupMembers[userMember] {
+ return nil
+ }
+ }
}
}
return errs.Errorf("user %q is not a member of workspace %q", account.Email, workspaceID)
diff --git a/backend/api/auth/header.go b/backend/api/auth/header.go
index b5b4156925..6ed237146d 100644
--- a/backend/api/auth/header.go
+++ b/backend/api/auth/header.go
@@ -26,8 +26,9 @@ func GetTokenCookie(ctx context.Context, stores *store.Store, licenseService *en
return &http.Cookie{
Name: AccessTokenCookieName,
Value: token,
- // Cookie outlives the JWT so that Refresh() can extract the workspace from the expired token.
- // The auth middleware rejects expired JWTs, so an expired JWT in the cookie is harmless.
+ // Cookie outlives the JWT by 30 seconds so that Refresh() can extract the
+ // workspace from the expired token. The frontend calls Refresh immediately
+ // on 401, well within this window.
Expires: time.Now().Add(tokenDuration + 30*time.Second),
Path: "/",
// Http-only helps mitigate the risk of client side script accessing the protected cookie.
diff --git a/backend/api/v1/acl.go b/backend/api/v1/acl.go
index 0fc9d840d0..3672ae1c7a 100644
--- a/backend/api/v1/acl.go
+++ b/backend/api/v1/acl.go
@@ -292,6 +292,7 @@ func doIAMPermissionCheck(ctx context.Context, iamManager *iam.Manager, fullMeth
return true, nil, nil
}
+var workspaceRegex = regexp.MustCompile(`^workspaces/[^/]+`)
var projectRegex = regexp.MustCompile(`^projects/[^/]+`)
var databaseRegex = regexp.MustCompile(`^instances/[^/]+/databases/[^/]+`)
var instanceRegex = regexp.MustCompile(`^instances/[^/]+`)
@@ -317,7 +318,11 @@ func populateRawResources(ctx context.Context, stores *store.Store, request any,
for _, name := range rawNames {
switch {
case strings.HasPrefix(name, "workspaces/"):
- wsID, err := common.GetWorkspaceID(name)
+ match := workspaceRegex.FindString(name)
+ if match == "" {
+ return nil, errors.Errorf("invalid workspace resource %q", name)
+ }
+ wsID, err := common.GetWorkspaceID(match)
if err != nil {
return nil, err
}
diff --git a/backend/api/v1/group_service.go b/backend/api/v1/group_service.go
index e3e723d586..76fa2db33f 100644
--- a/backend/api/v1/group_service.go
+++ b/backend/api/v1/group_service.go
@@ -126,7 +126,7 @@ func (s *GroupService) CreateGroup(ctx context.Context, req *connect.Request[v1p
if err := s.licenseService.IsFeatureEnabled(ctx, common.GetWorkspaceIDFromContext(ctx), v1pb.PlanFeature_FEATURE_USER_GROUPS); err != nil {
return nil, connect.NewError(connect.CodePermissionDenied, err)
}
- groupMessage, err := s.convertToGroupMessage(ctx, req.Msg)
+ groupMessage, err := convertToGroupMessage(req.Msg)
if err != nil {
return nil, connect.NewError(connect.CodeInvalidArgument, err)
}
@@ -206,7 +206,7 @@ func (s *GroupService) UpdateGroup(ctx context.Context, req *connect.Request[v1p
if group.Payload.Source != "" {
return nil, connect.NewError(connect.CodeInvalidArgument, errors.New("cannot change members for external group"))
}
- payload, err := s.convertToGroupPayload(ctx, req.Msg.Group)
+ payload, err := convertToGroupPayload(req.Msg.Group)
if err != nil {
return nil, connect.NewError(connect.CodeInvalidArgument, err)
}
@@ -280,26 +280,11 @@ func (s *GroupService) checkPermission(ctx context.Context, group *store.GroupMe
return nil
}
-func (s *GroupService) convertToGroupPayload(ctx context.Context, group *v1pb.Group) (*storepb.GroupPayload, error) {
+func convertToGroupPayload(group *v1pb.Group) (*storepb.GroupPayload, error) {
payload := &storepb.GroupPayload{}
for _, member := range group.Members {
- email, err := common.GetUserEmail(member.Member)
- if err != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Wrap(err, "failed to get member email"))
- }
- user, err := s.store.GetUserByEmail(ctx, email)
- if err != nil {
- return nil, connect.NewError(connect.CodeInternal, errors.Wrapf(err, "failed to get member %s", member.Member))
- }
- if user == nil {
- return nil, connect.NewError(connect.CodeInvalidArgument, errors.Errorf("cannot found member %s", member.Member))
- }
- if user.Type != storepb.PrincipalType_END_USER {
- return nil, connect.NewError(connect.CodeInvalidArgument, errors.New("only allow add end users to the group"))
- }
-
m := &storepb.GroupMember{
- Member: common.FormatUserEmail(user.Email),
+ Member: member.Member,
}
switch member.Role {
case v1pb.GroupMember_MEMBER:
@@ -314,7 +299,7 @@ func (s *GroupService) convertToGroupPayload(ctx context.Context, group *v1pb.Gr
return payload, nil
}
-func (s *GroupService) convertToGroupMessage(ctx context.Context, request *v1pb.CreateGroupRequest) (*store.GroupMessage, error) {
+func convertToGroupMessage(request *v1pb.CreateGroupRequest) (*store.GroupMessage, error) {
if request.GroupEmail == "" {
return nil, connect.NewError(connect.CodeInvalidArgument, errors.New("missing group_email in the request"))
}
@@ -326,7 +311,7 @@ func (s *GroupService) convertToGroupMessage(ctx context.Context, request *v1pb.
Payload: &storepb.GroupPayload{},
}
- payload, err := s.convertToGroupPayload(ctx, request.Group)
+ payload, err := convertToGroupPayload(request.Group)
if err != nil {
return nil, connect.NewError(connect.CodeInvalidArgument, err)
}
diff --git a/backend/api/v1/project_service.go b/backend/api/v1/project_service.go
index aa9a49aa9e..1fecb2e021 100644
--- a/backend/api/v1/project_service.go
+++ b/backend/api/v1/project_service.go
@@ -595,7 +595,7 @@ func (s *ProjectService) SetIamPolicy(ctx context.Context, req *connect.Request[
return nil, connect.NewError(connect.CodeAborted, errors.Errorf("there is concurrent update to the project iam policy, please refresh and try again"))
}
- if err := validateIAMPolicy(ctx, s.store, req.Msg, oldIamPolicyMsg); err != nil {
+ if err := validateIAMPolicy(ctx, s.store, !s.profile.SaaS, req.Msg, oldIamPolicyMsg); err != nil {
return nil, err
}
@@ -1059,6 +1059,7 @@ func getBindingIdentifier(role string, condition *expr.Expr) string {
func validateIAMPolicy(
ctx context.Context,
stores *store.Store,
+ allowAllUsers bool,
msg *v1pb.SetIamPolicyRequest,
oldPolicyMessage *store.IamPolicyMessage,
) error {
@@ -1101,6 +1102,18 @@ func validateIAMPolicy(
}
}
+ // If allUsers is not allowed in IAM policies, members must be explicitly added.
+ if !allowAllUsers {
+ for _, binding := range bindings {
+ for _, member := range binding.Members {
+ if member == common.AllUsers {
+ return connect.NewError(connect.CodeInvalidArgument,
+ errors.New("allUsers is not allowed in workspace IAM policy in SaaS mode, add members explicitly"))
+ }
+ }
+ }
+ }
+
return validateBindings(msg.Resource, bindings, roleMessages, maximumRoleExpiration)
}
diff --git a/backend/api/v1/workspace_service.go b/backend/api/v1/workspace_service.go
index 08dd217117..274bafb87f 100644
--- a/backend/api/v1/workspace_service.go
+++ b/backend/api/v1/workspace_service.go
@@ -122,28 +122,22 @@ func (s *WorkspaceService) SetIamPolicy(ctx context.Context, req *connect.Reques
return nil, connect.NewError(connect.CodeAborted, errors.New("there is concurrent update to the workspace iam policy, please refresh and try again"))
}
- if err := validateIAMPolicy(ctx, s.store, request, policyMessage); err != nil {
+ if err := validateIAMPolicy(ctx, s.store, !s.profile.SaaS, request, policyMessage); err != nil {
return nil, err
}
- // In SaaS mode, allUsers is not allowed in workspace IAM policies.
- // Members must be explicitly added.
- if s.profile.SaaS {
- for _, binding := range request.Policy.Bindings {
- for _, member := range binding.Members {
- if member == common.AllUsers {
- return nil, connect.NewError(connect.CodeInvalidArgument,
- errors.New("allUsers is not allowed in workspace IAM policy in SaaS mode, add members explicitly"))
- }
- }
- }
- }
-
iamPolicy, err := convertToStoreIamPolicy(request.Policy)
if err != nil {
return nil, err
}
- users := utils.GetUsersByRoleInIAMPolicy(ctx, s.store, common.GetWorkspaceIDFromContext(ctx), store.WorkspaceAdminRole, iamPolicy)
+ users := utils.GetUsersByRoleInIAMPolicy(
+ ctx,
+ s.store,
+ common.GetWorkspaceIDFromContext(ctx),
+ store.WorkspaceAdminRole,
+ !s.profile.SaaS,
+ iamPolicy,
+ )
if !containsActiveEndUser(users) {
return nil, connect.NewError(connect.CodeInvalidArgument, errors.New("workspace must have at least one admin"))
}
diff --git a/backend/runner/approval/runner.go b/backend/runner/approval/runner.go
index 1b30dc5cc7..4e101de981 100644
--- a/backend/runner/approval/runner.go
+++ b/backend/runner/approval/runner.go
@@ -962,7 +962,17 @@ func getApproversForRole(ctx context.Context, stores *store.Store, projectID str
}
// Get all users with the specified role
- users := utils.GetUsersByRoleInIAMPolicy(ctx, stores, project.Workspace, role, projectIAM.Policy, workspaceIAM.Policy)
+ users := utils.GetUsersByRoleInIAMPolicy(
+ ctx,
+ stores,
+ project.Workspace,
+ role,
+ // TODO(ed): tmp hack
+ // It's not allowed set AllUsers in the IAM, so will not break the new SaaS workflow.
+ true,
+ projectIAM.Policy,
+ workspaceIAM.Policy,
+ )
// Convert to webhook.User format, filtering by END_USER principal type
approvers := make([]webhook.User, 0, len(users))
diff --git a/backend/store/workspace.go b/backend/store/workspace.go
index 5a431484d5..b02244e156 100644
--- a/backend/store/workspace.go
+++ b/backend/store/workspace.go
@@ -195,11 +195,25 @@ func (s *Store) FindWorkspace(ctx context.Context, find *FindWorkspaceMessage) (
}
// ListWorkspacesByEmail finds all workspaces where the given email is a member
-// in the workspace IAM policy bindings.
+// in the workspace IAM policy bindings, either directly or via a group.
// Returns workspaces sorted by name.
func (s *Store) ListWorkspacesByEmail(ctx context.Context, find *FindWorkspaceMessage) ([]*WorkspaceMessage, error) {
memberName := common.FormatUserEmail(find.Email)
+
+ // Check direct membership OR group membership:
+ // 1. Direct: member = 'users/{email}'
+ // 2. Group: member = 'groups/{groupEmail}' and user_group with that email
+ // contains 'users/{email}' in its payload.members[].member
+ // 3. AllUsers: member = 'allUsers' (self-hosted only)
memberFilter := qb.Q().Space("member = ?", memberName)
+ memberFilter.Or(`member LIKE 'groups/%' AND EXISTS (
+ SELECT 1
+ FROM user_group ug,
+ jsonb_array_elements(ug.payload->'members') AS gm
+ WHERE ug.workspace = w.resource_id
+ AND 'groups/' || ug.email = member
+ AND gm->>'member' = ?
+ )`, memberName)
if find.IncludeAllUser {
memberFilter.Or("member = ?", common.AllUsers)
}
@@ -208,8 +222,8 @@ func (s *Store) ListWorkspacesByEmail(ctx context.Context, find *FindWorkspaceMe
SELECT DISTINCT w.resource_id, w.name
FROM workspace w
JOIN policy p ON p.workspace = w.resource_id
- WHERE p.resource_type = 'WORKSPACE'
- AND p.type = 'IAM'
+ WHERE p.resource_type = ?
+ AND p.type = ?
AND w.deleted = FALSE
AND EXISTS (
SELECT 1
@@ -217,7 +231,7 @@ func (s *Store) ListWorkspacesByEmail(ctx context.Context, find *FindWorkspaceMe
jsonb_array_elements_text(binding->'members') AS member
WHERE ?
)
- `, memberFilter)
+ `, storepb.Policy_WORKSPACE.String(), storepb.Policy_IAM.String(), memberFilter)
if v := find.WorkspaceID; v != nil {
q.And("w.resource_id = ?", *v)
}
diff --git a/backend/utils/member.go b/backend/utils/member.go
index 97bb30dfff..5561cffa2d 100644
--- a/backend/utils/member.go
+++ b/backend/utils/member.go
@@ -34,7 +34,14 @@ func FormatGroupName(group *store.GroupMessage) string {
// GetUsersByRoleInIAMPolicy gets users in the iam policy.
// The role can be either with or without the "roles/" prefix.
-func GetUsersByRoleInIAMPolicy(ctx context.Context, stores *store.Store, workspace string, role string, policies ...*storepb.IamPolicy) []*store.UserMessage {
+func GetUsersByRoleInIAMPolicy(
+ ctx context.Context,
+ stores *store.Store,
+ workspace string,
+ role string,
+ allowAllUsers bool,
+ policies ...*storepb.IamPolicy,
+) []*store.UserMessage {
roleFullName := role
if !strings.HasPrefix(role, common.RolePrefix) {
roleFullName = common.FormatRole(role)
@@ -53,7 +60,7 @@ func GetUsersByRoleInIAMPolicy(ctx context.Context, stores *store.Store, workspa
}
for _, member := range binding.Members {
- if member == common.AllUsers {
+ if member == common.AllUsers && allowAllUsers {
// TODO(d): make it more efficient.
allUsers, err := stores.ListUsers(ctx, &store.FindUserMessage{
ShowDeleted: false,
diff --git a/docs/plans/saas/00.challenges-and-roadmap.md b/docs/plans/saas/00.challenges-and-roadmap.md
index 35b2be3e65..f1e27a8528 100644
--- a/docs/plans/saas/00.challenges-and-roadmap.md
+++ b/docs/plans/saas/00.challenges-and-roadmap.md
@@ -6,7 +6,7 @@ Refactor Bytebase from per-user isolation (one container per workspace) to a tru
## Chosen Approach: Row-Level Isolation
-Add a `workspace_id` column to root-level tables. Project-child tables reuse their existing `project` FK for workspace scoping -- the `project` table has `workspace_id`, so any query that filters by `project` is implicitly workspace-scoped.
+Add a `workspace` column to root-level tables. Project-child tables reuse their existing `project` FK for workspace scoping -- the `project` table has `workspace`, so any query that filters by `project` is implicitly workspace-scoped.
---
@@ -18,11 +18,11 @@ Separate different workspaces so users only see their own data.
### Challenge 2: Database Connection Routing
-Single connection pool; workspace resolved from JWT, applied as query filter (`WHERE workspace_id = $1` on root tables, `WHERE project = $1` on project children).
+Single connection pool; workspace resolved from JWT, applied as query filter (`WHERE workspace = $1` on root tables, `WHERE project = $1` on project children).
### Challenge 3: Background Runners
-Runners poll for pending tasks across ALL workspaces with a single query. Each task carries `workspace_id` for context when processing.
+Runners poll for pending tasks across ALL workspaces with a single query. Each task carries `workspace` for context when processing.
### Challenge 4: API Resource Naming
@@ -34,17 +34,17 @@ Two options:
**Option A: Keep flat names, resolve workspace from JWT (recommended)**
-The middleware resolves workspace from the JWT and injects it as a query parameter. Resource IDs like `projects/default` are unique per-workspace because `project` has `UNIQUE(workspace_id, resource_id)`. Project-child queries use the project FK which is already workspace-scoped.
+The middleware resolves workspace from the JWT and injects it as a query parameter. Resource IDs like `projects/default` are unique per-workspace because `project` has `UNIQUE(workspace, resource_id)`. Project-child queries use the project FK which is already workspace-scoped.
- Zero API breaking changes
- Zero proto changes
-- Resource ID uniqueness scoped by `workspace_id` in unique indexes on root tables
+- Resource ID uniqueness scoped by `workspace` in unique indexes on root tables
**Option B: Explicit workspace prefix (`workspaces/{workspace}/projects/{project}`)**
AIP-compliant but requires changing every endpoint, proto definition, resource name parser, frontend API call, and external integration (Terraform provider, API clients, webhooks).
-**Recommendation**: Option A. Workspace scoping is enforced at the DB level (root tables via `workspace_id`, child tables via `project` FK), making URL-level scoping redundant.
+**Recommendation**: Option A. Workspace scoping is enforced at the DB level (root tables via `workspace`, child tables via `project` FK), making URL-level scoping redundant.
### Challenge 5: Multi-Workspace User Identity
@@ -54,11 +54,11 @@ SaaS model requires:
- A user can belong to multiple workspaces
- Auth (login, password, MFA, OAuth) is workspace-independent
- After login, user picks a workspace (or auto-redirects if only one)
-- JWT includes both `user_id` and `workspace_id`
+- JWT includes both `user_id` and `workspace`
**Solution**: Split the `principal` table into three separate tables:
-- **`principal`** -- keeps only END_USER rows. This IS the global account/identity table. No `workspace_id` needed (a user can belong to multiple workspaces). No data migration required -- just remove SERVICE_ACCOUNT/WORKLOAD_IDENTITY rows.
-- **`service_account`** -- new table for SERVICE_ACCOUNT rows. Workspace-scoped via `project` FK (project-level) or `workspace_id` (workspace-level).
+- **`principal`** -- keeps only END_USER rows. This IS the global account/identity table. No `workspace` needed (a user can belong to multiple workspaces). No data migration required -- just remove SERVICE_ACCOUNT/WORKLOAD_IDENTITY rows.
+- **`service_account`** -- new table for SERVICE_ACCOUNT rows. Workspace-scoped via `project` FK (project-level) or `workspace` (workspace-level).
- **`workload_identity`** -- new table for WORKLOAD_IDENTITY rows. Same scoping as service_account.
The store layer already treats these as separate entities (`principal.go`, `principal_service_account.go`, `principal_workload_identity.go`), all querying the same `principal` table with `WHERE type = ?`. The split makes the schema match the existing code structure.
@@ -67,21 +67,21 @@ Workspace membership is tracked by the `policy` table's IAM policy (`resource_ty
### Why RLS Was Rejected
-RLS policies are per-table: each table must have its own `workspace_id` column for the policy `USING (workspace_id = current_setting('app.workspace_id'))` to evaluate. This means:
+RLS policies are per-table: each table must have its own `workspace` column for the policy `USING (workspace = current_setting('app.workspace'))` to evaluate. This means:
-- All 30+ workspace-scoped tables would need a `workspace_id` column
+- All 30+ workspace-scoped tables would need a `workspace` column
- Cannot leverage existing `project` FK for workspace scoping on child tables
- Conflicts with the goal of minimizing schema changes
-Row-level isolation with project-FK scoping requires `workspace_id` on only 12 root tables, while child tables use their existing FK relationships.
+Row-level isolation with project-FK scoping requires `workspace` on only 12 root tables, while child tables use their existing FK relationships.
---
## Table Classification
-### Tier 1: Root Tables That Need `workspace_id` (12 tables)
+### Tier 1: Root Tables That Need `workspace` (12 tables)
-These are top-level entities with no parent FK that provides workspace scoping. They get a `workspace_id` column directly.
+These are top-level entities with no parent FK that provides workspace scoping. They get a `workspace` column directly.
| Table | Notes |
|-------|-------|
@@ -100,7 +100,7 @@ These are top-level entities with no parent FK that provides workspace scoping.
### Tier 2: Project Children -- Scoped via `project` FK (9 tables)
-These already have a `project` FK referencing `project(resource_id)`. Since `project` has `workspace_id`, queries on these tables filter by `WHERE project = $1` where the project is already validated as belonging to the current workspace. **No `workspace_id` column needed.**
+These already have a `project` FK referencing `project(resource_id)`. Since `project` has `workspace`, queries on these tables filter by `WHERE project = $1` where the project is already validated as belonging to the current workspace. **No `workspace` column needed.**
| Table | FK |
|-------|-----|
@@ -116,15 +116,15 @@ These already have a `project` FK referencing `project(resource_id)`. Since `pro
### Tier 3: Grandchild Tables -- Scoped via Parent Chain (11 tables)
-These are children of Tier 2 tables. They have no `project` FK and no `workspace_id`. Workspace scoping is inherited through the FK chain -- they are always accessed via their parent, which is already workspace-scoped.
+These are children of Tier 2 tables. They have no `project` FK and no `workspace`. Workspace scoping is inherited through the FK chain -- they are always accessed via their parent, which is already workspace-scoped.
**Plan/pipeline grandchildren (5):**
| Table | FK chain to workspace |
|-------|----------------------|
-| `plan_check_run` | -> `plan(id)` -> `plan.project` -> `project.workspace_id` |
-| `plan_webhook_delivery` | -> `plan(id)` -> `plan.project` -> `project.workspace_id` |
-| `task` | -> `plan(id)` -> `plan.project` -> `project.workspace_id` |
+| `plan_check_run` | -> `plan(id)` -> `plan.project` -> `project.workspace` |
+| `plan_webhook_delivery` | -> `plan(id)` -> `plan.project` -> `project.workspace` |
+| `task` | -> `plan(id)` -> `plan.project` -> `project.workspace` |
| `task_run` | -> `task(id)` -> `plan(id)` -> ... |
| `task_run_log` | -> `task_run(id)` -> `task(id)` -> ... |
@@ -132,24 +132,24 @@ These are children of Tier 2 tables. They have no `project` FK and no `workspace
| Table | FK chain to workspace |
|-------|----------------------|
-| `issue_comment` | -> `issue(id)` -> `issue.project` -> `project.workspace_id` |
+| `issue_comment` | -> `issue(id)` -> `issue.project` -> `project.workspace` |
**DB grandchildren (4):**
| Table | FK chain to workspace |
|-------|----------------------|
-| `db_schema` | -> `db` (via instance+db_name) -> `db.project` -> `project.workspace_id` |
-| `revision` | -> `db` (via instance+db_name) -> `db.project` -> `project.workspace_id` |
-| `sync_history` | -> `db` (via instance+db_name) -> `db.project` -> `project.workspace_id` |
-| `changelog` | -> `db` (via instance+db_name) -> `db.project` -> `project.workspace_id` |
+| `db_schema` | -> `db` (via instance+db_name) -> `db.project` -> `project.workspace` |
+| `revision` | -> `db` (via instance+db_name) -> `db.project` -> `project.workspace` |
+| `sync_history` | -> `db` (via instance+db_name) -> `db.project` -> `project.workspace` |
+| `changelog` | -> `db` (via instance+db_name) -> `db.project` -> `project.workspace` |
**Worksheet grandchildren (1):**
| Table | FK chain to workspace |
|-------|----------------------|
-| `worksheet_organizer` | -> `worksheet(id)` -> `worksheet.project` -> `project.workspace_id` |
+| `worksheet_organizer` | -> `worksheet(id)` -> `worksheet.project` -> `project.workspace` |
-### Tables That Do NOT Need `workspace_id` (5 tables)
+### Tables That Do NOT Need `workspace` (5 tables)
| Table | Reason |
|-------|--------|
@@ -159,7 +159,7 @@ These are children of Tier 2 tables. They have no `project` FK and no `workspace
| `workspace` | It IS the workspace |
| `principal` | Global identity layer (END_USER only, cross-workspace) |
-### Auth Token Tables -- Tied to Identity Layer (no `workspace_id`)
+### Auth Token Tables -- Tied to Identity Layer (no `workspace`)
| Table | Reason |
|-------|--------|
@@ -170,9 +170,9 @@ These are children of Tier 2 tables. They have no `project` FK and no `workspace
### Summary
-| Tier | Tables | `workspace_id` column | Workspace scoping mechanism |
+| Tier | Tables | `workspace` column | Workspace scoping mechanism |
|------|--------|-----------------------|----------------------------|
-| **Root** | 12 | Yes (10 existing + 2 new) | Direct `WHERE workspace_id = $1` |
+| **Root** | 12 | Yes (10 existing + 2 new) | Direct `WHERE workspace = $1` |
| **Project children** | 9 | No | `WHERE project = $1` (project already validated) |
| **Grandchildren** | 11 | No | Parent FK chain (parent validated by caller) |
| **Global** | 5 | No | Not workspace-scoped |
@@ -217,6 +217,6 @@ These are children of Tier 2 tables. They have no `project` FK and no `workspace
| Step | File | Description |
|------|------|-------------|
| 01 | [01.prepare-for-saas.md](./01.prepare-for-saas.md) | Preparatory refactors that can land independently: split `principal` table, fix workspace IAM policy resource field, migrate `serial` to `bigserial` |
-| 02 | [02.database-migration.md](./02.database-migration.md) | Create `workspace` table, add `workspace_id` to root tables, update unique indexes |
+| 02 | [02.database-migration.md](./02.database-migration.md) | Create `workspace` table, add `workspace` to root tables, update unique indexes |
| 03 | [03.application-layer.md](./03.application-layer.md) | Middleware, store/service changes to enforce workspace scoping on API requests |
| 04 | [04.runners-and-auth.md](./04.runners-and-auth.md) | Background runner workspace resolution, auth flow changes (login, workspace picker, JWT) |
diff --git a/docs/plans/saas/01.prepare-for-saas.md b/docs/plans/saas/01.prepare-for-saas.md
index 0cc3f9364d..5aabd8cc91 100644
--- a/docs/plans/saas/01.prepare-for-saas.md
+++ b/docs/plans/saas/01.prepare-for-saas.md
@@ -9,8 +9,8 @@ Preparatory refactors that can land independently on the current single-workspac
### Why
The `principal` table currently stores three entity types (`END_USER`, `SERVICE_ACCOUNT`, `WORKLOAD_IDENTITY`) differentiated by a `type` column. In SaaS mode:
-- `principal` (END_USER) becomes the **global identity** table -- no `workspace_id`, since a user can belong to multiple workspaces.
-- `service_account` and `workload_identity` become **workspace-scoped** tables with `workspace_id`.
+- `principal` (END_USER) becomes the **global identity** table -- no `workspace`, since a user can belong to multiple workspaces.
+- `service_account` and `workload_identity` become **workspace-scoped** tables with `workspace`.
The store layer already treats them as separate entities (`principal.go`, `principal_service_account.go`, `principal_workload_identity.go`), all querying the same table with `WHERE type = ?`. Splitting the table makes the schema match the code.
@@ -197,7 +197,7 @@ SELECT value->>'workspaceId' FROM setting WHERE name = 'WORKSPACE_PROFILE';
### Migration SQL
```sql
--- Set resource = 'workspaces/{workspace_id}' for all workspace-level policies
+-- Set resource = 'workspaces/{workspace}' for all workspace-level policies
UPDATE policy
SET resource = 'workspaces/' || (
SELECT value->>'workspaceId'
@@ -232,13 +232,13 @@ For SaaS, tables need different ID strategies depending on their scope:
1. **Project-scoped tables**: Keep `id` (convert to `bigserial`), auto-increment per project so IDs are human-readable within each project (e.g., project A: issue #1, #2, #3; project B: issue #1, #2, #3).
2. **Instance-scoped tables**: Keep `id`, auto-increment per instance.
3. **Cross-workspace tables**: Change `id` to `TEXT PRIMARY KEY` (uuid) since these have no natural scope boundary.
-4. **Workspace-scoped tables**: Add `workspace_id` column for multi-tenancy.
+4. **Workspace-scoped tables**: Add `workspace` column for multi-tenancy.
### Complete Table Migration Summary
| Table | Current PK | Scope | Migration |
|---|---|---|---|
-| **Top-level (no workspace_id)** | | | |
+| **Top-level (no workspace)** | | | |
| `principal` | `serial` | Global | Deprecate `id`, use `email` as unique key |
| `web_refresh_token` | `token_hash text` | User-scoped | None |
| `sheet_blob` | `sha256 bytea` | Content-addressed | None |
@@ -250,19 +250,19 @@ For SaaS, tables need different ID strategies depending on their scope:
| `revision` | `bigserial` | Instance | Per-instance auto-increment id, add FK to `instance(resource_id)` |
| `sync_history` | `bigserial` | Instance | Per-instance auto-increment id |
| `changelog` | `bigserial` | Instance | Per-instance auto-increment id |
-| **Workspace-scoped (need `workspace_id`)** | | | |
-| `idp` | `resource_id text` | Workspace | Add `workspace_id` |
-| `project` | `resource_id text` | Workspace | Add `workspace_id` |
-| `service_account` | `email text` | Workspace | Add `workspace_id` |
-| `workload_identity` | `email text` | Workspace | Add `workspace_id` |
-| `setting` | `name text` | Workspace | Add `workspace_id` |
-| `role` | `resource_id text` | Workspace | Add `workspace_id` |
-| `policy` | `(resource_type, resource, type)` | Workspace | Add `workspace_id` |
-| `user_group` | `id text` | Workspace | Add `workspace_id` |
-| `review_config` | `id text` | Workspace | Add `workspace_id` |
-| `oauth2_client` | `client_id text` | Workspace | Add `workspace_id` |
-| `oauth2_authorization_code` | `code text` | Workspace (via client) | Add `workspace_id` |
-| `oauth2_refresh_token` | `token_hash text` | Workspace (via client) | Add `workspace_id` |
+| **Workspace-scoped (need `workspace`)** | | | |
+| `idp` | `resource_id text` | Workspace | Add `workspace` |
+| `project` | `resource_id text` | Workspace | Add `workspace` |
+| `service_account` | `email text` | Workspace | Add `workspace` |
+| `workload_identity` | `email text` | Workspace | Add `workspace` |
+| `setting` | `name text` | Workspace | Add `workspace` |
+| `role` | `resource_id text` | Workspace | Add `workspace` |
+| `policy` | `(resource_type, resource, type)` | Workspace | Add `workspace` |
+| `user_group` | `id text` | Workspace | Add `workspace` |
+| `review_config` | `id text` | Workspace | Add `workspace` |
+| `oauth2_client` | `client_id text` | Workspace | Add `workspace` |
+| `oauth2_authorization_code` | `code text` | Workspace (via client) | Add `workspace` |
+| `oauth2_refresh_token` | `token_hash text` | Workspace (via client) | Add `workspace` |
| **Project-scoped (per-project auto-increment id)** | | | |
| `project_webhook` | `serial` | Project | Drop `id`, use `resource_id` as PK (no composite PK needed — `id` is unused, all lookups use `resource_id`) |
| `plan` | `bigserial` | Project | Per-project auto-increment id |
diff --git a/docs/plans/saas/02.database-migration.md b/docs/plans/saas/02.database-migration.md
index 64e5b278a2..02f1311e34 100644
--- a/docs/plans/saas/02.database-migration.md
+++ b/docs/plans/saas/02.database-migration.md
@@ -1,6 +1,6 @@
# Step 02: Database Migration
-Create the `workspace` table, add `workspace_id` to root tables, and update indexes. This step depends on Step 01 (principal split, bigserial migration) being completed first.
+Create the `workspace` table, add `workspace` to root tables, and update indexes. This step depends on Step 01 (principal split, bigserial migration) being completed first.
---
@@ -26,13 +26,13 @@ FROM setting
WHERE name = 'WORKSPACE_PROFILE';
```
-No `plan` column -- workspace plan/license info is already stored in the `setting` table (name = `'SYSTEM'`, value contains license). Once `setting` gets `workspace_id`, plan info is naturally workspace-scoped.
+No `plan` column -- workspace plan/license info is already stored in the `setting` table (name = `'SYSTEM'`, value contains license). Once `setting` gets `workspace`, plan info is naturally workspace-scoped.
---
-## 2. Add `workspace_id` to Root Tables
+## 2. Add `workspace` to Root Tables
-Add `workspace_id` to the 10 existing root-level tables. (`service_account` and `workload_identity` will get `workspace_id` added in this step too, since Step 01 creates them without it.)
+Add `workspace` to the 10 existing root-level tables. (`service_account` and `workload_identity` will get `workspace` added in this step too, since Step 01 creates them without it.)
For each table, the pattern is:
1. Add nullable column with FK
@@ -44,106 +44,106 @@ For each table, the pattern is:
-- All statements below use this subquery inline.
-- project
-ALTER TABLE project ADD COLUMN workspace_id text REFERENCES workspace(id);
-UPDATE project SET workspace_id = (SELECT id FROM workspace LIMIT 1);
-ALTER TABLE project ALTER COLUMN workspace_id SET NOT NULL;
+ALTER TABLE project ADD COLUMN workspace text REFERENCES workspace(resource_id);
+UPDATE project SET workspace = (SELECT id FROM workspace LIMIT 1);
+ALTER TABLE project ALTER COLUMN workspace SET NOT NULL;
-- instance
-ALTER TABLE instance ADD COLUMN workspace_id text REFERENCES workspace(id);
-UPDATE instance SET workspace_id = (SELECT id FROM workspace LIMIT 1);
-ALTER TABLE instance ALTER COLUMN workspace_id SET NOT NULL;
+ALTER TABLE instance ADD COLUMN workspace text REFERENCES workspace(resource_id);
+UPDATE instance SET workspace = (SELECT id FROM workspace LIMIT 1);
+ALTER TABLE instance ALTER COLUMN workspace SET NOT NULL;
-- setting
-ALTER TABLE setting ADD COLUMN workspace_id text REFERENCES workspace(id);
-UPDATE setting SET workspace_id = (SELECT id FROM workspace LIMIT 1);
-ALTER TABLE setting ALTER COLUMN workspace_id SET NOT NULL;
+ALTER TABLE setting ADD COLUMN workspace text REFERENCES workspace(resource_id);
+UPDATE setting SET workspace = (SELECT id FROM workspace LIMIT 1);
+ALTER TABLE setting ALTER COLUMN workspace SET NOT NULL;
-- policy
-ALTER TABLE policy ADD COLUMN workspace_id text REFERENCES workspace(id);
-UPDATE policy SET workspace_id = (SELECT id FROM workspace LIMIT 1);
-ALTER TABLE policy ALTER COLUMN workspace_id SET NOT NULL;
+ALTER TABLE policy ADD COLUMN workspace text REFERENCES workspace(resource_id);
+UPDATE policy SET workspace = (SELECT id FROM workspace LIMIT 1);
+ALTER TABLE policy ALTER COLUMN workspace SET NOT NULL;
-- role
-ALTER TABLE role ADD COLUMN workspace_id text REFERENCES workspace(id);
-UPDATE role SET workspace_id = (SELECT id FROM workspace LIMIT 1);
-ALTER TABLE role ALTER COLUMN workspace_id SET NOT NULL;
+ALTER TABLE role ADD COLUMN workspace text REFERENCES workspace(resource_id);
+UPDATE role SET workspace = (SELECT id FROM workspace LIMIT 1);
+ALTER TABLE role ALTER COLUMN workspace SET NOT NULL;
-- idp
-ALTER TABLE idp ADD COLUMN workspace_id text REFERENCES workspace(id);
-UPDATE idp SET workspace_id = (SELECT id FROM workspace LIMIT 1);
-ALTER TABLE idp ALTER COLUMN workspace_id SET NOT NULL;
+ALTER TABLE idp ADD COLUMN workspace text REFERENCES workspace(resource_id);
+UPDATE idp SET workspace = (SELECT id FROM workspace LIMIT 1);
+ALTER TABLE idp ALTER COLUMN workspace SET NOT NULL;
-- review_config
-ALTER TABLE review_config ADD COLUMN workspace_id text REFERENCES workspace(id);
-UPDATE review_config SET workspace_id = (SELECT id FROM workspace LIMIT 1);
-ALTER TABLE review_config ALTER COLUMN workspace_id SET NOT NULL;
+ALTER TABLE review_config ADD COLUMN workspace text REFERENCES workspace(resource_id);
+UPDATE review_config SET workspace = (SELECT id FROM workspace LIMIT 1);
+ALTER TABLE review_config ALTER COLUMN workspace SET NOT NULL;
-- user_group
-ALTER TABLE user_group ADD COLUMN workspace_id text REFERENCES workspace(id);
-UPDATE user_group SET workspace_id = (SELECT id FROM workspace LIMIT 1);
-ALTER TABLE user_group ALTER COLUMN workspace_id SET NOT NULL;
+ALTER TABLE user_group ADD COLUMN workspace text REFERENCES workspace(resource_id);
+UPDATE user_group SET workspace = (SELECT id FROM workspace LIMIT 1);
+ALTER TABLE user_group ALTER COLUMN workspace SET NOT NULL;
-- export_archive
-ALTER TABLE export_archive ADD COLUMN workspace_id text REFERENCES workspace(id);
-UPDATE export_archive SET workspace_id = (SELECT id FROM workspace LIMIT 1);
-ALTER TABLE export_archive ALTER COLUMN workspace_id SET NOT NULL;
+ALTER TABLE export_archive ADD COLUMN workspace text REFERENCES workspace(resource_id);
+UPDATE export_archive SET workspace = (SELECT id FROM workspace LIMIT 1);
+ALTER TABLE export_archive ALTER COLUMN workspace SET NOT NULL;
-- audit_log
-ALTER TABLE audit_log ADD COLUMN workspace_id text REFERENCES workspace(id);
-UPDATE audit_log SET workspace_id = (SELECT id FROM workspace LIMIT 1);
-ALTER TABLE audit_log ALTER COLUMN workspace_id SET NOT NULL;
-
--- service_account (created in Step 01 without workspace_id)
-ALTER TABLE service_account ADD COLUMN workspace_id text REFERENCES workspace(id);
-UPDATE service_account SET workspace_id = (SELECT id FROM workspace LIMIT 1);
-ALTER TABLE service_account ALTER COLUMN workspace_id SET NOT NULL;
-
--- workload_identity (created in Step 01 without workspace_id)
-ALTER TABLE workload_identity ADD COLUMN workspace_id text REFERENCES workspace(id);
-UPDATE workload_identity SET workspace_id = (SELECT id FROM workspace LIMIT 1);
-ALTER TABLE workload_identity ALTER COLUMN workspace_id SET NOT NULL;
+ALTER TABLE audit_log ADD COLUMN workspace text REFERENCES workspace(resource_id);
+UPDATE audit_log SET workspace = (SELECT id FROM workspace LIMIT 1);
+ALTER TABLE audit_log ALTER COLUMN workspace SET NOT NULL;
+
+-- service_account (created in Step 01 without workspace)
+ALTER TABLE service_account ADD COLUMN workspace text REFERENCES workspace(resource_id);
+UPDATE service_account SET workspace = (SELECT id FROM workspace LIMIT 1);
+ALTER TABLE service_account ALTER COLUMN workspace SET NOT NULL;
+
+-- workload_identity (created in Step 01 without workspace)
+ALTER TABLE workload_identity ADD COLUMN workspace text REFERENCES workspace(resource_id);
+UPDATE workload_identity SET workspace = (SELECT id FROM workspace LIMIT 1);
+ALTER TABLE workload_identity ALTER COLUMN workspace SET NOT NULL;
```
-Project-child tables (plan, issue, db, project_webhook, worksheet, db_group, release, access_grant, query_history) and grandchild tables do NOT get a `workspace_id` column -- they are scoped through their existing `project` FK chain.
+Project-child tables (plan, issue, db, project_webhook, worksheet, db_group, release, access_grant, query_history) and grandchild tables do NOT get a `workspace` column -- they are scoped through their existing `project` FK chain.
---
## 3. Update Unique Indexes
-Only root tables need index changes to include `workspace_id`:
+Only root tables need index changes to include `workspace`:
```sql
-- project
DROP INDEX idx_project_unique_resource_id;
-CREATE UNIQUE INDEX idx_project_unique_resource_id ON project(workspace_id, resource_id);
+CREATE UNIQUE INDEX idx_project_unique_resource_id ON project(workspace, resource_id);
-- instance
DROP INDEX idx_instance_unique_resource_id;
-CREATE UNIQUE INDEX idx_instance_unique_resource_id ON instance(workspace_id, resource_id);
+CREATE UNIQUE INDEX idx_instance_unique_resource_id ON instance(workspace, resource_id);
-- principal: no change needed (global identity, email unique globally)
-- setting
DROP INDEX idx_setting_unique_name;
-CREATE UNIQUE INDEX idx_setting_unique_name ON setting(workspace_id, name);
+CREATE UNIQUE INDEX idx_setting_unique_name ON setting(workspace, name);
-- role
DROP INDEX idx_role_unique_resource_id;
-CREATE UNIQUE INDEX idx_role_unique_resource_id ON role(workspace_id, resource_id);
+CREATE UNIQUE INDEX idx_role_unique_resource_id ON role(workspace, resource_id);
-- idp
DROP INDEX idx_idp_unique_resource_id;
-CREATE UNIQUE INDEX idx_idp_unique_resource_id ON idp(workspace_id, resource_id);
+CREATE UNIQUE INDEX idx_idp_unique_resource_id ON idp(workspace, resource_id);
-- user_group
DROP INDEX idx_user_group_unique_email;
-CREATE UNIQUE INDEX idx_user_group_unique_email ON user_group(workspace_id, email) WHERE email IS NOT NULL;
+CREATE UNIQUE INDEX idx_user_group_unique_email ON user_group(workspace, email) WHERE email IS NOT NULL;
-- service_account
-CREATE UNIQUE INDEX idx_service_account_unique_workspace_email ON service_account(workspace_id, email);
+CREATE UNIQUE INDEX idx_service_account_unique_workspace_email ON service_account(workspace, email);
-- workload_identity
-CREATE UNIQUE INDEX idx_workload_identity_unique_workspace_email ON workload_identity(workspace_id, email);
+CREATE UNIQUE INDEX idx_workload_identity_unique_workspace_email ON workload_identity(workspace, email);
```
Child table unique indexes remain unchanged -- their uniqueness is naturally scoped because their parent references (e.g., `plan.project`, `db.instance`) are already workspace-unique:
@@ -163,13 +163,13 @@ Child table unique indexes remain unchanged -- their uniqueness is naturally sco
## 4. Add Workspace Query Performance Indexes
```sql
-CREATE INDEX idx_project_workspace ON project(workspace_id);
-CREATE INDEX idx_instance_workspace ON instance(workspace_id);
-CREATE INDEX idx_setting_workspace ON setting(workspace_id);
-CREATE INDEX idx_policy_workspace ON policy(workspace_id);
-CREATE INDEX idx_audit_log_workspace ON audit_log(workspace_id);
-CREATE INDEX idx_service_account_workspace ON service_account(workspace_id);
-CREATE INDEX idx_workload_identity_workspace ON workload_identity(workspace_id);
+CREATE INDEX idx_project_workspace ON project(workspace);
+CREATE INDEX idx_instance_workspace ON instance(workspace);
+CREATE INDEX idx_setting_workspace ON setting(workspace);
+CREATE INDEX idx_policy_workspace ON policy(workspace);
+CREATE INDEX idx_audit_log_workspace ON audit_log(workspace);
+CREATE INDEX idx_service_account_workspace ON service_account(workspace);
+CREATE INDEX idx_workload_identity_workspace ON workload_identity(workspace);
```
---
@@ -178,4 +178,4 @@ CREATE INDEX idx_workload_identity_workspace ON workload_identity(workspace_id);
Update `TestLatestVersion` in `backend/migrator/migrator_test.go` after adding new migration files.
-Update `backend/migrator/migration/LATEST.sql` to reflect the final schema state with the `workspace` table and `workspace_id` columns.
+Update `backend/migrator/migration/LATEST.sql` to reflect the final schema state with the `workspace` table and `workspace` columns.
diff --git a/docs/plans/saas/03.application-layer.md b/docs/plans/saas/03.application-layer.md
index d83dbb8e33..89766435be 100644
--- a/docs/plans/saas/03.application-layer.md
+++ b/docs/plans/saas/03.application-layer.md
@@ -6,7 +6,7 @@ Update middleware, store, and service layers to enforce workspace scoping on all
## 1. Workspace Context Middleware
-Extract `workspace_id` from the JWT and inject it into the request context. Every authenticated request carries workspace context.
+Extract `workspace` from the JWT and inject it into the request context. Every authenticated request carries workspace context.
```go
type workspaceIDKey struct{}
@@ -31,26 +31,26 @@ func WorkspaceIDFromContext(ctx context.Context) string {
## 2. Store Layer: Root Table Queries
-All root table queries (12 tables) add `WHERE workspace_id = $1`. This is the primary isolation boundary.
+All root table queries (12 tables) add `WHERE workspace = $1`. This is the primary isolation boundary.
### Pattern for Root Tables
```go
-// GET: add workspace_id to WHERE clause
+// GET: add workspace to WHERE clause
func (s *Store) GetProject(ctx context.Context, workspaceID, resourceID string) (*ProjectMessage, error) {
- query := "SELECT ... FROM project WHERE workspace_id = $1 AND resource_id = $2"
+ query := "SELECT ... FROM project WHERE workspace = $1 AND resource_id = $2"
// ...
}
-// LIST: add workspace_id to WHERE clause
+// LIST: add workspace to WHERE clause
func (s *Store) ListInstances(ctx context.Context, workspaceID string, find *FindInstanceMessage) ([]*InstanceMessage, error) {
- where := qb.Q().Space("workspace_id = ?", workspaceID)
+ where := qb.Q().Space("workspace = ?", workspaceID)
// ... existing filters ...
}
-// INSERT: include workspace_id
+// INSERT: include workspace
func (s *Store) CreateProject(ctx context.Context, workspaceID string, create *ProjectMessage) (*ProjectMessage, error) {
- query := "INSERT INTO project (workspace_id, resource_id, name, ...) VALUES ($1, $2, $3, ...)"
+ query := "INSERT INTO project (workspace, resource_id, name, ...) VALUES ($1, $2, $3, ...)"
// ...
}
```
@@ -74,13 +74,13 @@ func (s *Store) CreateProject(ctx context.Context, workspaceID string, create *P
### `principal` Table: NO Workspace Filter
-`principal` is the global identity table. Queries like `GetUserByEmail`, `GetUserByID` do NOT add `workspace_id` -- a user identity is cross-workspace.
+`principal` is the global identity table. Queries like `GetUserByEmail`, `GetUserByID` do NOT add `workspace` -- a user identity is cross-workspace.
---
## 3. Store Layer: Project-Child Table Queries
-These tables (plan, issue, db, project_webhook, worksheet, db_group, release, access_grant, query_history) filter by `project` FK. **No `workspace_id` changes needed in the store layer** -- they continue to use `WHERE project = $1`.
+These tables (plan, issue, db, project_webhook, worksheet, db_group, release, access_grant, query_history) filter by `project` FK. **No `workspace` changes needed in the store layer** -- they continue to use `WHERE project = $1`.
The security invariant is: the `project` value passed to the store has already been validated as belonging to the current workspace (see Service Layer below).
@@ -148,10 +148,10 @@ func (s *RolloutService) GetTaskRun(ctx context.Context, req *v1pb.GetTaskRunReq
Critical: every API endpoint that returns or mutates workspace-scoped data MUST enforce workspace isolation. Audit every endpoint against this checklist:
-- [ ] **Root table endpoints**: store query includes `WHERE workspace_id = $1`
+- [ ] **Root table endpoints**: store query includes `WHERE workspace = $1`
- [ ] **Project-child endpoints**: project is validated against workspace before querying children
- [ ] **Grandchild endpoints**: parent chain is validated (project -> plan/issue/db -> child)
-- [ ] **Cross-table joins**: any JOIN that touches root tables includes workspace_id condition
+- [ ] **Cross-table joins**: any JOIN that touches root tables includes workspace condition
- [ ] **Batch operations**: bulk queries (e.g., `BatchGetUsersByEmails`) handle cross-workspace correctly
- [ ] **Cache invalidation**: caches keyed by resource name include workspace context to prevent cross-workspace leaks
- [ ] **No direct PK lookups without parent validation**: queries like `GetPlan(ctx, &FindPlanMessage{UID: &planID})` must not be reachable from an API handler without first validating the parent project belongs to the workspace
diff --git a/docs/plans/saas/04.runners-and-auth.md b/docs/plans/saas/04.runners-and-auth.md
index 19d57911d8..47f605cb65 100644
--- a/docs/plans/saas/04.runners-and-auth.md
+++ b/docs/plans/saas/04.runners-and-auth.md
@@ -1,6 +1,4 @@
-# Step 04: Background Runners and Auth Flow
-
-Update background runners to handle multi-workspace task processing, and implement the new auth flow with workspace selection. This step depends on Step 03 (application layer) being completed.
+# Step 04: Background Runners, Auth Flow, and Member Management
---
@@ -8,167 +6,153 @@ Update background runners to handle multi-workspace task processing, and impleme
Runners poll for pending tasks across ALL workspaces with a single query (no workspace filter). They resolve workspace context from the task's parent chain when processing.
-### Current Architecture
-
-Runners are in `backend/runner/` and include:
-- `approval/` -- approval workflow processing
-- `relay/` -- external approval relay
-- `taskrun/` -- task execution scheduler
-- `schemasync/` -- database schema sync
-- `slowquerysync/` -- slow query log sync
-- `mail/` -- email notifications
-- `metricreport/` -- metric reporting
-- `plancheck/` -- plan check execution
-
-### How Runners Work in SaaS Mode
-
-```go
-func (r *Scheduler) Run(ctx context.Context) {
- ticker := time.NewTicker(5 * time.Second)
- for {
- select {
- case <-ticker.C:
- // No workspace filter -- returns pending task runs across all workspaces
- tasks, _ := r.store.ListPendingTaskRuns(ctx)
- for _, task := range tasks {
- go r.processTask(ctx, task)
- }
- }
- }
-}
-
-func (r *Scheduler) processTask(ctx context.Context, taskRun *TaskRun) {
- // Resolve workspace through parent chain:
- // task_run -> task -> plan -> project -> workspace_id
- task, _ := r.store.GetTask(ctx, taskRun.TaskID)
- plan, _ := r.store.GetPlan(ctx, &FindPlanMessage{UID: &task.PlanID})
- project, _ := r.store.GetProjectByResourceID(ctx, plan.ProjectID)
- workspaceID := project.WorkspaceID
-
- // Use workspaceID for workspace-specific operations
- // (e.g., loading instance credentials, checking workspace settings)
-}
-```
-
-### Runner-Specific Considerations
+### Runner-Specific Workspace Resolution
| Runner | Workspace resolution | Notes |
|--------|---------------------|-------|
-| `taskrun/` | task_run -> task -> plan -> project -> workspace_id | Main execution pipeline |
-| `plancheck/` | plan_check_run -> plan -> project -> workspace_id | Plan validation |
-| `approval/` | issue -> project -> workspace_id | Approval workflows |
-| `relay/` | issue -> project -> workspace_id | External approval relay |
-| `schemasync/` | instance -> workspace_id (direct) | Instance is a root table |
-| `slowquerysync/` | instance -> workspace_id (direct) | Instance is a root table |
+| `taskrun/` | task_run → task → plan → project → workspace | Main execution pipeline |
+| `plancheck/` | plan_check_run → plan → project → workspace | Plan validation |
+| `approval/` | issue → project → workspace | Approval workflows |
+| `schemasync/` | instance → workspace (direct) | Instance is a root table |
| `mail/` | Varies by notification source | Resolve from the entity being notified about |
-| `metricreport/` | Reports across all workspaces | May aggregate per-workspace or globally |
-### Optimization: Denormalize `workspace_id`
+### Cross-Workspace Store Methods
-For frequently polled runner queries, consider denormalizing `workspace_id` onto hot tables to avoid the join chain on every poll cycle:
-
-```sql
--- Optional: add workspace_id to task for faster runner lookups
-ALTER TABLE task ADD COLUMN workspace_id text REFERENCES workspace(id);
--- Backfill from parent chain: task -> plan -> project -> workspace_id
-UPDATE task SET workspace_id = (
- SELECT p.workspace_id FROM project p
- JOIN plan pl ON pl.project = p.resource_id
- WHERE pl.id = task.plan_id
-);
-```
-
-This is an optimization, not a requirement. Start without it and add if runner query latency becomes an issue.
+Located in `backend/store/runner_queries.go`:
+- `GetProjectByResourceID` — by globally unique PK, no workspace filter
+- `GetInstanceByResourceID` — by globally unique PK, no workspace filter
+- `ListAllInstances` — returns all instances across workspaces
+- `DeleteExpiredExportArchivesAll` — cleanup across all workspaces
---
-## 2. Auth Flow Changes
+## 2. Auth Flow
-### Current Flow (Per-Workspace Container)
+### Login Flow
-1. User hits `{id}.bytebase.com` -> single workspace container
-2. Login with email/password or SSO
-3. JWT scoped to workspace implicitly (one workspace per container)
-
-### SaaS Flow (Single Container)
-
-1. User hits `console.bytebase.com`
-2. Login (password/SSO) -> authenticates against global `principal` table (END_USER only)
-3. Query workspace membership: find all workspaces where the user appears in `policy` (IAM binding with `resource_type = 'WORKSPACE'`)
-4. If user has 1 workspace -> auto-redirect
-5. If user has N workspaces -> workspace picker UI
-6. If user has 0 workspaces -> create workspace or accept invitation
-7. After workspace selected -> JWT includes both `user_id` (principal.id) and `workspace_id`
-8. All subsequent requests scoped to that workspace
+1. User authenticates (password/SSO/MFA) → global `principal` table
+2. Workspace resolved:
+ - Prefers `user.Profile.LastLoginWorkspace` if still valid
+ - Falls back to first workspace from IAM membership
+ - Self-hosted includes `allUsers` workspaces; SaaS requires explicit membership
+3. JWT generated with `workspace_id` claim
+4. Access token set as HTTP-only cookie (expires 30s after JWT for refresh support)
+5. Refresh token stored in `web_refresh_token` table
### JWT Structure
```json
{
- "sub": "users/[email protected]",
- "user_id": 123,
+ "sub": "[email protected]",
"workspace_id": "ws-abc123",
+ "aud": ["bb.user.access"],
+ "iss": "bytebase",
"iat": 1709654400,
"exp": 1709740800
}
```
+### Token Refresh
+
+1. Access token cookie outlives JWT by 30 seconds
+2. On 401, frontend calls `Refresh()` with refresh token cookie
+3. `Refresh()` extracts workspace from the expired JWT in the access token cookie (signature-verified)
+4. Verifies user still a member of the workspace
+5. Issues new access token + rotates refresh token (preserving absolute session expiry)
+
+### Workspace Switching
+
+`SwitchWorkspace` RPC (`POST /v1/auth:switchWorkspace`):
+
+1. Validates user is END_USER (not service account/OAuth2 token)
+2. Verifies membership in target workspace (direct or via group)
+3. Validates workspace sign-in policies (domain restrictions)
+4. Checks MFA if target workspace requires it (with lockout protection)
+5. Consumes old refresh token, preserves its absolute expiry
+6. Issues new JWT + cookies for the target workspace
+7. Frontend reloads via `BroadcastChannel` (all tabs switch together)
+
### Workspace Discovery Query
-Find workspaces a user belongs to by scanning IAM policies:
+Finds workspaces where a user is a member — directly, via group, or via `allUsers`:
```sql
--- Find all workspaces where [email protected] is a member
-SELECT DISTINCT w.id, w.resource_id, w.name
+SELECT DISTINCT w.resource_id, w.name
FROM workspace w
-JOIN policy p ON p.workspace_id = w.id
+JOIN policy p ON p.workspace = w.resource_id
WHERE p.resource_type = 'WORKSPACE'
AND p.type = 'IAM'
+ AND w.deleted = FALSE
AND EXISTS (
- SELECT 1
- FROM jsonb_array_elements(p.payload->'bindings') AS binding,
- jsonb_array_elements_text(binding->'members') AS member
- WHERE member = 'users/[email protected]'
+ SELECT 1
+ FROM jsonb_array_elements(p.payload->'bindings') AS binding,
+ jsonb_array_elements_text(binding->'members') AS member
+ WHERE member = 'users/{email}'
+ OR (member LIKE 'groups/%' AND EXISTS (
+ SELECT 1 FROM user_group ug,
+ jsonb_array_elements(ug.payload->'members') AS gm
+ WHERE ug.workspace = w.resource_id
+ AND 'groups/' || ug.email = member
+ AND gm->>'member' = 'users/{email}'
+ ))
+ OR member = 'allUsers' -- self-hosted only
)
- AND w.deleted = FALSE;
```
### Service Accounts and Workload Identities
-These are workspace-scoped in their own tables (`service_account`, `workload_identity`), each with a `workspace_id` column. They authenticate directly within workspace context (API key or token exchange) -- no workspace picker needed.
+Workspace-scoped via their own tables (`service_account`, `workload_identity`), each with a `workspace` column. They authenticate directly within workspace context — no workspace picker needed.
-### Auth Token Tables
+---
-`web_refresh_token`, `oauth2_client`, `oauth2_authorization_code`, `oauth2_refresh_token` remain tied to the `principal` (identity) layer since login is cross-workspace. No `workspace_id` needed on these tables.
+## 3. Member Management
----
+### Design: Google Cloud IAM Model
-## 3. Workspace Switching
+Following Google Cloud's approach — no invitation/pending state. Members are managed by updating the workspace IAM policy.
-After initial login and workspace selection, users may need to switch workspaces without re-authenticating.
+| Action | How |
+|--------|-----|
+| **Add member** | Add email to workspace IAM binding with a role |
+| **Remove member** | Remove email from all workspace IAM bindings |
+| **Change role** | Update the member's IAM bindings |
-### Approach
+If the email doesn't have a Bytebase account yet, the IAM binding still exists. When the user signs up later, `Signup` finds the workspace via IAM membership and auto-joins.
-1. User clicks "Switch Workspace" in the UI
-2. Frontend calls a workspace-switch endpoint with the target `workspace_id`
-3. Backend validates user is a member of the target workspace (check IAM policy)
-4. Backend issues a new JWT with the updated `workspace_id`
-5. Frontend reloads with new workspace context
+### SaaS vs Self-Hosted
-```go
-func (s *AuthService) SwitchWorkspace(ctx context.Context, req *SwitchWorkspaceRequest) (*SwitchWorkspaceResponse, error) {
- userID := UserIDFromContext(ctx)
+| Behavior | Self-Hosted | SaaS |
+|----------|-------------|------|
+| **Add member** | `CreateUser` (admin creates account) OR add email to IAM | Add email to IAM only (no `CreateUser`) |
+| **Principal creation** | Admin can create via API | Users self-register via `Signup` only |
+| **allUsers binding** | Allowed (grants access to all principals) | Blocked |
+| **Member types in IAM** | `users/{email}`, `groups/{email}`, `allUsers` | `users/{email}`, `groups/{email}` |
- // Validate user is a member of the target workspace
- iamPolicy, err := s.store.GetWorkspaceIamPolicy(ctx, req.WorkspaceID)
- if err != nil { return nil, err }
+### Member Resolution (Auth Layer)
- if !isMember(iamPolicy, userID) {
- return nil, status.Errorf(codes.PermissionDenied, "not a member of workspace %s", req.WorkspaceID)
- }
+When verifying workspace membership (`verifyWorkspaceMembership`), the auth interceptor checks:
- // Issue new JWT with updated workspace_id
- token, err := s.issueJWT(userID, req.WorkspaceID)
- // ...
-}
-```
+1. **Direct membership**: `member == 'users/{email}'`
+2. **Group membership**: `member == 'groups/{groupEmail}'` → expand via `GetGroupMembersSnapshot`
+3. **allUsers** (self-hosted only): `member == 'allUsers'`
+
+### Group Membership Expansion
+
+Groups are stored in `user_group` table with members in `payload.members[].member` (format: `users/{email}`).
+
+When a group `groups/{groupEmail}` appears in an IAM binding:
+- Permission checks (`iam/manager.go`): expands via `GetGroupMembersSnapshot` (cached)
+- Workspace discovery (`store/workspace.go`): expands via SQL JOIN to `user_group` table
+- Auth verification (`api/auth/auth.go`): expands via `GetGroupMembersSnapshot`
+
+### Frontend UX
+
+**SaaS mode**:
+- "Members" page: shows workspace members from IAM policy, allows adding emails with role selection
+- "Users" section: hidden (principals are global, not workspace-managed)
+- "Groups" section: shown (workspace-scoped)
+
+**Self-hosted mode**:
+- "Members" page: shows members, allows adding existing users or creating new ones
+- "Users" section: shown (admin can manage principals)
+- "Groups" section: shown
diff --git a/docs/plans/saas/05.progress.md b/docs/plans/saas/05.progress.md
index 1abf1f31b9..33e1117515 100644
--- a/docs/plans/saas/05.progress.md
+++ b/docs/plans/saas/05.progress.md
@@ -25,7 +25,7 @@ Current status of the workspace isolation implementation. **185+ files changed,
### Store Layer
- [x] **All root tables enforce workspace on CRUD** (INSERT, SELECT, UPDATE, DELETE)
-- [x] **`workspace.go`**: `GetWorkspaceID()` returns `("", nil)` when no workspace exists, `FindWorkspacesByMemberEmail()`, `FindWorkspaceIDByMemberEmail()`, `CreateWorkspace()` with proto-based settings/policy
+- [x] **`workspace.go`**: `GetWorkspaceID()` returns `("", nil)` when no workspace exists, `ListWorkspacesByEmail()`, `FindWorkspace()`, `CreateWorkspace()` with proto-based settings/policy
- [x] **`runner_queries.go`**: Cross-workspace methods (`GetProjectByResourceID`, `GetInstanceByResourceID`, `ListAllInstances`, `DeleteExpiredExportArchivesAll`)
- [x] **`account.go`**: `AccountMessage` + `GetAccountByEmail()` for auth layer
- [x] **`GetServerConfig()` / `GetAuthSecret()`** — reads from `server_config` table
@@ -40,7 +40,7 @@ Current status of the workspace isolation implementation. **185+ files changed,
- [x] **Workspace in JWT claims** (`WorkspaceID` field)
- [x] **Auth middleware** injects workspace into context, verifies membership
-- [x] **Login workspace resolution** via `FindWorkspacesByMemberEmail` (IAM policy). Workspace resolved early in Login flow, passed as parameter (not via context).
+- [x] **Login workspace resolution** via `ListWorkspacesByEmail` (IAM policy). Workspace resolved early in Login flow, passed as parameter (not via context).
- [x] **`Signup` API** (`POST /v1/auth/signup`, `allow_without_credential`) — Creates principal + workspace. Self-hosted: joins existing workspace or creates if none exists. SaaS: creates new workspace per user.
- [x] **`CreateUser` refactored** — Admin-only (`bb.users.create` permission), self-hosted only. SaaS blocked.
- [x] **Login lockout** — `countRecentLoginFailures` searches audit logs cross-workspace (per-email rate limit)
@@ -138,11 +138,21 @@ Every public store method was audited:
### Remaining
-- [ ] **Workspace switching endpoint** — Issue new JWT with different `workspace_id` (login auto-selects the first workspace; users switch after login)
-- [ ] **Cross-workspace user management** — List workspaces for a user
-- [ ] **Workspace admin panel** — Manage workspace settings, members
+#### High Priority
+
+- [ ] **Workspace switching** — Issue new JWT with different `workspace_id` (login auto-selects the first workspace; users switch after login)
+- [ ] Invite users
+- [x] ListWorkspacesByEmail must expand groups
+- [ ] User count limit in the SaaS mode
+
+#### Medium Priority
+
- [ ] **Schema sync perf** — when database count grows, consider querying per instance or adding `InstanceIDs` batch filter to `FindDatabaseMessage`
+#### Low Priority
+
+- [ ] **Workspace admin panel** — Manage workspace settings, members
+
---
## Impact on Existing Self-hosted Customers
@@ -171,7 +181,7 @@ Every public store method was audited:
3. **Three access patterns for store queries**:
- **API layer**: `common.GetWorkspaceIDFromContext(ctx)` from JWT
- **Runners**: Cross-workspace methods
- - **Login/startup**: `store.GetWorkspaceID(ctx)` or `FindWorkspacesByMemberEmail`
+ - **Login/startup**: `store.GetWorkspaceID(ctx)` or `ListWorkspacesByEmail`
4. **OAuth2 child tables** don't need workspace — scoped through `client_id` FK.