Software Engineer Encyclopedia
0%
Domain 14 · SaaS & Product Engineering · Topic 14.1

هندسة SaaS متعددة العملاء

Multi-Tenant SaaS Architecture

تصميم SaaS آمن يعزل بيانات العملاء ويضبط الاستخدام والتكلفة والاشتراكات.

  • Professional Engineering
  • ~18 min read
  • 13 sections
  • 16 code examples
  • 2 diagrams
  • 9 questions
  • Priority L2 · Essential
  • ASP.NET Core · EF Core · PostgreSQL · Identity

بعد الدرس ده هتقدر

  • تطبّق Row-Level Security في PostgreSQL وتثبت إنه fail closed.
  • تربط الـ tenant بالـ transaction بشكل آمن مع connection pooling.
  • تختار نموذج العزل المناسب وتكتب test بيثبته.

المتطلبات قبل ما تبدأ

Security + Architecture + System Design.

مستوى التعمق المطلوب

PRACTICALتصمم منتج SaaS بيعزل داتا كل عميل ويحسب الاستخدام والاشتراكات والتكلفة لكل tenant.

01

ما معنى Multi-Tenancy؟

One product, isolated customer workspaces
Deep dive

Tenant هو customer/account/workspace مستقل داخل SaaS واحد. كل tenant قد يملك users و documents و projects و usage و settings خاصة به. Multi-tenancy تقلل تكلفة تشغيل نسخة منفصلة لكل عميل، لكنها تخلق مسؤولية أمنية: أي خطأ في query أو cache أو background job قد يكشف بيانات tenant آخر.

ميّز بين tenant و user و organization و workspace؛ قد يكون للعميل عدة workspaces، وقد ينتمي user لأكثر من tenant. لا تفترض أن tenant واحد يساوي user واحد. صمم identity membership واضحة: User ↔ Tenant عبر TenantMembership مع roles/permissions داخل tenant.

مثال عملي: نموذج العضوية الصح من أول يوم

شركة «Contoso Legal» عندها 3 فروع، وكل فرع عايز workspace منفصل، والمحامية «سارة» شغالة في فرعين. لو صممت الـ schema على إن User.TenantId عمود واحد، سارة محتاجة حسابين وإيميلين — وده أول طلب هيجيلك بعد أسبوعين من الإطلاق. الصح:

C#Domain/Membership.cs
public sealed class Tenant          { public Guid Id { get; init; } public string Slug { get; init; } = ""; public TenantStatus Status { get; set; } public string Plan { get; set; } = "free"; public string Region { get; init; } = "eu"; }
public sealed class AppUser         { public Guid Id { get; init; } public string Email { get; init; } = ""; }   // global identity, NOT tenant-scoped
public sealed class TenantMembership
{
    public Guid TenantId { get; init; }
    public Guid UserId { get; init; }
    public string Role { get; set; } = "member";              // owner | admin | member | viewer
    public DateTimeOffset JoinedAt { get; init; }
    public DateTimeOffset? RevokedAt { get; set; }            // soft revoke keeps audit history
}
public enum TenantStatus { Provisioning, Active, Suspended, PendingDeletion, Deleted }

ليه كده؟ الهوية (مين إنت) عالمية، والصلاحية (تعمل إيه هنا) خاصة بكل tenant. ده نفس الفصل بين authentication و authorization اللي في Auth Pillar، بس بُعد إضافي.

Failure case

منتج بدأ بـ User.TenantId. بعد سنة، عميل enterprise طلب «حساب واحد لمستشار خارجي يدخل على 4 شركات تابعة». الحل اتعمل كـ hack (حسابات مكررة بنفس الإيميل + suffix) وبوّظ الـ SSO والـ audit. التكلفة: migration للـ identity كلها. الدرس: membership table من أول يوم حتى لو أول نسخة بتسمح بـ tenant واحد لكل user.

02

Tenancy Models: Shared DB, Schema per Tenant, DB per Tenant

Choose isolation, cost and operations deliberately
Deep dive

Shared database/shared schema: كل الجداول تحتوي TenantId. أقل تكلفة وأسهل migrations، لكن أي query ناقص filter خطر، و noisy neighbor قد يؤثر على الجميع. Schema per tenant يعزل namespace لكنه يزيد تعقيد migrations/connection management، ولا يوفر دائمًا عزلًا أمنيًا كاملًا وحده. Database per tenant يعطي isolation و backup/restore/region flexibility أقوى لكنه يرفع operational cost وإدارة connections والمigrations.

يمكن استخدام hybrid model: shared tier للعملاء الصغار و dedicated database للعملاء enterprise. القرار يعتمد على regulatory requirements، tenant count، data size، restore granularity، noisy-neighbor tolerance، و operational maturity. وثّق trade-off في ADR ولا تبدأ بأعلى تعقيد دون حاجة.

إزاي تختار فعلًا: جدول قرار برقم

السؤاللو الإجابة…بيميل لـ
عدد الـ tenants المتوقعآلاف صغيرة (self-serve)Shared schema + RLS
عقود بتطلب عزل فيزيائي/backup منفصلأيوه لبعض العملاءHybrid: silo لـ enterprise
Data residency (EU/KSA/…)عملاء في مناطق مختلفةDB/cluster لكل region (cells)، shared جوه الـ region
Restore لـ tenant واحد بدون الباقيمطلب صريحDB per tenant أو أدوات export/restore per tenant
نضج التشغيلفريق صغير من غير DBAابدأ shared؛ كل DB زيادة = migrations و monitoring زيادة
Tenant routertenant → placementPool DB (shared schema + RLS)thousands of free/pro tenantsSilo DBenterprise ASilo DBenterprise B (KSA)Same code, same migrationsplacement is data, not a fork
Hybrid tenancy: a shared pool for most tenants, dedicated silos for those who pay for isolation
C#TenantPlacement.cs
public sealed record TenantPlacement(Guid TenantId, string Region, string ConnectionName, bool Dedicated);

