Skip to content

[EPIC]: Complete Enterprise Multi-Tenancy System with Team-Based Resource Scoping #860

New issue
New issue
Closed
Feature
#862
Closed
[EPIC]: Complete Enterprise Multi-Tenancy System with Team-Based Resource Scoping#860
Feature
#862
Assignees
crivetimihai
Labels
enhancementNew feature or requestsecurityImproves security
Milestone
Release 0.7.0
@crivetimihai

Description

@crivetimihai
crivetimihai
opened on Sep 1, 2025

🏢 Complete Enterprise Multi-Tenancy System

🧭 Epic Overview

Goal: Complete enterprise-grade multi-tenancy system with team-based resource scoping, email authentication, SSO integration, and comprehensive RBAC.

Impact: Transforms MCP Gateway from single-tenant to full enterprise multi-tenant platform with secure resource isolation, team collaboration, and enterprise SSO integration.

Status: 🟢 IMPLEMENTED - Production-ready multi-tenancy system with comprehensive documentation.

🎯 Core Features Implemented

🔐 Authentication & Authorization

👥 Team Management System

  • ✅ Personal Teams Auto-Creation - Every user gets a personal team upon registration
  • ✅ Multi-Team Membership - Users can belong to multiple teams with different roles
  • ✅ Team Invitation System - Email-based invitations with secure tokens and expiration
  • ✅ Team Visibility Controls - Private/Public teams with proper discovery mechanisms
  • ✅ Team Roles & Permissions - Owner/Member roles with granular permission enforcement

🔒 Resource Scoping & Visibility

  • ✅ Three-Tier Resource Visibility:
    • Private: Owner-only access
    • Team: Team member access
    • Public: Cross-team access
  • ✅ Applied to All Resource Types: Tools, Servers, Resources, Prompts, A2A Agents
  • ✅ Team-Scoped API Endpoints with proper access validation
  • ✅ Cross-Team Resource Discovery for public resources

🏗️ Platform Administration

  • ✅ Platform Admin Role separate from team roles
  • ✅ Domain-Based Auto-Assignment via SSO (SSO_AUTO_ADMIN_DOMAINS)
  • ✅ Enterprise Domain Trust (SSO_TRUSTED_DOMAINS)
  • ✅ Admin Team Management - view/manage all teams except personal teams

🗄️ Database & Infrastructure

  • ✅ Multi-Tenant Database Schema with proper indexing
  • ✅ Team-Based Query Filtering for performance
  • ✅ Migration Strategy from single-tenant to multi-tenant
  • ✅ Complete API Redesign with team-aware endpoints

🔗 Related Issues & Dependencies

Closes These Issues:

Builds Upon:

Future Extensions:

📐 System Architecture

graph TB
    subgraph "Authentication Layer"
        Email[Email Authentication<br/>Argon2id Hashing]
        SSO[Multi-Provider SSO<br/>GitHub, Google, IBM Verify]
        JWT[Enhanced JWT Tokens<br/>Team Context + Scoped Access]
    end

    subgraph "Team Management"
        PersonalTeams[Personal Teams<br/>Auto-Creation]
        MultiTeam[Multi-Team Membership<br/>Owner/Member Roles]
        Invitations[Email Invitations<br/>Token-Based Workflow]
        TeamVisibility[Team Visibility<br/>Private/Public Discovery]
    end

    subgraph "Resource Scoping"
        ResourceVis[Three-Tier Visibility<br/>Private/Team/Public]
        TeamAPI[Team-Scoped APIs<br/>All Resource Types]
        CrossTeam[Cross-Team Access<br/>Public Resources]
    end

    subgraph "Platform Administration"
        PlatformAdmin[Platform Admin Role<br/>System-Wide Access]
        DomainMap[Domain-Based Assignment<br/>Auto-Admin via SSO]
        TeamMgmt[Team Management<br/>Admin Oversight]
    end

    subgraph "Database Layer"
        Schema[Multi-Tenant Schema<br/>EmailUser, EmailTeam, etc.]
        Indexes[Team-Based Indexing<br/>Query Performance]
        Migration[Migration Strategy<br/>Single→Multi Tenant]
    end

    Email --> JWT
    SSO --> JWT
    JWT --> MultiTeam
    PersonalTeams --> MultiTeam
    MultiTeam --> ResourceVis
    Invitations --> MultiTeam
    TeamVisibility --> MultiTeam
    ResourceVis --> TeamAPI
    TeamAPI --> CrossTeam
    PlatformAdmin --> TeamMgmt
    DomainMap --> PlatformAdmin
    Schema --> Indexes
    Indexes --> Migration
