⌘ The Architecture Reference

Cld saas · Cloud & SaaS · Intermediate

Tenant Onboarding and Identity

Start with onboarding and identity: a fully automated front door that binds every user to a tenant and carries tenant context downstream as a JWT.

Cld saas Intermediate ⏱ 5 min read Complete

🧭 Analogy

Checking into a hotel chain is onboarding: one smooth process issues your key card, registers your stay, sets up billing, and that card silently carries your identity to every door, the gym, and the restaurant. You never re-prove who you are. A great SaaS onboarding is that key card — issued once, automatically, and it carries tenant context everywhere you go.

Where do you start? Onboarding and identity

For both greenfield and migrating teams, the answer to “where do you start?” is onboarding, identity, and the control plane. This puts tenancy “front and center” from day one and avoids the trap of building the application first and bolting tenancy on later. Onboarding is part of your service, not a bolt-on — it shapes first impressions and time to value, and it is where deployment, identity, routing, and tiering strategies are put into action. The bar is identical for self-service (B2C) and internal (B2B): fully automated, repeatable, low-friction, with no one-off configuration.

The baseline environment

Before onboarding any tenant, teams provision a baseline environment via DevOps automation: foundational networking (VPC, AZs, subnets), the control plane itself, pooled resources shared by all tenants, the system admin identity, and the system admin console — a purpose-built single pane of glass (monitor onboarding status, activate/deactivate tenants, manage policies, view metrics). System admin identities are kept entirely separate from tenant identities.

The onboarding flow

graph TD
RQ["Receive onboarding request"] --> CT["Create tenant<br/>(GUID, active=false)"]
CT --> PR["Provision tenant resources<br/>(full silo vs. minimal pool)"]
PR --> BI["Add to billing"]
BI --> CU["Create tenant admin user"]
CU --> AC["Set active=true on full success"]
CT -. tracks .-> ST["States: TENANT_CREATED,<br/>BILLING_INITIALIZED,<br/>TENANT_ACTIVATED"]

A single Onboarding service orchestrates the flow, tracking granular states. The provisioning step is potentially the heaviest — SaaS “blurs the DevOps boundaries” by running provisioning at runtime. Tier-based onboarding applies per-resource tier policies (premium → full silo, basic → pool, mixed mode per-resource), with a bias toward pre-provisioning pooled resources at baseline. Track onboarded resources so later deployments find every per-tenant deployment, and handle failures with fault tolerance (e.g., async billing via a queue with retries).

SaaS identity

Every user is authenticated in a tenant's context

Authentication must produce a SaaS identity — a binding of a user identity to a tenant identity that conveys tenant context through all layers. Golding focuses on OAuth/OIDC: authentication returns JWTs carrying claims; tenant attributes (tenant ID, role, tier) are added as custom claims, and the enriched token cascades downstream as a bearer token.

graph LR
U["User identity"] --> AUTH["OAuth / OIDC authentication"]
T["Tenant identity"] --> AUTH
AUTH --> JWT["JWT with custom claims<br/>(tenant ID, role, tier)"]
JWT --> RT["Routing"]
JWT --> LG["Logging and metrics"]
JWT --> DA["Data access"]

Guidance for getting identity right:

  • Configure the IdP with custom attributes before onboarding and populate them per user.
  • Use custom claims judiciously — don’t put volatile app access-control attributes there.
  • Support federated identity (customer-hosted IdPs), often via an authentication manager that stitches tenant context into third-party tokens (e.g., Amazon Cognito User Pools — pool-per-tenant or a shared pool with groups).

Never resolve tenant context via a runtime lookup

Never require a service to call an external Tenant Mapping service to resolve tenant context — it becomes a point of scale and failure. This is precisely why critical attributes live in the JWT. And remember: tenant authentication is not tenant isolation — isolation is a separate layer built atop tenant context (see tenant isolation models).

Front-door access and routing

Tenants “enter the front door” via a tenant domain (subdomain-per-tenant, or vanity domains supporting white-labeling, resolved through a Tenant Mapping layer) or a single shared domain (common in B2C, where tenant resolution uses the user’s email domain or a lookup table). Beware the Man in the Middle Challenge: injecting tenant-mapping indirection before the IdP conflicts with the elegant classic auth flow and adds a point of scale and failure. Routing then maps authenticated tenants to resources per request — and the more siloed constructs you introduce, the more you must weigh scalability against cost.

See also

When to use it — and when not

✅ Reach for it when

  • Deciding where to begin a greenfield or migrating SaaS build
  • Designing a frictionless, fully automated onboarding flow
  • Binding user identity to tenant identity and conveying tenant context

⛔ Think twice when

  • Building the application first and bolting tenancy on later
  • Requiring a service to call an external tenant-mapping service to resolve context at runtime
  • Putting volatile access-control attributes into JWT custom claims
cld-saasControl Plane vs. Application Plane

Every SaaS environment divides into a control plane that orchestrates all tenants and an application plane where the multi-tenant product features live.

cld-saasSaaS Foundations

SaaS is a business model first — a unified, single-version service experience for tenants — and multi-tenancy means collective management, not necessarily shared infrastructure.

cld-saasTenant Isolation Models

Silo, pool, and bridge express how resources map to tenants — but deployment is not isolation; true isolation needs a separate gatekeeper scoped by tenant context.

Check your understanding

Score: 0 / 4

1. Where should a greenfield or migrating SaaS team start?

Starting here puts tenancy front and center and avoids the trap of building the app first and bolting tenancy on later.

2. What is the SaaS identity?

Every authenticated user must be authenticated in the context of a tenant; tenant attributes are added as custom claims to the JWT.

3. Why should you never require a service to call an external Tenant Mapping service at runtime to resolve context?

That is why critical tenant attributes live in the JWT — resolving context per request via an external lookup creates a bottleneck.

4. Is tenant authentication the same as tenant isolation?

Authentication establishes who the user is and their tenant; isolation is a distinct mechanism that scopes resource access by that tenant context.

Comments

Sign in with GitHub to join the discussion.