public sealed class TenantDbContextFactory(ITenantContext tenant, IPlacementStore placements, IConfiguration cfg)
{
    public async Task<AppDb> CreateAsync(CancellationToken ct)
    {
        var p = await placements.GetAsync(tenant.TenantId, ct);       // cached, from a control-plane table
        var options = new DbContextOptionsBuilder<AppDb>()
            .UseNpgsql(cfg.GetConnectionString(p.ConnectionName))
            .Options;
        return new AppDb(options, tenant);                             // same model, same migrations everywhere
    }
}

Failure case: فريق عمل «schema per tenant» لـ 3,000 tenant. كل migration بقت loop على 3,000 schema بتاخد ساعات، وواحدة فشلت في النص فبقى فيه tenants على نسختين من الـ schema. التفاصيل وحلها في SaaS Operations at Scale.

03

Tenant Resolution and Trusted Context

Never trust a tenant ID supplied by the browser
Pitfalls

مصادر tenant resolution قد تكون subdomain أو route أو claim أو API key. أي قيمة من request يجب التحقق منها وربطها بالـ authenticated principal. Header مثل X-Tenant-Id ليس دليل صلاحية؛ هو selector فقط. استخرج membership من trusted identity/database، وتحقق أن user عضو في tenant المطلوب قبل إنشاء TenantContext scoped للطلب.

اجعل resolution مبكرًا في request pipeline، وتعامل مع missing/ambiguous tenant كخطأ واضح. في background jobs لا يوجد HttpContext؛ خزّن tenant ID كجزء من job payload ثم أعد التحقق من وجود tenant وحالته عند التنفيذ. لا تستخدم mutable static tenant state في تطبيق متعدد المستخدمين.

C#Never trust a tenant ID supplied by the browser
public sealed record TenantContext(Guid TenantId, Guid UserId);

public interface ITenantContextAccessor
{
    TenantContext Current { get; }
}

// Resolve tenant selector -> authenticate principal -> verify membership ->
// create scoped TenantContext. Do not trust a raw X-Tenant-Id header by itself.

Implementation كامل: من الـ request للـ TenantContext

C#TenantResolutionMiddleware.cs
public sealed class TenantResolutionMiddleware(RequestDelegate next)
{
    public async Task InvokeAsync(HttpContext http, IMembershipStore members, TenantContextHolder holder)
    {
        if (http.User.Identity?.IsAuthenticated != true) { await next(http); return; }   // auth endpoints etc.

        // 1) selector: subdomain (acme.app.example) or route value; never trusted on its own
        var slug = http.Request.Host.Host.Split('.')[0];
        // 2) principal from the validated token
        var userId = Guid.Parse(http.User.FindFirstValue("sub")!);
        // 3) membership from OUR database (cached briefly), not from the request
        var m = await members.FindAsync(slug, userId, http.RequestAborted);
        if (m is null || m.RevokedAt is not null)
        {
            http.Response.StatusCode = StatusCodes.Status404NotFound;   // 404 not 403: do not confirm the tenant exists
            return;
        }
        if (m.TenantStatus is TenantStatus.Suspended or TenantStatus.PendingDeletion)
        {
            await Results.Problem(title: "Workspace unavailable", statusCode: 423).ExecuteAsync(http);
            return;
        }
        holder.Current = new TenantContext(m.TenantId, userId, m.Role);   // scoped service, set once per request
        using (LogContextScope.Push("tenant_id", m.TenantId))             // every log line carries the tenant
            await next(http);
    }
}

Background jobs: الـ job payload بيحمل TenantId و InitiatedBy، والـ worker بيبني TenantContext من جديد بعد ما يتأكد إن الـ tenant لسه Active والـ user لسه عضو (ممكن يكون اتشال بين الـ enqueue والتنفيذ).

Failure case: tenant ID في الـ body

endpoint POST /api/reports كان بياخد tenantId في الـ JSON «عشان الـ admin dashboard». مستخدم عادي غيّر الرقم وطلع تقرير tenant تاني. الـ global filter ما حماش لأن الكود استخدم الـ tenantId اللي جاي من الـ body في الـ filter نفسه. القاعدة: الـ tenant بييجي من TenantContext فقط؛ أي tenantId في input = 400.

04

Tenant Isolation in EF Core

Global filters help, but they are not the security boundary
Deep dive

EF Core Global Query Filters تضيف predicate تلقائيًا مثل TenantId == currentTenantId للكيانات tenant-scoped. هذا يقلل احتمال نسيان filter في LINQ، لكنه لا يغطي كل access path: raw SQL، bulk operations، IgnoreQueryFilters، detached entities، admin paths، و incorrectly scoped DbContext قد تتجاوز الحماية.

اجعل TenantId immutable بعد إنشاء entity، واملأه server-side من TenantContext لا من DTO. أضف composite indexes تبدأ بـ TenantId عندما يناسب query pattern، و unique constraints تشمل TenantId حتى لا تتعارض IDs بين العملاء. اختبر cross-tenant reads/writes في integration tests، ولا تعتمد على unit tests فقط.