Loading

🎛️ Configuration

Core Multi-Tenancy Settings

# Team Management
AUTO_CREATE_PERSONAL_TEAMS=true
PERSONAL_TEAM_PREFIX=personal
MAX_TEAMS_PER_USER=50
MAX_MEMBERS_PER_TEAM=100

# Invitations
INVITATION_EXPIRY_DAYS=7
REQUIRE_EMAIL_VERIFICATION_FOR_INVITES=true

# Platform Administration  
[email protected]
PLATFORM_ADMIN_PASSWORD=changeme
PLATFORM_ADMIN_FULL_NAME="Platform Administrator"

# SSO & Domain Trust
SSO_ENABLED=true
SSO_TRUSTED_DOMAINS=["company.com","trusted-partner.com"]
SSO_AUTO_ADMIN_DOMAINS=["company.com"]
SSO_AUTO_CREATE_USERS=true
SSO_PRESERVE_ADMIN_AUTH=true

Authentication Settings

# Email Authentication
EMAIL_AUTH_ENABLED=true
ARGON2ID_TIME_COST=3
ARGON2ID_MEMORY_COST=65536
ARGON2ID_PARALLELISM=1

# Password Policies
PASSWORD_MIN_LENGTH=8
PASSWORD_REQUIRE_UPPERCASE=false
PASSWORD_REQUIRE_NUMBERS=false
PASSWORD_REQUIRE_SPECIAL=false

# JWT Configuration
JWT_SECRET_KEY=your-secret-key
JWT_EXPIRATION_HOURS=24
REQUIRE_TOKEN_EXPIRATION=true

🎯 User Stories Implemented

👤 User Authentication

  • As a user, I can register with email/password and get secure Argon2id authentication
  • As a user, I can login via SSO providers (GitHub, Google, IBM Security Verify)
  • As a user, I automatically get a personal team for my private resources

👥 Team Management

  • As a user, I can create organizational teams and invite members
  • As a team owner, I can manage team settings, members, and resource visibility
  • As a team member, I can access team resources and collaborate on shared tools

🔒 Resource Scoping

  • As a user, I can create private resources only I can access
  • As a team member, I can share resources with my team by changing visibility to "team"
  • As a user, I can make resources public for cross-team discovery and access

👨‍💼 Platform Administration

  • As a platform admin, I have system-wide access to manage all teams and users
  • As a platform admin, I can configure domain-based auto-admin assignment
  • As an enterprise admin, I can integrate with corporate SSO providers

🔐 Security Features

Multi-Tenant Security Model

  • ✅ Data Isolation: Team-scoped queries prevent cross-tenant data access
  • ✅ Resource Ownership: Every resource has owner_email and team_id validation
  • ✅ Visibility Enforcement: Private/Team/Public visibility strictly enforced
  • ✅ Access Logging: Authentication and authorization events tracked
  • ✅ Secure Tokens: Invitation tokens with expiration and single-use validation

Enterprise Security Controls

  • ✅ Domain Restrictions: Corporate domain enforcement via SSO_TRUSTED_DOMAINS
  • ✅ MFA Support: Automatic enforcement of SSO provider MFA policies
  • ✅ Conditional Access: Location/device-based access controls via SSO providers
  • ✅ Audit Trail: Comprehensive logging for compliance requirements

📊 Implementation Details

Database Schema Extensions

-- Core multi-tenancy tables
CREATE TABLE email_users (email PRIMARY KEY, password_hash, full_name, is_admin, ...);
CREATE TABLE email_teams (id UUID PRIMARY KEY, name, visibility, owner_email, ...);
CREATE TABLE email_team_members (id UUID PRIMARY KEY, team_id, user_email, role, ...);
CREATE TABLE email_team_invitations (id UUID PRIMARY KEY, team_id, invited_email, token, ...);

