Tenant Isolation Test Strategy¶
Generated: 2025-11-22 | Version: 1.0 Scope: Multi-tenant data access, authorization, and cross-tenant leakage prevention for Core HR MVP.
1. Objectives¶
- Guarantee strict logical isolation: no data from Tenant B visible/alterable by Tenant A sessions.
- Detect accidental leakage early (queries missing tenant predicate, cache pollution, IDOR risks).
- Provide repeatable automated suite integrated in CI (blocking severity for failures).
2. Isolation Dimensions¶
| Dimension | Description | Example Risk |
|---|---|---|
| Data Read | Query returns only tenant-scoped rows | SELECT * without tenant filter returns foreign employees |
| Data Write | Writes cannot target other tenant resources | Updating employee of another tenant via guessed ID |
| Cache | Shared cache entries namespaced by tenant | Cached employee list reused across tenants |
| Search/Index | Full-text / search results restricted | Global search returning other tenant documents |
| Async Events | Message consumption processes only tenant-scoped payload | Accrual job processes other tenant balances |
| Access Control | Role checks scoped per-tenant | Admin role from Tenant A applied in Tenant B |
3. Test Layers¶
| Layer | Tooling | Purpose |
|---|---|---|
| Unit | ORM/Repository tests | Enforce tenant predicate presence |
| Integration | API + DB container | Validate end-to-end isolation on CRUD endpoints |
| E2E | Browser/headless | Session switching checks (multi-tenant user) |
| Security | Dynamic scans / IDOR probes | Attempt cross-tenant ID access |
| Observability | Log/event assertion | Ensure tenantId always populated post-auth |
4. Core Scenarios¶
| ID | Scenario | Layer | Automation Priority |
|---|---|---|---|
| ISO-READ-01 | Employee read returns only tenant rows | Integration | High |
| ISO-READ-02 | Document metadata list scoped | Integration | High |
| ISO-WRITE-01 | Cross-tenant update blocked (403/404) | Integration | High |
| ISO-CACHE-01 | Cached profile list differs between tenants | Integration | Medium |
| ISO-IDOR-01 | Sequential ID enumeration fails for foreign tenant | Security | High |
| ISO-MULTI-01 | Multi-tenant user switching resets context | E2E | Medium |
| ISO-EVENT-01 | Accrual job processes only target tenant employees | Integration | High |
| ISO-LOG-01 | Logs contain tenantId for post-provision requests | Observability | Medium |
5. Data Setup Strategy¶
- Fixture generator creates N tenants (e.g. 3) each with sample employees.
- Use randomized IDs (UUID) to reduce enumeration success likelihood but still test for logic flaws ignoring tenant filtering.
- For IDOR tests: attempt direct GET on UUIDs belonging to other tenants; expect 404 or 403 (choose consistent pattern).
6. Repository / Query Guardrails¶
Implement automated repository rule tests:
1. Reflection-based scan ensures each query builder includes tenant predicate (WHERE tenant_id = ?).
2. If dynamic multi-tenant bypass is needed (e.g., super admin), require explicit flag & test verifying logging of privileged access.
7. Cache Namespacing Rules¶
- All cache keys prefixed:
tenant:{tenantId}:<entity>:<suffix>. - Test invalidation separately per tenant; ensure one tenant’s profile updates do not flush another tenant’s cache.
8. Async Processing Isolation¶
- Accrual job receives tenantId as parameter; test harness runs job twice for different tenants and asserts no cross modifications.
- Event consumer includes tenantId attribute check before applying updates; missing tenantId triggers WARN & discard.
9. Security / IDOR Tests¶
Automated script attempts: - Direct API calls with swapped tenantId in path/query. - Omitted tenantId → expect server to derive from auth context not fallback to global. - Modified resource IDs from another tenant; verify generic not-found (avoid revealing existence).
10. Observability Assertions¶
- Every INFO+ log line post-auth must include tenantId (spot check sampling).
- Trace spans contain
tenant.idattribute; failing spans flagged. - Analytics events without tenantId after provisioning cause test failure (except pre-provision events like SignupStarted).
11. Metrics & Thresholds¶
| Metric | Target |
|---|---|
| Isolation test pass rate | 100% |
| False positives (allowed cross-tenant) | 0 |
| Time to run isolation suite | < 2 minutes |
| Tenant predicate coverage (repository scan) | 100% queries |
12. Failure Handling & Reporting¶
- CI marks isolation suite failures as blocking.
- Report includes offending query signature, endpoint, and missing predicate details.
- Slack/alert integration for any ISO-* failure on main branch.
13. Tooling Choices (Suggested)¶
- Integration: Postman/Newman or REST-assured style tests (language-specific) + dockerized DB.
- Security/IDOR: Lightweight custom script or ZAP baseline scan with target focusing on enumeration endpoints.
- Repository scan: AST or reflection enumeration depending on language/ORM.
- Cache tests: Local in-memory or Redis instance with isolated keys.
14. Roadmap Enhancements¶
- Add differential privacy checks (ensure analytic aggregates not leaking tenant-specific patterns when combined).
- Introduce chaos testing: simulate mixed concurrent requests from multiple tenants.
- Automated pen test integration pre-release (external tool).
15. Open Questions¶
- Standard response for cross-tenant access attempt: 403 vs 404? (Leaning 404 to reduce resource enumeration.)
- Super admin observation: log format distinct enough? Need
privileged=trueattribute? - Do we require tenant-level rate limits early (prevent noisy neighbor)?
Document Version: 1.0