C#Global filters help, but they are not the security boundary
// Illustrative EF Core configuration
modelBuilder.Entity<Invoice>()
    .HasQueryFilter(x => x.TenantId == _tenantContext.TenantId);

modelBuilder.Entity<Invoice>()
    .HasIndex(x => new { x.TenantId, x.InvoiceNumber })
    .IsUnique();

// Also validate TenantId on writes and review raw SQL / IgnoreQueryFilters paths.

الـ DbContext بالكامل + الأماكن اللي الفلتر ما بيغطيهاش

C#AppDb.cs
public interface ITenantOwned { Guid TenantId { get; } }

public sealed class AppDb(DbContextOptions<AppDb> options, ITenantContext tenant) : DbContext(options)
{
    public DbSet<Invoice> Invoices => Set<Invoice>();
    public DbSet<Document> Documents => Set<Document>();

    protected override void OnModelCreating(ModelBuilder b)
    {
        foreach (var et in b.Model.GetEntityTypes().Where(t => typeof(ITenantOwned).IsAssignableFrom(t.ClrType)))
        {
            // Build `e => e.TenantId == tenant.TenantId` for every tenant-owned entity automatically.
            var p = Expression.Parameter(et.ClrType, "e");
            var body = Expression.Equal(Expression.Property(p, nameof(ITenantOwned.TenantId)),
                                        Expression.Property(Expression.Constant(this), nameof(CurrentTenantId)));
            b.Entity(et.ClrType).HasQueryFilter(Expression.Lambda(body, p));
            b.Entity(et.ClrType).HasIndex(nameof(ITenantOwned.TenantId));
        }
    }
    public Guid CurrentTenantId => tenant.TenantId;           // evaluated per query, per context instance

    public override Task<int> SaveChangesAsync(CancellationToken ct = default)
    {
        foreach (var e in ChangeTracker.Entries<ITenantOwned>())
        {
            if (e.State == EntityState.Added)
                e.Property(nameof(ITenantOwned.TenantId)).CurrentValue = tenant.TenantId;     // server-side, always
            else if (e.State == EntityState.Modified && e.Property(nameof(ITenantOwned.TenantId)).IsModified)
                throw new InvalidOperationException("TenantId is immutable");
        }
        return base.SaveChangesAsync(ct);
    }
}

Access paths خارج الفلتر (كل واحد لازم test): FromSqlRaw/SqlQuery، ExecuteUpdate/ExecuteDelete (بيحترموا الفلتر لكن راجع)، Dapper/ADO.NET reports، IgnoreQueryFilters() في الـ admin، الـ Find على entity متتبعة من context تاني، الـ projections لـ search engines والـ vector store، والـ exports. عشان كده RLS (s5) تحت الـ ORM.

Production note

أضف analyzer/architecture test بيمنع IgnoreQueryFilters برّه namespace معيّن (مثلًا Admin.CrossTenant) وكل استخدام له يتسجّل في الـ audit log.

05

Database Row-Level Security and Defense in Depth

Enforce tenant boundaries below the ORM
Deep dive

PostgreSQL Row-Level Security (RLS) يسمح بكتابة policies تحدد الصفوف التي يمكن قراءتها أو تعديلها. عند تفعيله، يجب ضبط tenant context داخل transaction/session بطريقة لا تتسرب بين pooled connections. استخدم SET LOCAL داخل transaction عند الإمكان، وتأكد أن application role ليس table owner أو BYPASSRLS دون قصد؛ table owners قد يتجاوزون policies في الإعدادات المعتادة.

RLS طبقة دفاع إضافية وليست بديلًا عن application authorization. اختبر كل operation تحت database role الفعلي، وراجع policies للـ SELECT/INSERT/UPDATE/DELETE، وراجع connection pooling/reset semantics. خطأ في session variable أو role configuration قد يبطل العزل.

SQLEnforce tenant boundaries below the ORM
-- PostgreSQL conceptual example; adapt role names and transaction handling.
ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON invoices
USING (tenant_id = current_setting('app.tenant_id', true)::uuid)
WITH CHECK (tenant_id = current_setting('app.tenant_id', true)::uuid);

-- Set app.tenant_id transaction-locally from authenticated server context.

المثال الكامل اتنفّذ في v2-rls — هنا الأخطاء اللي بتكسره

  • الـ app بيتصل كـ owner الجدول: الـ owner بيتخطى الـ policies (إلا لو FORCE ROW LEVEL SECURITY). الحل: role منفصل للتطبيق، والـ migrations بـ role تاني.
  • SET بدل SET LOCAL مع pooling: القيمة بتفضل على الـ connection وترجع للـ pool، والطلب الجاي (tenant تاني) يرثها لو ما اتضبطتش. استخدم set_config(..., true) جوه transaction.
  • current_setting('app.tenant_id', true) رجّع NULL: المقارنة tenant_id = NULL بترجع NULL = مفيش صفوف = fail closed. ده كويس — اتأكد إنك ما كتبتش policy زي OR current_setting(...) IS NULL «عشان الـ jobs».
  • Policies ناقصة على INSERT/UPDATE: USING بيحمي القراءة؛ WITH CHECK بيمنع كتابة صف بـ tenant تاني.