-- All resource tables extended with:
ALTER TABLE tool ADD COLUMN team_id UUID, ADD COLUMN owner_email VARCHAR, ADD COLUMN visibility VARCHAR;
ALTER TABLE server ADD COLUMN team_id UUID, ADD COLUMN owner_email VARCHAR, ADD COLUMN visibility VARCHAR;
ALTER TABLE resource ADD COLUMN team_id UUID, ADD COLUMN owner_email VARCHAR, ADD COLUMN visibility VARCHAR;
ALTER TABLE prompt ADD COLUMN team_id UUID, ADD COLUMN owner_email VARCHAR, ADD COLUMN visibility VARCHAR;
ALTER TABLE a2a_agent ADD COLUMN team_id UUID, ADD COLUMN owner_email VARCHAR, ADD COLUMN visibility VARCHAR;

API Endpoint Updates

  • ✅ All resource endpoints support team_id filtering
  • ✅ Team membership validation on all operations
  • ✅ Consistent access control across all APIs
  • ✅ Resource creation with automatic team assignment

UI/UX Enhancements

  • ✅ Team management interface in Admin UI
  • ✅ Resource visibility controls in all creation/edit forms
  • ✅ Team member invitation workflows
  • ✅ Multi-team resource discovery interface

📚 Documentation

Complete Documentation Suite

  • ✅ Architecture Documentation: docs/docs/architecture/multitenancy.md (934 lines)
  • ✅ SSO Integration Tutorials:
    • docs/docs/manage/sso-ibm-tutorial.md
    • GitHub and Google SSO guides
  • ✅ Configuration Reference: Environment variables and settings
  • ✅ Migration Guide: Single-tenant to multi-tenant upgrade path
  • ✅ API Reference: Team-scoped endpoint documentation

Enterprise Deployment

  • ✅ Production Checklist: Security requirements and best practices
  • ✅ Troubleshooting Guide: Common multi-tenant scenarios and solutions
  • ✅ Performance Tuning: Team-based indexing and query optimization

✅ Acceptance Criteria

Core Functionality

  • Users can register with email/password authentication
  • Personal teams are auto-created for every new user
  • Users can create organizational teams and invite members
  • All resources support Private/Team/Public visibility
  • Team-scoped API endpoints work for all resource types
  • Platform admins have system-wide management access

Security Requirements

  • Argon2id password hashing with configurable parameters
  • Enhanced JWT tokens include team memberships and permissions
  • Multi-provider SSO integration (GitHub, Google, IBM Security Verify)
  • Domain-based admin assignment and user restrictions
  • Comprehensive audit logging for compliance

Enterprise Features

  • Corporate domain trust and auto-user creation
  • MFA enforcement via SSO providers
  • Team invitation system with email notifications
  • Cross-team resource discovery and access
  • Migration path from single-tenant deployments

🚀 Production Status

Ready for Production

This epic represents completed, production-ready functionality including:

  • ✅ Complete multi-tenant architecture with proper data isolation
  • ✅ Enterprise SSO integration with major providers
  • ✅ Comprehensive security model with RBAC and resource scoping
  • ✅ Production-grade documentation and deployment guides
  • ✅ Database migration strategy for existing installations
  • ✅ Performance optimization with team-based indexing

Deployment Verification

  • ✅ All unit and integration tests pass
  • ✅ Security audit completed (no high/critical issues)
  • ✅ Performance benchmarks meet requirements
  • ✅ Documentation review completed
  • ✅ Migration testing validated

🔄 Migration Impact

Breaking Changes

  • Database schema extensions (handled by Alembic migrations)
  • API endpoint changes (backward compatible with feature flags)
  • Configuration additions (new environment variables)

Upgrade Path

  1. Database Migration: Automated Alembic migrations add multi-tenant schema
  2. Configuration Update: Add multi-tenancy environment variables
  3. Feature Enablement: Enable multi-tenancy features via configuration flags
  4. User Migration: Existing users get personal teams automatically
  5. SSO Integration: Configure SSO providers as needed

🏆 Business Impact

Enterprise Readiness

  • ✅ Secure Multi-Tenancy: Enterprise customers can deploy with confidence
  • ✅ SSO Integration: Seamless integration with existing identity infrastructure
  • ✅ Team Collaboration: Enable collaborative workflows within organizations
  • ✅ Resource Governance: Proper resource scoping and access controls

Scalability

  • ✅ Performance Optimization: Team-based indexing and query filtering
  • ✅ Resource Isolation: Proper data separation for compliance requirements
  • ✅ Admin Efficiency: Platform-level management for enterprise deployments

This epic transforms MCP Gateway into a production-ready enterprise platform capable of supporting complex organizational structures with secure, scalable multi-tenancy.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or requestsecurityImproves security

Type

Feature

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions