Multi-tenant product platforms must answer two questions on every request: who is this user, and which organization's data may they touch? Weak answers produce cross-tenant data leaks, unusable audit trails, and SSO projects that stall when the first enterprise customer asks for SAML claim mapping.
DarDev operates several customer-facing products—Hesabi for Tunisian SME finance, DarDevLab for cloud-native training, EscaHire on waitlist, plus GitLab, Grafana, and internal admin tools—each serving many tenants from shared infrastructure. This guide explains the identity and tenancy patterns we apply and extend through Workspace, our zero-trust IAM layer on the Authorize step of the platform pipeline.
What tenant means in a product stack
A tenant is the billing and data-isolation boundary—usually a company or workspace—not a single login. Users belong to one or more tenants through membership records; authorization is always evaluated as user plus tenant plus role. Sessions must carry a stable tenant identifier (organization ID, workspace slug, or server-validated switch token) so every API handler, queue worker, and nightly export scopes queries the same way.
- Organization is the default tenant key for B2B SaaS
- Teams or branches nest under org scope—they do not replace it
- Platform operators use separate break-glass paths with stronger logging
- Machine clients (CI jobs, webhooks, sync workers) get scoped service principals per tenant
Treat tenant context as mandatory middleware, not an optional query parameter. If a route accepts an org ID from the client without verifying membership, you will eventually ship an insecure direct object reference. Whether you enforce scope with PostgreSQL row-level security, ORM middleware, or explicit WHERE clauses in every repository method, the invariant is the same: no unscoped reads or writes.
Isolation models and when to choose each
Shared database with a tenant_id column is the right default for homogenous schemas and moderate tenant counts. Schema-per-tenant or database-per-tenant adds migration and backup complexity but helps regulated customers or noisy-neighbor risk. DarDev products today use shared Postgres with strict tenant scoping; we document dedicated resources only when a contract explicitly requires them.
- Shared DB plus tenant_id: fastest iteration, demands query discipline
- Schema-per-tenant: stronger logical separation, heavier migrations
- Database-per-tenant: maximum isolation, highest operational cost
- Object storage prefixes and cache keys must mirror the same tenant key as the database
Pick the model before you optimize signup UX. Retrofitting tenant_id into tables that were built single-tenant is painful; so is explaining to an auditor why support staff can query any customer without a logged impersonation session.
Authentication patterns that survive SSO rollouts
- Centralize IdP configuration
Start with OIDC for modern identity providers; add SAML where enterprise customers require it. Keep client secrets and redirect URIs in Workspace—or one identity service—not scattered across microservice repos.
- Issue short-lived tokens with tenant claims
Access tokens should carry sub, audience, and tenant_id or an explicit org list. Refresh tokens stay httpOnly. Never rely on a tenant choice stored only in browser localStorage without a server round-trip.
- Separate human login from machine credentials
Pipelines and background workers use scoped API keys or workload identity, not cloned admin passwords. Our zero-trust IAM for internal SaaS guide covers service-to-service boundaries inside the cluster.
- Design org switching as a server action
Changing active tenant must re-issue session context on the server. Client-only switches cause support tickets and accidental cross-tenant UI states.
- Log auth events per tenant
Failed logins, MFA enrollment, role changes, and impersonation sessions belong in immutable audit streams keyed by tenant for later compliance questions.
Identity in the DarDev platform pipeline
Workspace sits on the Authorize step after Build and Deploy: human-facing admin surfaces and several customer apps federate through one identity plane instead of duplicating LDAP every time we ship a product. That keeps group mappings consistent when a engineer moves from DarDevLab course admin to Grafana viewer to a custom Node service. See Workspace in the DarDev pipeline (Authorize step) for how Authorize connects to Observe and the rest of the stack.
Cross-app SSO follows the same rules: one canonical subject ID per person, group membership derived from tenant role tables, and no shared session cookies across unrelated apex domains. Our SSO across GitLab, Grafana, and custom apps article covers redirect URIs, group sync, and least-privilege Grafana org roles without granting cluster-admin shortcuts.
Internal admin tooling—CRM, campaign prep, sync workers—needs tighter session policy than customer apps: shorter idle timeouts, step-up authentication for destructive actions, and optional IP allow lists. Session security patterns for admin tools explains rotation, fixation risks, and break-glass accounts in detail.
Rollout checklist for your next tenant feature
- Inventory every actor
Humans, service accounts, webhooks, and support impersonation (if you allow it) each need a documented credential type.
- Define tenant lifecycle
Signup, invite, suspend, export, and delete—with retention rules per product. Deletion must cascade object storage and search indexes, not only SQL rows.
- Map roles to API permissions
Avoid a super-admin role inside tenant scope. Platform operators should live outside tenant RBAC with auditable elevation.
- Automate cross-tenant tests
CI should prove that Tenant A tokens cannot read Tenant B records. These tests catch regressions faster than penetration tests once a year.
- Publish IdP onboarding docs early
Enterprise buyers ask for metadata URLs, claim mapping, SCIM timing, and logout behavior before they sign. Answer in a runbook, not in Slack threads.
Common mistakes
- Trusting tenant_id from the frontend after login without server validation
- Reusing OAuth client secrets across staging and production
- Support tools that query without a tenant filter for one urgent ticket
- Embedding bespoke auth in each repo instead of routing through Workspace
- Launching SSO before group sync, logout, and session revocation are tested
How Workspace helps
Workspace provides zero-trust IAM and SSO as DarDev's Authorize layer—central OIDC and SAML configuration, group sync into GitLab and Grafana, and patterns we reuse as we add products. Visit dardev.net/products for positioning, and subscribe to Workspace marketing updates at mail.dardev.net/subscribe/workspace-marketing.html if you are evaluating federated identity for your own multi-tenant stack.
What is the minimum viable multi-tenant identity model?
A single IdP, org-scoped membership tables, tenant_id on every business row, middleware that rejects missing tenant context, and audit logs keyed by organization. Add SAML and SCIM when enterprise deals require them—not on day one unless sales already promised them.
Should each DarDev product have its own user database?
Products keep their own business data and role models, but human authentication should federate through Workspace where possible. Duplicating passwords per product increases reset friction and makes SSO projects multiply.
How do service accounts fit tenancy?
Issue machine credentials scoped to one tenant and one API surface. A Twenty sync worker or Listmonk automation should not use a human admin session or a platform-wide root key.
Where does zero-trust fit?
Assume breach: short-lived tokens, mTLS or network policy between services, and no implicit trust based on internal IP alone. Pair this guide with zero-trust IAM for internal SaaS for service-to-service rules inside Kubernetes.
What should we implement first this sprint?
Add tenant-scoped integration tests, document your org-switch flow, and centralize one OIDC client in Workspace. Those three items prevent the most common production incidents we see in multi-tenant rollouts.