SQLrls_hardening.sql
ALTER TABLE invoices FORCE ROW LEVEL SECURITY;               -- even the owner obeys the policy
CREATE ROLE app_runtime LOGIN NOINHERIT NOBYPASSRLS;           -- the API connects as this
CREATE ROLE app_migrator LOGIN;                                -- owns tables; used only by migrations
-- Admin/reporting across tenants is an explicit, audited role, not a missing filter:
CREATE ROLE app_crosstenant_reader NOLOGIN BYPASSRLS;

Row-Level Security في PostgreSQL: عزل بيتنفذ حتى لو الكود نسي

الـ global query filter في EF Core بيحميك طول ما كل query بتعدّي عليه. أول FromSqlRaw، أول report مكتوب بـ Dapper، أول IgnoreQueryFilters() اتنسى — والعزل اتكسر في صمت. الـ Row-Level Security بيحط القاعدة في قاعدة البيانات نفسها: الصف اللي مش بتاع الـ tenant مش موجود من وجهة نظر الـ query، مهما كان اللي كتبها.

SQLrls_demo.sql — policies, a non-owner application role, and what each tenant can see or doExecuted ✓
SET client_min_messages = warning;
DROP TABLE IF EXISTS invoices; DROP ROLE IF EXISTS app_user;
CREATE ROLE app_user NOLOGIN;                         -- the role the API connects as: NOT the table owner

CREATE TABLE invoices (
    id        int  GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    tenant_id uuid NOT NULL,
    customer  text NOT NULL,
    amount    numeric(10,2) NOT NULL
);
GRANT SELECT, INSERT, UPDATE, DELETE ON invoices TO app_user;

INSERT INTO invoices (tenant_id, customer, amount) VALUES
  ('11111111-1111-1111-1111-111111111111', 'Nile Traders', 1200),
  ('11111111-1111-1111-1111-111111111111', 'Delta Foods',   340),
  ('22222222-2222-2222-2222-222222222222', 'Sahara Tech',  9900);

ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON invoices
    USING      (tenant_id = current_setting('app.tenant_id', true)::uuid)     -- which rows are visible
    WITH CHECK (tenant_id = current_setting('app.tenant_id', true)::uuid);    -- which rows may be written

SET ROLE app_user;

\echo '--- no tenant set: fail closed (zero rows, not all rows)'
SELECT count(*) AS visible_rows FROM invoices;

\echo '--- tenant 1: a query with NO WHERE clause still sees only its own rows'
BEGIN;
SET LOCAL app.tenant_id = '11111111-1111-1111-1111-111111111111';
SELECT customer, amount FROM invoices ORDER BY id;
\echo '--- tenant 1 tries to update tenant 2''s invoice'
UPDATE invoices SET amount = 0 WHERE customer = 'Sahara Tech';
\echo '--- tenant 1 tries to insert a row for tenant 2 (rejected by WITH CHECK)'
SAVEPOINT s;
\set ON_ERROR_STOP off
INSERT INTO invoices (tenant_id, customer, amount) VALUES ('22222222-2222-2222-2222-222222222222', 'Planted row', 1);
\set ON_ERROR_STOP on
ROLLBACK TO s;
COMMIT;

\echo '--- tenant 2: its invoice is untouched'
BEGIN;
SET LOCAL app.tenant_id = '22222222-2222-2222-2222-222222222222';
SELECT customer, amount FROM invoices;
COMMIT;

RESET ROLE;
\echo '--- the table OWNER bypasses RLS unless FORCE is set'
SELECT count(*) AS owner_sees FROM invoices;
ALTER TABLE invoices FORCE ROW LEVEL SECURITY;
DROP TABLE invoices; DROP ROLE app_user;
ConsoleOutput — captured from a real run
SET
DROP TABLE
DROP ROLE
CREATE ROLE
CREATE TABLE
GRANT
INSERT 0 3
ALTER TABLE
CREATE POLICY
SET
--- no tenant set: fail closed (zero rows, not all rows)
 visible_rows 
--------------
            0
(1 row)

--- tenant 1: a query with NO WHERE clause still sees only its own rows
BEGIN
SET
   customer   | amount  
--------------+---------
 Nile Traders | 1200.00
 Delta Foods  |  340.00
(2 rows)

--- tenant 1 tries to update tenant 2's invoice
UPDATE 0
--- tenant 1 tries to insert a row for tenant 2 (rejected by WITH CHECK)
SAVEPOINT
psql: line 37: ERROR:  new row violates row-level security policy for table "invoices"
ROLLBACK
COMMIT
--- tenant 2: its invoice is untouched
BEGIN
SET
  customer   | amount  
-------------+---------
 Sahara Tech | 9900.00
(1 row)

COMMIT
RESET
--- the table OWNER bypasses RLS unless FORCE is set
 owner_sees 
------------
          3
(1 row)

ALTER TABLE
DROP TABLE
DROP ROLE

من غير tenant: صفر صفوف. current_setting('app.tenant_id', true) بترجّع NULL لو الإعداد مش موجود، و tenant_id = NULL عمرها ما تبقى true. يعني نسيان تحديد الـ tenant بيدّي نتيجة فاضية (bug واضح) بدل ما يدّي كل البيانات (كارثة). ده معنى fail closed.

الـ UPDATE رجّع UPDATE 0 مش error: صف الـ tenant التاني مش مرئي أصلًا فمفيش حاجة تتعدّل. والـ INSERT اترفض بسبب WITH CHECK — من غيرها tenant يقدر «يزرع» صفوف عند غيره.

