feature: suborg scope support [ENG-4125]

[gupta-piyush19]

Description 📣

• Adds sub-org scope to the user token
• Adds a new scopeOrgId column to the IdentityAccessToken table
• Adds an optional subOrganizationName to the machine identity auth endpoints
• Fixes the styling of the sub-org tab

Type ✨

• Bug fix
• New feature
• Improvement
• Breaking change
• Documentation

Tests 🛠️

• Navigation between the org and sub-org should work fine
• Sub-org navigation should be audit-logged
• The user cookie token should include the subOrganizationId, please verify this on jwt.io
• New machine identity tokens should have the scopeOrgId

# Here's some code block to paste some code snippets

---

• I have read the contributing guide, agreed and acknowledged the code of conduct. 📝

[maidul98]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds sub-organization scope support to user tokens and machine identity authentication. Users can now scope their session to specific sub-organizations, and machine identities can authenticate with a subOrganizationName parameter to scope their access tokens.

Key Changes:

• Added scopeOrgId column to IdentityAccessToken table to store the organization scope
• Updated all identity auth methods (Universal Auth, Token Auth, AWS, GCP, Azure, Kubernetes, etc.) to accept optional subOrganizationName parameter
• Modified login flow to support subOrganizationId alongside organizationId
• Frontend navigation updated to properly handle sub-org selection via API calls instead of query parameters
• Token validation updated to use scopeOrgId with fallback to identity's organization

Critical Issues Found:

• Universal Auth login endpoint passes positional parameters instead of object to service method - will break all universal auth logins
• Database migration adds NOT NULL column without default value - will fail on existing data
• Sub-organization validation logic may allow users to access sub-orgs outside their root organization

Security Concerns:

• Missing validation in selectSubOrganization to verify the sub-org belongs to user's authenticated root organization
• Identity auth methods should validate that requested sub-org is under the identity's root organization before allowing scope change

Confidence Score: 1/5

• This PR contains critical bugs that will break production authentication flows and database migrations
• Score reflects two critical runtime errors: (1) universal auth login will fail immediately due to function signature mismatch, and (2) database migration will fail on tables with existing data. Additionally, security validation gaps could allow unauthorized cross-organization access.
• Critical: backend/src/server/routes/v1/identity-universal-auth-router.ts (runtime error), backend/src/db/migrations/20251127192155_adds-scope-org-id-to-identity-access-tokens.ts (migration failure). High priority: backend/src/services/identity-ua/identity-ua-service.ts, backend/src/services/auth/auth-login-service.ts (security validation)

Important Files Changed

File Analysis

Filename	Score	Overview
backend/src/db/migrations/20251127192155_adds-scope-org-id-to-identity-access-tokens.ts	1/5	Migration adds NOT NULL column without default, will fail on existing data. Schema defines field as nullable but migration uses notNullable().
backend/src/server/routes/v1/identity-universal-auth-router.ts	1/5	Critical: login function called with positional args instead of object parameter, will cause runtime error on all universal auth logins.
backend/src/services/identity-ua/identity-ua-service.ts	2/5	Adds sub-org scope support to universal auth. Logic issue in sub-org validation may allow cross-org access. scopeOrgId correctly stored in token.
backend/src/services/auth/auth-login-service.ts	2/5	New selectSubOrganization function adds sub-org login flow. Missing validation that sub-org belongs to user's authenticated root organization.
backend/src/services/identity-access-token/identity-access-token-service.ts	4/5	Token validation updated to use scopeOrgId with fallback to identityOrgId. Correctly verifies identity membership in scoped organization.
backend/src/services/auth-token/auth-token-service.ts	4/5	JWT validation correctly handles subOrganizationId in tokens. Validates membership and enforces auth policies for sub-orgs.
frontend/src/context/OrganizationContext/OrganizationContext.tsx	4/5	Simplified sub-org detection logic using rootOrgId comparison. Clean refactor removing query param dependency.
frontend/src/layouts/OrganizationLayout/components/NavBar/Navbar.tsx	4/5	Navigation properly handles sub-org selection via API calls. Correctly distinguishes organizationId vs subOrganizationId parameters.
backend/src/server/routes/v3/login-router.ts	3/5	Login endpoint updated to accept subOrganizationId. Routes to correct service method but uses either/or pattern for orgId/subOrgId.

[greptile-apps]

_{71 files reviewed, 4 comments}

_{Edit Code Review Agent Settings | Greptile}

[scott-ray-wilson]

Three thoughts on UX:

1. with the current UI as is we could always show the "Add Sub-Organization" button, even if you're in a sub-org, and from that modal, before firing off the mutation, if you are not in the root-org we do a token exchange and then call the mutation. That way the create sub-org experience is always accessible

2. I'm thinking we should make the token exchange based off the orgId in the url, automatically triggering when changing pages so that way back button and links always get the appropriate scope access token

3. On project access control, settings and audit logs, can you update the "Are you looking for organization _____?" to say sub-org if in a sub-org project and also add these back links to sub-organization access control, settings and audit logs to bring you to the parent org? (These should not show on the root org)

[scott-ray-wilson]

couple of comments

All good from private conversation