SET LOCAL جوه transaction: الإعداد بيتمسح مع نهاية الـ transaction. ده ضروري مع connection pooling: لو استخدمت SET عادي، الـ connection هيرجع للـ pool وهو لسه شايل tenant الطلب اللي فات — والطلب الجاي ممكن يشتغل بهوية غلط.

الـ owner والـ superuser بيعدّوا الـ RLS. الـ API لازم يتصل بـ role عادي مش صاحب الجداول، والـ migrations بـ role تاني. FORCE ROW LEVEL SECURITY بيطبق الـ policies على الـ owner كمان.

ربطها بـ EF Core

حالة التحقق

الـ SQL فوق اتنفذ فعلًا على PostgreSQL 16. كود C#‎ اللي تحت لم يتم عمل compile له.

C#TenantConnectionInterceptor.cs — set the tenant on every transaction, from the authenticated context
public sealed class TenantTransactionInterceptor(ITenantContext tenant) : DbTransactionInterceptor
{
    public override async Task TransactionStartedAsync(
        DbConnection connection, TransactionEndEventData eventData, CancellationToken ct = default)
    {
        await using var cmd = connection.CreateCommand();
        cmd.Transaction = eventData.Transaction;
        // set_config(name, value, is_local = true) is the parameterisable form of SET LOCAL
        cmd.CommandText = "SELECT set_config('app.tenant_id', @tenant, true)";
        var p = cmd.CreateParameter(); p.ParameterName = "tenant"; p.Value = tenant.TenantId.ToString();
        cmd.Parameters.Add(p);
        await cmd.ExecuteNonQueryAsync(ct);
    }
}

// Registration: every unit of work runs inside an explicit transaction, so the setting is always present.
builder.Services.AddScoped<TenantTransactionInterceptor>();
builder.Services.AddDbContext<AppDbContext>((sp, o) => o
    .UseNpgsql(connectionString)                         // connects as app_user, not as the table owner
    .AddInterceptors(sp.GetRequiredService<TenantTransactionInterceptor>()));

Defense in depth: خلّي الـ global query filter موجود (بيدّي queries أوضح وأخطاء بدري في الـ tests) والـ RLS تحته كشبكة أمان. الاتنين بياخدوا الـ tenant من نفس المصدر: الـ token المتحقق منه، مش header ولا query string.

الـ test اللي لازم يكون موجود: integration test بيعمل بيانات لـ tenant A و B، وبينفذ raw SQL من غير WHERE بهوية A، ويتأكد إن صفوف B مش راجعة. لو الـ test ده عدّى من غير RLS يبقى مش بيختبر حاجة.

نموذج العزلالعزلالتكلفة التشغيليةمناسب لـ
Shared schema + tenant_id + RLSمنطقي، مفروض من قاعدة البياناتالأقل: migration واحدة، pool واحدأغلب الـ B2B SaaS — نقطة البداية
Schema لكل tenantأقوى؛ backup/restore لكل tenant ممكنmigrations × عدد الـ tenantsعشرات–مئات tenants بمتطلبات مختلفة
Database لكل tenantالأقوى؛ noisy neighbour معزولالأعلى: provisioning، connections، تكلفةenterprise، residency، compliance

فعّلت RLS والـ API لسه بيرجّع بيانات كل الـ tenants. أرجح سبب؟

06

Tenant Permissions, Quotas and Noisy Neighbors

Authorization is not the same as rate limiting
Deep dive

Tenant-level authorization answers “هل هذا المستخدم مسموح له بهذا الفعل على هذا المورد داخل tenant؟”. Quota answers “كم استهلاك هذا tenant مسموح؟”. Rate limit controls request frequency؛ concurrency limit controls simultaneous expensive work؛ usage quota controls cumulative consumption مثل tokens أو storage أو documents.

ضع limits حسب plan مع server-side enforcement. استخدم atomic counters أو usage ledger موثوق، ولا تعتمد على client-side counters. صمم burst allowance و grace policy و overage behavior. راقب noisy neighbor عبر CPU/queue depth/DB connections/model concurrency per tenant، واستخدم fair scheduling أو per-tenant queues عند الحاجة.

C#Authorization is not the same as rate limiting
public sealed record TenantLimits(int RequestsPerMinute, int MaxConcurrentAiJobs, long MonthlyTokenBudget);

// Enforce at the server boundary using atomic counters / durable usage records.
// Return 429 for rate limit, 403/402-style product state for exhausted plan,
// and expose reset/upgrade guidance without leaking another tenant's usage.

Noisy neighbor بالأرقام: FIFO مقابل fair queueing

Tenant كبير رفع 400 مستند مرة واحدة. لو الـ ingestion workers بتسحب من طابور واحد FIFO، كل الـ tenants الصغيرين بيستنوا وراه. Fair queueing (round-robin بين طوابير الـ tenants) بيحمي الصغيرين والكبير بيدفع تمن زيادة بسيط:

Pythonfairq_lab.pyExecuted ✓
import random
from collections import deque
random.seed(9)

# 3 small tenants send a steady trickle; tenant "big" uploads 400 documents at t=10s.
jobs = []
for t in range(0, 120):
    for tenant in ("t-small-1", "t-small-2", "t-small-3"):
        if random.random() < 0.25: jobs.append((t + random.random(), tenant))
jobs += [(10 + i * 0.01, "t-big") for i in range(400)]
jobs.sort()
WORKERS, JOB_S = 4, 2.0                    # 4 workers, each ingestion job takes 2 s

def simulate(policy):
    queues = {} ; fifo = deque(); pending = deque(jobs); waits = {}
    free_at = [0.0] * WORKERS; rr = deque()
    now = 0.0
    while pending or fifo or any(queues.values()):
        w = min(range(WORKERS), key=lambda i: free_at[i]); now = max(now, free_at[w])
        while pending and pending[0][0] <= now:                  # enqueue arrivals
            arr, ten = pending.popleft()
            if policy == "fifo": fifo.append((arr, ten))
            else:
                if ten not in queues: queues[ten] = deque()
                if not queues[ten] and ten not in rr: rr.append(ten)
                queues[ten].append(arr)
        job = None
        if policy == "fifo" and fifo: job = fifo.popleft()
        elif policy == "fair":
            while rr and not queues[rr[0]]: rr.popleft()
            if rr:
                ten = rr.popleft(); job = (queues[ten].popleft(), ten)
                if queues[ten]: rr.append(ten)                    # round-robin across tenants
        if job is None:
            now = pending[0][0] if pending else now; free_at[w] = max(free_at[w], now); continue
        waits.setdefault(job[1], []).append(now - job[0]); free_at[w] = now + JOB_S
    return waits

for pol in ("fifo", "fair"):
    w = simulate(pol)
    small = sorted(x for k, v in w.items() if k != "t-big" for x in v)
    big = sorted(w["t-big"])
    print(f"{pol:5s} small tenants: p50 wait {small[len(small)//2]:6.1f}s  p95 {small[int(len(small)*.95)]:6.1f}s | big tenant p95 {big[int(len(big)*.95)]:6.1f}s")
ConsoleOutput — captured from a real run
fifo  small tenants: p50 wait  169.3s  p95  198.0s | big tenant p95  189.1s
fair  small tenants: p50 wait    1.1s  p95    1.9s | big tenant p95  237.1s

في الإنتاج: طابور لكل tenant (أو partitioning بالـ tenant في Service Bus/RabbitMQ/Kafka أو جدول jobs في Postgres بـ ORDER BY عادل)، وحد للـ concurrency لكل tenant، والـ plan بيحدد الأولوية (enterprise weight أعلى = weighted fair queueing).

C#Program.cs (per-tenant rate limiting)
builder.Services.AddRateLimiter(o =>
{
    o.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
    o.AddPolicy("per-tenant", http =>
    {
        var t = http.RequestServices.GetRequiredService<ITenantContext>();
        var limits = http.RequestServices.GetRequiredService<IPlanCatalog>().For(t.TenantId);
        return RateLimitPartition.GetTokenBucketLimiter(t.TenantId.ToString(), _ => new TokenBucketRateLimiterOptions
        {
            TokenLimit = limits.Burst, TokensPerPeriod = limits.RequestsPerMinute,
            ReplenishmentPeriod = TimeSpan.FromMinutes(1), QueueLimit = 0, AutoReplenishment = true
        });
    });
});
// app.MapPost("/api/chat", ...).RequireRateLimiting("per-tenant");
// NOTE: in-memory limiters are per instance; with N instances use a distributed limiter (Redis) or divide limits by N.
07

Subscriptions, Metering and AI Cost Attribution

Bill usage from an auditable ledger
Deep dive

Subscription plan يحدد entitlements: seats، storage، API calls، document pages، و AI tokens. لا تخلط plan name مع enforcement logic؛ استخدم entitlement model قابل للتطور. Metering يسجل usage events immutable مع tenant، feature، quantity، unit، timestamp، provider/model، و correlation ID. Billing aggregation يقرأ ledger ولا يعتمد على counters قابلة للتعديل فقط.

في AI، سجّل input/output tokens و embedding/reranking/OCR costs، retries، cache hits، و model route. احسب internal cost و billable usage بشكل منفصل لأن provider price و commercial pricing ليسا الشيء نفسه. أضف reconciliation مع provider invoices، idempotent usage ingestion، و dispute audit.

C#Bill usage from an auditable ledger
public sealed record UsageEvent(
    Guid TenantId, string Feature, string Unit,
    decimal Quantity, string ModelId, string CorrelationId,
    DateTimeOffset OccurredAt);

// Store immutable events; aggregate by billing period and entitlement version.
// Deduplicate provider callbacks/events with a stable event ID.

Ledger عملي + الربط بالفوترة

SQLusage_ledger.sql
CREATE TABLE usage_events (
  event_id      text PRIMARY KEY,                -- idempotency: same event twice = one row
  tenant_id     uuid NOT NULL,
  feature       text NOT NULL,                   -- 'ai.chat', 'ai.embed', 'storage.gb_day', 'seats'
  unit          text NOT NULL,                   -- 'input_token', 'output_token', 'page', 'seat_day'
  quantity      numeric(20,6) NOT NULL CHECK (quantity >= 0),
  cost_usd      numeric(20,8),                   -- OUR provider cost (internal), from a versioned price table
  model_id      text,
  price_version text,
  occurred_at   timestamptz NOT NULL,
  ingested_at   timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX ON usage_events (tenant_id, occurred_at);

-- Billable usage for a period is a query over immutable facts, never a mutable counter:
SELECT feature, unit, sum(quantity) AS qty, sum(cost_usd) AS our_cost
FROM usage_events
WHERE tenant_id = $1 AND occurred_at >= $2 AND occurred_at < $3
GROUP BY feature, unit;

ليه immutable events؟ لما العميل يعترض على فاتورة، لازم تقدر تقول «الـ 2.1 مليون token دول جم من 3,412 request، ودي الـ traces». الـ counter اللي بيتعدل ما بيجاوبش. وتفاصيل الخطط والـ entitlements والـ webhooks في Billing & Subscriptions.

Failure case: double counting

الـ usage event اتبعت من الـ API بعد الرد، والـ client عمل retry بعد timeout ← نفس الاستهلاك اتسجل مرتين. الحل: event_id مشتق من (request id + نوع الاستهلاك) و PRIMARY KEY عليه + ON CONFLICT DO NOTHING.

08

Enterprise SSO, Tenant Lifecycle and Data Operations

Enterprise readiness beyond login
Deep dive

Enterprise SSO غالبًا عبر OIDC أو SAML حسب customer IdP. اربط external subject بالـ tenant membership، وراجع domain verification و JIT provisioning و SCIM lifecycle إن احتجت. لا تسمح لأي email domain بمجرد مطابقته أن ينشئ membership تلقائيًا دون verified ownership/policy. دعم MFA/session policy و audit export قد يكون مطلوبًا.

Tenant lifecycle يشمل provisioning، plan change، suspension، export، deletion، restore، و region migration. deletion يجب أن يغطي primary DB و search/vector indexes و object storage و caches و derived AI artifacts وفق retention/legal holds. backup deletion لها semantics مختلفة وقد تحتاج expiry policy. وثّق tenant offboarding runbook واختبره.

Tenant lifecycle كـ state machine

ProvisioningActiveSuspendedPendingDeletionDeleted (+ evidence)reactivate (payment fixed)grace period · export offered · legal hold check
Tenant lifecycle: every transition is an audited command with side effects
  • Provisioning idempotent: لو الخطوة 3 من 5 فشلت (إنشاء bucket مثلًا)، إعادة التشغيل تكمّل من غير ما تكرر.
  • Suspended: القراءة/export مسموح غالبًا، الكتابة والـ AI ممنوعين، الـ jobs متوقفة — والـ UI بيقول ليه وإزاي يرجع.
  • Deletion: نفس فكرة الـ erasure orchestrator + verifier في Governance، لكن على مستوى tenant: DB rows، vectors، blobs، caches، search indexes، traces، adapters، و backups بالـ expiry.

SSO pitfall: «أي حد إيميله ينتهي بـ @acme.com يدخل tenant Acme تلقائيًا» من غير domain verification (DNS TXT) = أي حد يسجل الدومين ده عند IdP ضعيف أو acme.com.evil يقدر يدخل. JIT provisioning مسموح بس بعد التحقق من ملكية الدومين ومن الـ IdP المربوط.

09

اختبار SaaS Isolation عمليًا

Adversarial tests for every data path
Practical

أنشئ Tenant A و Tenant B، وجرّب قراءة resource ID صحيح تابع للآخر، تحديثه، حذفه، البحث عنه في vector index، استرجاعه من cache، تشغيل background job له، وتنفيذ MCP tool عليه. اختبر أيضًا tenant switching داخل نفس user session، revoked membership، disabled tenant، و raw SQL/reporting endpoints.

اختبارات العزل يجب أن تكون integration/security tests على نفس roles/configuration المستخدمة فعليًا. أضف negative assertions: لا result، لا metadata leak، لا count leak، لا cache hit cross-tenant. أي cross-tenant leak هو release blocker.

PythonAdversarial tests for every data path
# Example test matrix (automate with integration tests)
checks = [
  'API_GET_cross_tenant_resource_denied',
  'EF_Core_query_filter_applied',
  'raw_SQL_RLS_policy_enforced',
  'vector_search_acl_filter_applied',
  'cache_key_includes_tenant',
  'background_job_revalidates_tenant',
  'MCP_tool_checks_resource_tenant',
]
print('Isolation checks:', len(checks))

الـ matrix ده كـ xUnit test حقيقي

C#IsolationMatrixTests.cs
public sealed class IsolationMatrixTests(ApiFactory api) : IClassFixture<ApiFactory>
{
    public static TheoryData<string, string> Endpoints => new()
    {
        { "GET",    "/api/invoices/{id}" },
        { "PUT",    "/api/invoices/{id}" },
        { "DELETE", "/api/invoices/{id}" },
        { "GET",    "/api/documents/{id}/download" },
        { "POST",   "/api/chat?docId={id}" },               // AI path: retrieval must not see the other tenant
    };

    [Theory, MemberData(nameof(Endpoints))]
    public async Task Tenant_B_cannot_touch_tenant_A_resources(string method, string template)
    {
        var aId = await api.SeedInvoiceAndDocAsync(tenant: "a");
        var client = api.ClientFor(tenant: "b", role: "admin");          // even an ADMIN of B
        var resp = await client.SendAsync(new HttpRequestMessage(new HttpMethod(method), template.Replace("{id}", aId.ToString())));

        Assert.True(resp.StatusCode is HttpStatusCode.NotFound or HttpStatusCode.Forbidden, $"{method} {template} -> {resp.StatusCode}");
        var body = await resp.Content.ReadAsStringAsync();
        Assert.DoesNotContain("tenant-a-secret", body);                 // no data or metadata leak in errors either
    }
}

شغّله في CI على Postgres حقيقي (Testcontainers) بنفس الـ roles بتاعة الإنتاج. أي endpoint جديد لازم يتضاف للـ matrix — وتقدر تخلي test تاني يلف على كل الـ endpoints المسجلة (EndpointDataSource) ويفشل لو endpoint فيه {id} مش موجود في الـ matrix.

10

اختبر فهمك

Knowledge Check
Practical
هل X-Tenant-Id القادم من المتصفح دليل authorization؟
لا؛ هو selector غير موثوق ويجب ربطه بالـ authenticated principal والتحقق من membership.
لماذا Global Query Filters ليست boundary أمنية وحيدة؟
لأن raw SQL و IgnoreQueryFilters و bulk operations وبعض المسارات قد تتجاوزها؛ نحتاج tests وقيودًا إضافية وربما RLS.
لماذا نفصل usage ledger عن plan entitlements؟
الـ plan يحدد المسموح، والـ ledger يسجل الاستهلاك الفعلي القابل للمراجعة والفوترة.
11

تمارين محلولة

Solved exercises
Practical
1: Redis cache key = invoice:{id}. فين المشكلة؟

الحل: لو الـ IDs مش globally unique (أو حتى لو unique)، أي bug في الـ authorization بعد الـ cache ممكن يرجّع بيانات tenant تاني، والمسح لكل tenant مستحيل. الـ key: t:{tenantId}:invoice:{id}، والـ cache layer نفسه بيرفض keys من غير prefix tenant.

2: عميل enterprise عايز «backup و restore للـ tenant بتاعنا بس» وانتوا shared schema. إيه الخيارات؟

الحل: (1) logical export/import per tenant (كل الجداول بـ tenant_id + blobs + vectors) كـ feature مختبرة. (2) نقله لـ silo DB (placement) لو العقد يبرر التكلفة. (3) PITR للـ DB كلها مش حل لأنه بيرجّع كل الـ tenants. القرار في ADR مع تكلفة الـ silo في الـ pricing.

3: Job بيبعت تقارير شهرية لكل tenants، وحد بلّغ إنه استلم تقرير شركة تانية. فين تدوّر؟

الحل: الـ job كان بيستخدم DbContext واحد (scoped للـ job) وبيلف على الـ tenants ← TenantContext اتضبط مرة واحدة أو الـ cache بتاع الـ filter. الإصلاح: scope جديد (DbContext جديد) لكل tenant، والـ email recipient يتجاب من نفس الـ scope، و test بيشغل الـ job على tenantين ويتأكد من الفصل.

12

Mini project: Tenant isolation kit

Mini project
Practical

للـ CAPSTONE/: membership model، middleware الـ resolution، AppDb بالفلاتر التلقائية والـ TenantId immutable، RLS بـ FORCE و roles منفصلة، rate limiter per tenant، fair queue للـ ingestion، و IsolationMatrixTests على Testcontainers. معيار القبول: شيل الـ global filter عمدًا ← RLS لسه بيمنع التسريب والـ tests بتعدي؛ شيل RLS كمان ← الـ tests تفشل.

13

أسئلة إنترفيو: Junior → Senior → Staff

Interview ladder
Basics
(Junior) ليه ما نثقش في X-Tenant-Id header؟
لأنه input من العميل؛ ممكن يتغير. هو selector بس، والصلاحية من الـ membership في الـ DB للـ user المصادَق عليه.
(Senior) Global query filters كفاية للعزل؟
لأ. بيغطي LINQ بس؛ raw SQL و reports و IgnoreQueryFilters والـ jobs والـ caches والـ vectors برّه. defense in depth: RLS، cache keys بالـ tenant، tests لكل data path.
(Senior) إزاي تتعامل مع noisy neighbor في AI ingestion؟
Fair queueing per tenant (weighted حسب الخطة)، concurrency limits per tenant، rate limits، budgets للـ AI، ومراقبة queue age لكل tenant.
(Staff) صمم tenancy لـ SaaS هيبيع لـ SMBs و banks في 3 regions.
Cells لكل region (residency)، جوه كل cell pool مشترك بـ RLS للـ SMBs و silos للبنوك، control plane للـ placement والـ routing، نفس الكود والـ migrations للكل مع orchestrated rollout، و pricing بيعكس تكلفة الـ silo. و ADR بمعايير الانتقال من pool لـ silo.
↗

المراجع والقراءة الإضافية

References & further reading

الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

مصادر تعليمية ومتقدمة — Third-party & advanced reading

خريطة التغطية: 18 عنصر من الـ Roadmap ومكان شرحه في الدرس
New sectionTenancy Models (shared DB / schema / DB per tenant)§01
New sectionTenant Isolation§01
New sectionTenant Resolution (subdomain, header, claim)§01
New sectionEF Core Global Query Filters§01
New sectionTenant-Level Permissions§02
SuggestedTenancy Models (shared DB / schema / DB per tenant)§02
SuggestedTenant Isolation§02
SuggestedTenant Resolution (subdomain, header, claim)§02
SuggestedEF Core Global Query Filters§03
SuggestedTenant-Level Permissions§03
SuggestedUsage Quotas§03
SuggestedRate Limits Per Tenant§04
SuggestedSubscription Plans§04
SuggestedAI Usage Tracking§04
SuggestedCost Isolation§05
SuggestedBilling Fundamentals§05
SuggestedRow-Level Security (PostgreSQL)§05
SuggestedEnterprise SSO§06

خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.

محتويات الدرس