Selling to businesses changes the identity problem completely. The person signing in is never just a person; they are a person belonging to a company.

When you sell to individual consumers, identity is simple to describe: one person, one account. When you sell to businesses, every account lives inside a business context. The same human might belong to two customers, as a consultant working for both. A company might have a hundred users or a hundred thousand. One company might insist its people sign in with the company’s own directory, while another is happy with passwords. One company’s administrator should manage their own people but must never glimpse anyone else’s.

What goes wrong without a plan

• Data leaks between customers: the most feared failure in any multi-tenant product, usually caused by a missing business check somewhere in the code.
• Onboarding bottlenecks: every new customer needs hand-built sign-in configuration, so sales outpace engineering.
• Lost deals: large customers refuse to buy if their staff cannot use their corporate sign-in or if departing employees keep access.
• Support overload: without self-service, customer administrators open tickets for every small change.
• Unscalable design: an approach that works for ten customers collapses at a thousand.

What good design gives you

A thoughtful multi-tenant identity design lets you onboard a new business in hours instead of weeks, lets customers manage their own people, makes every request carry a trustworthy statement of which business it belongs to, and keeps isolation strong even when developers make mistakes. These benefits compound as you grow.

flowchart TD
    P["Your product"] --> A["Customer A
staff and admins"]
    P --> B["Customer B
staff and admins"]
    P --> C["Customer C
staff and admins"]
    ID["Identity layer
who belongs where"] --> P
    

Figure 1 shows the basic picture. One product sits in the middle and serves several business customers. The identity layer is what tells the product which business each person belongs to. Everything else in this guide expands on that single idea.

A small vocabulary unlocks the rest. Read the table once, then return whenever a word feels unfamiliar.

Two meanings of the word tenant

The word tenant causes more confusion than any other in this subject, because it has two meanings. In Okta and Auth0 language, a tenant is your private account space in the identity service, containing your settings, applications, and users. In product language, a tenant is one of your customer businesses. In this guide, when we mean the first we say “identity tenant” or “your tenant”, and when we mean the second we say “customer”, “business”, or “customer tenant”. Mixing the two up in a design meeting leads to hours of confusion.

Authentication, authorization, and tenancy

Authentication asks “who are you?” Authorization asks “what may you do?” Multi-tenancy adds a third question: “on whose behalf are you acting?” A consultant who works for two customers is the same person but acts in different business contexts at different times, with different permissions in each. Good design makes the business context explicit in every request.

flowchart LR
    W["Who are you?
authentication"] --> T["For which business?
tenancy context"]
    T --> A["What may you do there?
authorization"]
    A --> D["Allow or deny"]
    

Figure 2 gives the order. First prove identity, then establish which business is in play, and only then decide permissions. Skipping the middle step is the root of most cross-customer leaks.

Okta has more than one family of products. B2B customer identity draws mainly on the customer-facing side.

Okta is widely known for workforce identity, which manages how a company’s own employees sign in to the tools they use. Its customer-facing side, which grew from the Auth0 platform, is built for products used by the public and by business customers. A B2B product usually builds on the customer-facing side, because the people signing in are customers’ employees, not your own.

A common and important situation

Many of your enterprise customers will already use some corporate identity system, and a good share may use Okta’s workforce product themselves. You are then sitting between two Okta-related worlds: your customer’s workforce identity on one side and your customer identity service on the other. Understanding that these are separate systems, linked by standards, keeps the picture clear. Your customer’s administrators control who their staff are and how they prove themselves. Your service controls what your product allows.

flowchart LR
    CU["Customer's staff"] --> CIDP["Customer's own
identity system"]
    CIDP -->|"federation"| CIC["Your customer
identity service"]
    CIC --> PROD["Your product"]
    

Figure 3 shows the chain of trust. The customer’s staff sign in with the customer’s own system. Your identity service trusts that system through federation and passes a consistent result to your product.

Before choosing tools, decide how separate your customers should be. This single decision shapes cost, risk, and effort.

Software architects describe three broad shapes for multi-tenant products. They differ in how much each customer shares with the others. The same ideas apply to identity.

How the models apply to identity

• Silo identity: one identity tenant per customer. Very strong separation, but heavy to manage.
• Pool identity: one identity tenant for all customers, with organizations separating them logically.
• Bridge identity: a shared identity tenant for most customers, with dedicated tenants for a few special ones, such as regulated or very large customers.

Why most products choose pool or bridge

Creating a separate identity tenant for each customer sounds safe, but at hundreds or thousands of customers it becomes unmanageable: every change must be repeated everywhere, every upgrade multiplied, every security review stretched. Most B2B products therefore start with a pooled design, using organizations to separate customers, and keep the option of a dedicated tenant for the rare customer with extreme requirements.

flowchart TD
    Q{"How different are
your customers' needs?"}
    Q -->|"very similar, many customers"| PL["Pool
one tenant, many organizations"]
    Q -->|"few, huge, very demanding"| SI["Silo
tenant per customer"]
    Q -->|"mostly similar, a few special"| BR["Bridge
shared plus dedicated"]
    

Figure 4 gives a simple way to choose. Many similar customers point to pooling. A few very demanding customers point to silos. A mixed audience points to a bridge.

The practical question for most teams: do we create one identity tenant for everyone, or one per customer?

Having chosen a general model, you must now decide how to organize the identity tenant itself. Think of it as choosing between one large building with many offices or many small buildings.

The single shared identity tenant

A tenant per customer

Giving each customer a separate identity tenant provides complete separation of configuration, users, logs, and limits. It makes sense when customers demand it contractually or when only a handful of very large customers exist. Beyond that, the operational burden grows quickly: each tenant needs its own settings, monitoring, certificates, and updates.

A sensible default

For most B2B products, the sensible default is one shared identity tenant per environment, with an organization for each customer, and dedicated tenants only for exceptional cases. Always check current documentation on organization limits and features for your plan before committing, because these determine how far the pooled approach can stretch.

Do not forget environments

Whichever choice you make, keep separate identity tenants for development, testing, and production, as with any serious system. The question of one tenant or many applies within each environment.

flowchart LR
    subgraph POOL["Pooled design"]
        T1["One identity tenant"] --> O1["Org: Customer A"]
        T1 --> O2["Org: Customer B"]
        T1 --> O3["Org: Customer C"]
    end
    subgraph SILO["Siloed design"]
        TA["Tenant A"] --> OA["Customer A"]
        TB["Tenant B"] --> OB["Customer B"]
        TC["Tenant C"] --> OC["Customer C"]
    end
    

Figure 5 contrasts the two. The pooled design has one configuration to maintain. The siloed design has as many configurations as customers. The choice determines how much work you do for each new customer.

Organizations are the identity service’s way of representing your customer businesses.

An organization is a grouping inside your identity tenant that stands for one customer business. It holds the list of members, the roles those members have, and the sign-in options available to that business. It is the identity-side twin of the customer record in your product.

What an organization holds

• Identity of the business: a stable identifier and a display name.
• Members: the people who belong, each with roles specific to that business.
• Connections: the sign-in options this business may use, such as its corporate directory.
• Invitations: pending offers for new people to join.
• Branding: optional appearance tailored to the business.

People can belong to several organizations

A single human might be a member of more than one business, for example a consultant, an auditor, or an agency worker. The model handles this by letting one user have membership in several organizations, with separate roles in each. When that person signs in, the context must specify which business they are acting for, either chosen by them or inferred from where they came from.

The link to your own customer record

Your product already has its own record for each customer: billing details, plan, settings. Link each organization to that record using a stable identifier that never changes, even if the business renames itself. Do not use the display name as the link. A name can change; an identifier should not.

Lifecycle of an organization

flowchart TD
    TEN["Identity tenant"] --> OA["Organization A"]
    TEN --> OB["Organization B"]
    OA --> MA1["Member 1: admin"]
    OA --> MA2["Member 2: user"]
    OB --> MB1["Member 2: viewer"]
    OB --> MB3["Member 3: admin"]
    

Figure 6 shows a person who is an ordinary user in Organization A and a viewer in Organization B. Their permissions depend on the business context, not on the person alone.

Large customers want their staff to sign in with the accounts they already use at work. Federation makes that possible.

Federation means trusting another system’s sign-in. Instead of asking a customer’s employee to create yet another password for your product, you send them to the customer’s own corporate sign-in. The customer’s system confirms who the person is and sends back a signed statement. Your identity service checks the statement and lets them in. Nobody new needs to be created or remembered by the customer, and when the person leaves the company, their access ends automatically.

Why enterprises insist on it

• One set of credentials: staff do not juggle another password.
• Central control: the customer’s security team applies its own rules, such as multi-factor requirements, to your product too.
• Instant offboarding: disabling a person at the company ends their access to your product.
• Audit trail: the customer’s sign-in logs record access.
• Procurement checklists: many security questionnaires ask whether single sign-on is supported.

The standards behind it

Two families of open standards dominate. One, older and very common in large enterprises, exchanges signed documents between the customer’s system and yours. The other, newer and built on the same modern foundations as general web sign-in, exchanges signed tokens. A good customer identity service supports both, so you can accept whatever your customer’s system speaks. Check current documentation for the exact protocols and options available on your plan.

The trust relationship

Federation depends on a trust set up in advance. Each side exchanges a small amount of configuration: where to send people, how to check signatures, and what information to include. This is a one-time setup per customer, which is why self-service configuration (covered later) matters so much at scale.

sequenceDiagram
    participant E as Customer employee
    participant P as Your product
    participant S as Your identity service
    participant C as Customer's identity system
    E->>P: Open product, press Sign in
    P->>S: Send to hosted sign-in
    S->>C: Redirect to customer's sign-in
    E->>C: Prove who they are
    C->>S: Signed statement about employee
    S->>P: Tokens with identity and business context
    P->>E: Signed in
    

Figure 7 shows the journey. Your product never sees a password. Your identity service acts as a trusted middleman between your product and every customer’s own system.

Certificates and expiry

Federation depends on signing keys and certificates that eventually expire. When a customer renews theirs without telling you, their staff suddenly cannot sign in, and the customer blames your product. Build a habit of recording expiry dates for every connection, alerting well ahead of time, and giving customers an easy way to upload a new certificate. This simple discipline prevents a large share of enterprise support tickets.

When thousands of businesses have their own sign-in, the first question at the door is: which one is yours?

When someone arrives at your sign-in page, your service must work out which method they should use. A person from one customer needs to be sent to that customer’s corporate system. A person from another should use a password. Someone from a third may use a social account. Working this out is called home realm discovery, because you are finding the person’s “home” place of identity.

Common ways to discover the home realm

Privacy and security cautions

Do not reveal which businesses are your customers to strangers. A drop-down list of every customer is a gift to attackers and competitors. Prefer methods that reveal nothing until the person has given some identifying hint. Also remember that anyone can type any email address, so routing by domain is a convenience, not proof; the actual proof comes from the customer’s system after redirect.

When domains are not enough

Some companies have several email domains. Some domains are shared among several customers, such as free consumer email services. Some people use personal addresses with business accounts. Your design must handle these cases gracefully, usually by letting a customer register all their domains, forbidding public domains for enterprise routing, and offering a fallback path for exceptions.

flowchart TD
    A["Person arrives"] --> B{"Business known
from link or invite?"}
    B -->|"yes"| R["Use that business's sign-in"]
    B -->|"no"| C["Ask for email"]
    C --> D{"Domain registered
to a customer?"}
    D -->|"yes"| R
    D -->|"no"| E["Offer default sign-in
or business picker"]
    

Figure 8 shows a layered approach. A known link or invite wins. Otherwise the email domain decides. If neither works, a safe fallback offers a default path.

Every request to your product must say which business it is for, in a way that cannot be forged.

After sign-in, your product receives tokens. These are small, digitally signed messages. If a token includes a statement of which organization the person is acting for, your product can trust it, because the signature proves the identity service wrote it. This statement, often called the tenant claim, is the foundation of isolation in the product.

What belongs in tenant-aware tokens

• The organization identifier: a stable code for the business in play.
• The person’s identifier: who is acting.
• Roles within that organization: what they may do there.
• Little else: keep tokens small and avoid personal details that many systems could see.

Never trust the client to choose the tenant

One of the most dangerous mistakes is letting the client, the browser or app, tell the server which business it is acting for in an ordinary request parameter, and believing it. A malicious user could simply change the value and view another business’s data. The server must take the business context from the verified token, never from something the user can freely edit. If a person can legitimately switch between businesses, the switch should go through the identity service, producing a fresh token for the chosen business.

Switching context

People who belong to several organizations need a clean way to switch. A common approach is to ask the identity service for new tokens naming the chosen organization, after checking that the person is truly a member. The old tokens are not simply edited. Each token is tied to exactly one business context.

Audience and issuer checks

Your back-end must also check that each token was meant for it and was issued by your identity service. Without these checks, tokens from another system, or tokens meant for a different API, could be accepted by mistake.

sequenceDiagram
    participant U as User
    participant I as Identity service
    participant A as Your API
    participant D as Data store
    U->>I: Sign in, choose business
    I->>U: Token naming business and roles
    U->>A: Request with token
    A->>A: Verify signature, audience, expiry
    A->>D: Query using business from token
    D->>A: Only that business's data
    A->>U: Response
    

Figure 9 shows the chain of trust. The business context comes from the signed token. The API checks it, and every data request is limited by it. Nothing in the chain relies on a value the user can freely change.

Keeping tokens small and safe

It is tempting to put every detail about a person and their business into a token so the product never has to look anything up. Resist. Large tokens slow every request, reveal information to every system that handles them, and go stale when roles change. Include the tenant identifier, the person identifier, and the roles, and let your product fetch richer details from its own data when needed.

Inside each business, people hold different powers. The business’s own administrators should manage them.

A permission is one allowed action. A role is a named bundle of permissions. In a multi-tenant product, roles are given per business: a person can be an administrator in one customer and a read-only viewer in another. Roles therefore attach to the membership, not the person.

Layers of roles

Delegated administration

Delegated administration means giving the customer’s own administrators the power to manage their people, without contacting you. They can invite colleagues, assign roles, connect their corporate sign-in, and remove leavers. This is essential for scale, since your support team cannot field every request from every customer. It must be bounded: customer administrators can act only within their own business, and cannot grant themselves powers beyond what you allow.

Coarse in identity, fine in the product

A useful rule: keep broad role decisions in the identity service, such as “administrator” or “viewer”, and keep fine-grained, data-dependent decisions in your product, such as “may this person edit this specific project”. Detailed business rules rarely belong in the identity tenant, because they depend on data the identity service does not hold.

Your own staff and customer data

Your support and operations staff sometimes need to help a customer. Give them a separate, tightly controlled way of acting, ideally requiring the customer’s consent or a recorded reason, with every such access logged and reviewed. Never give platform staff silent access to everything because it is convenient.

flowchart TD
    PO["Platform operators
your staff"] --> RULES["Tightly controlled,
logged access"]
    CA["Customer admin"] --> MG["Manage own members and roles"]
    CP["Power user"] --> FE["Broader features"]
    CU["Ordinary user"] --> EV["Everyday use"]
    RO["Read-only"] --> VW["View only"]
    MG --> ONLY["Only within own business"]
    

Figure 10 shows how powers are layered. Customer administrators are strong inside their business and powerless outside it. Platform staff sit under careful controls.

The speed of onboarding a new business decides how fast you can grow.

Imagine a sales team that closes ten new customers in a month. If each needs a week of manual identity configuration by your engineers, you have a problem. A scalable design turns onboarding into a repeatable procedure, as much as possible done by the customer themselves.

A typical onboarding journey

Why domain verification matters

If a customer can claim any email domain without proof, an attacker could claim someone else’s domain and then capture sign-ins from that company. Require proof of control, such as a record the customer must place in their public domain settings, before routing people by that domain.

Build a good wizard

The best self-service flows explain each step in plain language, show exactly what information is needed from the customer’s identity team, offer a test button, and give helpful error messages. Provide a clear, printable guide that the customer’s administrator can hand to their identity engineers, who may know nothing about your product.

flowchart LR
    S["Sale"] --> O["Organization created"]
    O --> I["Admin invited"]
    I --> W["Setup wizard"]
    W --> F["Federation connected and tested"]
    F --> DV["Domain verified"]
    DV --> U["Users join"]
    U --> L["Live"]
    

Figure 11 shows the conveyor belt of onboarding. Each stage can be automated or guided, so your team’s effort per customer drops sharply.

People join, change roles, and leave. Accounts must follow, or yesterday’s employee keeps today’s access.

Provisioning is the automatic creation, updating, and removal of accounts. In a B2B setting, the source of truth about who works at a customer is the customer’s own directory, so the best design lets that directory drive your product’s user list.

Three common ways accounts appear

The leaver problem

Just-in-time creation handles arrivals well but does nothing about departures. If a person leaves the company and is disabled in the corporate directory, they can no longer sign in through federation, but any long-lived session or token may remain valid for some time. Directory-driven provisioning solves this by actively removing or disabling the account, and ending sessions, soon after the departure. For customers who care about this, which is most enterprises, offer it.

Mapping groups to roles

Customers often organize their staff into groups in their own directory. A good design lets the customer map their groups to your roles, so that adding a person to the “finance” group automatically gives them the matching role in your product. This keeps role management where the customer already does it.

Deprovisioning is also about data

When a person leaves, decide what happens to the work they created. Reassign ownership, keep audit records, and delete personal data as required by privacy rules. Plan these rules in advance rather than improvising when the first customer asks.

sequenceDiagram
    participant H as Customer HR
    participant D as Customer directory
    participant S as Your identity service
    participant P as Your product
    H->>D: Employee leaves
    D->>S: Disable account
    S->>S: End sessions, revoke refresh
    S->>P: Notify product of change
    P->>P: Reassign work, keep audit trail
    

Figure 12 shows end-to-end offboarding. A change in the customer’s directory removes access to your product quickly, without anyone contacting your support team.

Handling mistakes in the customer’s directory

Customers sometimes make errors: they delete a group by accident, rename it, or move many people at once. Because provisioning mirrors the directory, such mistakes can instantly remove access for large numbers of users. Consider safeguards, such as warnings or holds when an unusually large share of a customer’s users would be removed in one operation, and make restoring access quick once the customer fixes the problem.

A bird’s-eye view shows how the pieces fit together, and where each responsibility lives.

Picture the full system in layers. At the top are the customers’ staff and the devices they use. Below them sit the customer’s own identity systems, which vouch for their people. Your identity service stands in the middle, translating many customers’ sign-in methods into one consistent result. Your product consumes that result and enforces business isolation in its own data layer. Around all of this are monitoring, support tools, and onboarding flows.

flowchart TD
    ST["Customer staff"] --> HL["Hosted sign-in"]
    HL --> HR["Home realm discovery"]
    HR --> EC["Enterprise connection
to customer identity system"]
    HR --> DB["Database or social
connection"]
    EC --> OR["Organization context"]
    DB --> OR
    OR --> TK["Tokens with tenant claim and roles"]
    TK --> API["Product APIs verify tokens"]
    API --> DL["Tenant-isolated data layer"]
    HL --> LG["Logs and monitoring"]
    OB["Onboarding portal"] --> OR
    

Figure 13 gives the full picture. Notice that the tenant claim in the tokens is the link between identity and data: it is what makes the data layer’s isolation possible.

Shared responsibility

The identity provider secures its platform and keeps it available. You remain responsible for your configuration, your applications, your data isolation, and how you respond to incidents. Customers remain responsible for their own directories and who they allow in. Seeing the three-way split prevents the dangerous assumption that any one party handles everything.

Single points of failure

Your identity service is on the path of every sign-in. If it is unavailable, no customer can reach your product. Understand its availability commitments, plan how your product behaves when it is unreachable, and keep any custom code in the sign-in path small and reliable.

Identity tells your product which business a request belongs to. Isolation is what your product does with that fact.

Identity cannot protect customer data by itself. It can only state truthfully which business a request is for. Your product must then ensure that every read and write is limited to that business. This is the hardest part of multi-tenancy, because the failure mode is a single forgotten check.

Common data isolation strategies

Defence in depth

Rely on several layers rather than one. The application layer filters by business. The data store enforces its own rule as a second line. Automated tests probe for cross-business access. Logs record which business each request was for, so unusual cross-access patterns stand out. A single layer will occasionally fail; several layers rarely fail together.

Beware of identifiers that can be guessed

If records are identified by simple counting numbers, an attacker can try neighbouring numbers to reach other customers’ records. The proper defence is to check business ownership on every access, but hard-to-guess identifiers add an extra hurdle. Never rely on obscurity alone.

Caches, queues, and files

Isolation must extend beyond the main database. Caches, background job queues, search indexes, file storage, and exports are all places where one customer’s data can mix with another’s when keys do not include the business. Review each one with the same question: “can this ever return the wrong customer’s information?”

flowchart TD
    RQ["Request with token"] --> V["Verify token"]
    V --> TC["Extract tenant claim"]
    TC --> AL["Application layer
filters by tenant"]
    AL --> DS["Data store
row-level rule by tenant"]
    DS --> RS["Only that tenant's rows"]
    TC --> LG["Log tenant on every request"]
    

Figure 14 shows two independent checks guarding the same data. If a developer forgets the application filter, the data store’s own rule still protects the customer.

Different customers have different security rules. A flexible design accommodates them without custom work for each.

One customer may demand multi-factor authentication for every sign-in. Another may rely on their own corporate system’s checks and want no extra prompts from you. A third in a regulated industry may require stricter session limits. Your design should let each business choose within boundaries you set, so that security teams can align your product with their own policies.

Policies customers commonly want

• Require corporate sign-in only: block passwords for that business’s domain so everyone must use the corporate system.
• Require multi-factor authentication: either from your service or from the customer’s own, accepted as proof.
• Session length limits: shorter sessions for sensitive uses.
• Allowed locations or networks: restrict sign-in to approved places.
• Break-glass administrators: a few emergency accounts that work if the corporate system is down.

Trusting the customer’s multi-factor proof

If the customer’s own system already asked for a second factor, asking again in your product annoys users. Your service can accept a statement from the customer’s system that multi-factor authentication was done, if you trust that customer’s configuration. Decide in advance which customers’ statements you accept, and how you record the decision.

Defaults and guardrails

Give sensible defaults to every new business, so that a customer who never touches the settings is still protected. Add guardrails so that a customer administrator cannot weaken settings below a minimum you consider safe. A customer might otherwise disable protections in a moment of convenience and expose themselves and, indirectly, you.

flowchart LR
    DEF["Your safe defaults"] --> POL["Per-customer policy"]
    CAD["Customer admin choices
within limits"] --> POL
    POL --> SI["Sign-in decision"]
    SI --> A["Require corporate sign-in"]
    SI --> B["Require extra proof"]
    SI --> C["Apply session limits"]
    

Figure 15 shows the combination. Your defaults set the floor. Customer choices adjust within limits. The resulting policy shapes each sign-in decision.

Business customers like to see their own name and look, and trust a familiar address.

In a B2B product, the sign-in page is often the first thing a customer’s staff see. Seeing their company’s logo and colours builds confidence and reduces mistaken support calls. Your design should allow some branding per business, within a consistent overall template that you control for safety and accessibility.

Levels of branding

Practical cautions

• Accessibility first: customer colours may fail contrast rules. Enforce limits.
• Review uploads: logos from customers can be inappropriate or oversized.
• Phishing risk: highly customizable pages make convincing fakes easier. Keep the overall page structure fixed.
• Operational cost: each custom domain needs certificates and ongoing care.
• Email too: invitation and notification emails should carry matching branding and a trustworthy sender.

Decide with your sales team

Branding promises often come from sales conversations. Agree in advance which levels are included at which price, so engineering is not surprised by commitments made at the table.

flowchart LR
    TPL["Fixed safe template"] --> MRG["Merge"]
    LOGO["Customer logo and colour"] --> MRG
    MRG --> PG["Branded sign-in page"]
    DM["Customer-specific address"] --> PG
    

Figure 16 shows the approach. Safety and accessibility live in the template, and the customer supplies only the safe, bounded elements.

B2B customers do not only click buttons. Their own programs call your product too.

Business customers often want to connect your product to their other systems: pulling reports, synchronizing records, triggering workflows. These are programs, not people, so they need their own way to prove identity, and that proof must still carry the business context.

Machine-to-machine access

A program registers with a credential of its own and uses it to obtain tokens that represent the program, not a person. Each credential should belong to exactly one business, carry only the permissions that business has granted it, and be easy for the customer’s administrator to create, rotate, and revoke. Never share one credential across customers.

Scopes for least privilege

Scopes are named permissions that a token may carry, such as “read reports” or “update records”. Let customers issue credentials with narrow scopes, so that a leaked credential for a reporting script cannot delete data. Document the scopes clearly.

Rate limits and fairness

One customer’s busy program should not slow down everyone else. Apply fair limits per customer, tell customers clearly what they are, and return helpful responses when a limit is reached. Unlimited access for one tenant is a risk to all.

Partners acting on a customer’s behalf

Sometimes a third party, such as an integration vendor or consultancy, needs to act on behalf of a customer. Model this explicitly as a relationship the customer grants and can revoke, with permissions limited to the task and a record of what was done. Avoid sharing the customer’s own credentials with partners.

sequenceDiagram
    participant J as Customer's program
    participant I as Your identity service
    participant A as Your API
    J->>I: Present program credential for Customer X
    I->>J: Token for Customer X with narrow scopes
    J->>A: Call API with token
    A->>A: Verify token, take tenant and scopes from it
    A->>J: Data for Customer X only
    

Figure 17 shows that programs follow the same pattern as people: identity service issues a token naming the business and the permissions, and the API trusts only the token.

Rotating credentials without downtime

Machine credentials should be rotated regularly, but a customer’s program cannot be switched off while a new secret is deployed. Allow two valid credentials for a short overlap, so the customer can install the new one, confirm it works, and then retire the old one. Tell customers when a credential has not been used for a long time, since forgotten credentials are a quiet risk.

A sensible order of work saves painful rework later.

Early traps

• Using customer display names as identifiers.
• Trusting tenant values supplied by the browser.
• Building everything in production.
• Skipping cross-tenant tests because “the filter is obviously there”.
• Promising customised sign-in to sales prospects before the design supports it.

Document your decisions

Write down why you chose your tenancy model, how identifiers work, and who owns what. In two years, new team members and auditors will thank you, and you will avoid reopening settled decisions by accident.

flowchart LR
    M["Model"] --> T["Tenants"]
    T --> D["Tenant data model"]
    D --> R["Registrations"]
    R --> I["Isolation"]
    I --> RL["Roles"]
    RL --> ON["Onboarding"]
    ON --> PV["Provisioning"]
    PV --> MO["Monitoring"]
    MO --> PI["Pilot"]
    

Figure 18 summarizes the roadmap. Each step builds on the previous one, and the earliest decisions are the hardest to change later.

Three short stories show the pieces working together.

Example one: a new enterprise customer goes live

A software company called Northwind Supplies signs a contract for a project-planning product. Within minutes, the product creates a customer record and a matching organization. An email invites Northwind’s operations manager, Asha, as first administrator. She follows a guided wizard: she gives the wizard the connection details provided by Northwind’s identity team, presses a test button, adds the company’s email domain, and proves she controls it. She maps the directory’s “managers” group to the product’s “project lead” role. The next morning, Northwind’s staff sign in with their usual work credentials, and the product shows the right data for Northwind only. The vendor’s own engineers never lifted a finger.

Example two: a consultant with two clients

Daniel is a consultant who works for Northwind and also for another customer, Harbourline Logistics. He has one account in the identity service with membership in both organizations. After signing in, he is asked which business he is acting for. He chooses Northwind and receives a token naming Northwind and his role there. Later he switches to Harbourline and receives a new token naming that business and his different role. At no point can a single token reach both businesses’ data.

Example three: a leaver and a caught mistake

An engineer leaves Harbourline. Their directory account is disabled, the directory notifies the product’s identity service, and sessions are ended within minutes. Meanwhile, a developer at the vendor adds a new report feature and forgets to filter by business. The data store’s row-level rule returns nothing for other businesses, and an automated cross-tenant test fails during testing. The mistake never reaches customers.

flowchart TD
    E1["Northwind onboarding"] --> R1["Self-service setup,
live in a day"]
    E2["Consultant with two clients"] --> R2["Separate token per business"]
    E3["Leaver and coding slip"] --> R3["Access ended, mistake caught
by second line of defence"]
    

Figure 19 sums up the examples. Self-service, tenant-scoped tokens, and layered isolation each earned their place in a different story.

A multi-tenant system concentrates many customers’ trust. Treat design choices as security controls.

In a multi-tenant product, a single flaw can affect many customers at once. Security in this setting means protecting each customer from outsiders, from other customers, and from mistakes inside your own organization.

Cross-tenant attacks

• Tampering with tenant identifiers: attackers change values in requests to reach other businesses. Defence: take the tenant from verified tokens only.
• Guessing identifiers: attackers try other record numbers. Defence: check ownership on every access.
• Shared caches and queues: cached answers for one business shown to another. Defence: include tenant in every key.
• Noisy neighbours: one customer’s load harms others. Defence: per-tenant limits.

Federation-specific risks

• Unverified domains: a customer claims a domain they do not control. Defence: require proof of control.
• Over-trusting a customer’s statements: a poorly secured customer system could assert anyone’s identity within that customer’s own scope. Defence: limit each connection to its own organization so it can speak only for its own people.
• Account linking by email: merging accounts across businesses on unverified email. Defence: link only on proof, never across organizations by default.
• Replay of signed statements: reusing captured messages. Defence: use short validity and standard protections provided by the service.

Administrator risks

Customer administrators are powerful within their business, and attackers target them. Encourage strong sign-in for administrators, send notifications when sensitive settings change, and require extra confirmation for dangerous actions such as changing federation settings. Inside your own company, restrict identity tenant administrators to a small group with strong authentication, and review changes.

Support access

Your support staff can become a backdoor if not controlled. Require a recorded reason, preferably customer consent, time limits, and logging for any access to customer data. Review these logs regularly.

flowchart LR
    SEC["Multi-tenant security"] --> X1["Tenant from token only"]
    SEC --> X2["Ownership checks everywhere"]
    SEC --> X3["Verified domains"]
    SEC --> X4["Connections limited to own org"]
    SEC --> X5["Protect admins"]
    SEC --> X6["Controlled support access"]
    

Figure 20 gives a checklist. Review each pillar regularly, not only at launch, as configuration drifts and new features are added.

You cannot protect or support what you cannot see. In multi-tenant systems, the view must be sliceable by customer.

Your identity service records events: sign-ins, failures, sign-ups, changes, and blocked attempts. For a multi-tenant product, every record should carry the business it relates to, so that you can answer questions such as “how many sign-in failures did Northwind have this morning?” quickly.

What to watch

• Sign-in failure rate per customer: a sudden jump may mean a customer’s federation broke, for example when they renewed a certificate.
• Onboarding progress: how many new customers are stuck at which step.
• Federation health: errors by connection, expiring certificates, and changed settings.
• Provisioning events: creations, updates, and removals, including failures.
• Cross-tenant anomalies: requests where the token’s tenant and the accessed record’s tenant differ.
• Administrator actions: who changed which settings, and when.
• Load per customer: to spot noisy neighbours and plan fair limits.

Per-customer views for support

Build a support view that shows one customer’s recent sign-in events, errors, and configuration changes. Support staff can then answer “why can’t my users sign in?” in minutes rather than hours. Make sure this view itself is access-controlled and logged.

Customer-facing visibility

Customers appreciate being able to see their own sign-in activity and administrator changes. Offering a simple activity page or a way to export their own logs for their security teams is often a procurement requirement for larger customers.

flowchart LR
    EV["Identity events
tagged with tenant"] --> ST["Log stream"]
    ST --> SY["Your log system"]
    SY --> D1["Global dashboards"]
    SY --> D2["Per-customer support view"]
    SY --> AL["Alerts"]
    SY --> CX["Customer activity export"]
    

Figure 21 shows that one stream serves several audiences. Tagging every event with the tenant is what makes each view possible.

Turning logs into customer trust

Customers who can see for themselves what happened on their accounts trust you more. A short, clear activity view, showing sign-ins, role changes, and connection changes, answers many questions before they become support tickets. It also gives the customer’s own security team material for audits, which makes your product easier to approve in procurement.

Multi-tenant bugs hide in the paths nobody tried. Test deliberately across tenants.

Normal testing proves a feature works for one customer. Multi-tenant testing must prove that the feature works for each customer and, more importantly, never touches another. Build these checks into your regular process.

Essential test families

• Cross-tenant access tests: create two test businesses, then attempt to read, change, and delete one’s data while signed in as the other. Every attempt must fail.
• Token tampering tests: alter the tenant value and confirm the request is refused.
• Federation tests: verify sign-in for each supported protocol, with a test customer system, including wrong certificate and expired statement cases.
• Home realm tests: shared domains, multiple domains, unknown domains, odd capitalization.
• Multi-membership tests: a person in two businesses, switching context, with different roles.
• Provisioning tests: create, update, move groups, disable, and re-enable.
• Leaver tests: confirm sessions end after disabling.
• Load tests: one customer at high volume while others remain steady. Coordinate heavy tests with the provider.
• Accessibility and branding tests: unusual logos and colours.

Make the tests automatic

Run cross-tenant tests automatically on every change. A manual check once a year will not catch the slip introduced last Tuesday. Treat any failure of these tests as a stop-the-line event.

Test the onboarding wizard like a customer

Ask someone unfamiliar with your system to run the wizard using only the on-screen help. Their confusion shows exactly where your instructions fail.

flowchart TD
    CH["Code or config change"] --> UT["Unit and integration tests"]
    UT --> CT["Cross-tenant access tests"]
    CT --> FT["Federation and provisioning tests"]
    FT --> ST["Staging tenant check"]
    ST --> PI["Pilot customers"]
    PI --> RL["Full release"]
    

Figure 22 shows the gates. The cross-tenant tests sit early and run automatically, so a slip is caught before it reaches any real customer.

Technology works only when people own it. Decide who does what, and who answers when something breaks.

Multi-tenant identity touches many teams: engineering, security, support, customer success, sales, legal, and the customers’ own administrators. Without clear ownership, duties fall between chairs.

Runbooks for common situations

• A customer’s federation stopped working after they changed something.
• A customer’s certificate is about to expire.
• A customer wants to add or change email domains.
• A leaver still appears active.
• A suspected cross-tenant data exposure.
• Identity service unavailable.

Customer success and support partnership

The customer’s identity engineers and your support team often speak different languages. Train a few people to bridge them, translating between your product’s words and the customer’s identity vocabulary. This role shortens onboarding dramatically for large accounts.

Change management

Treat configuration changes like code changes: requested, reviewed, tested in a non-production tenant, rolled out in stages, and recorded. Changes to the shared tenant affect every customer, so they deserve extra care.

flowchart TD
    PT["Platform team"] --> TC["Tenant configuration"]
    PE["Product engineering"] --> DI["Data isolation and onboarding"]
    CS["Customer success"] --> FS["Federation setup help"]
    SU["Support"] --> DG["Diagnosis"]
    SE["Security"] --> PO["Policies and response"]
    TC --> GOAL["Safe, scalable B2B identity"]
    DI --> GOAL
    FS --> GOAL
    DG --> GOAL
    PO --> GOAL
    

Figure 23 shows that the identity system is a team sport. Clear roles and a steady review rhythm keep it healthy.

A pooled, organization-based design has real benefits and real costs. Weigh both honestly.

Key trade-offs

• Pool versus silo: efficiency and speed versus the strongest isolation and customization.
• Self-service versus control: empowering customers versus the risk of misconfiguration.
• Branding freedom versus safety: customer pride versus phishing and accessibility risk.
• Strict policy versus convenience: tight rules versus ease of use.
• Identity-held versus product-held authorization: simple central roles versus rich business rules.

quadrantChart
    title Design choices by effort and value
    x-axis Low effort --> High effort
    y-axis Low value --> High value
    quadrant-1 Plan carefully
    quadrant-2 Do first
    quadrant-3 Skip for now
    quadrant-4 Reconsider
    Organizations: [0.25, 0.9]
    Tenant claim in tokens: [0.2, 0.95]
    Row-level isolation: [0.5, 0.9]
    Self-service wizard: [0.6, 0.8]
    Directory provisioning: [0.65, 0.75]
    Fully white-labelled login: [0.9, 0.35]
    

Figure 24 ranks sample decisions. Organizations and tenant claims are cheap and vital. Isolation and onboarding take more effort but pay back strongly. Full white-labelling is costly and should be reserved for customers who truly need it.

Patterns are proven shapes of good practice. Each solves a recurring problem in B2B multi-tenant identity.

flowchart LR
    DP1["Org per customer"] --> OUT["Safe, scalable
B2B identity"]
    DP2["Tenant from token"] --> OUT
    DP3["Two-layer isolation"] --> OUT
    DP4["Self-service wizard"] --> OUT
    DP5["Directory provisioning"] --> OUT
    DP6["Fresh token on switch"] --> OUT
    DP7["Bridge for exceptions"] --> OUT
    

Figure 25 shows that the patterns reinforce each other. None needs heroic skill, but together they keep growth manageable and mistakes contained.

These habits look sensible but cause trouble. Recognize them early.

flowchart TD
    A1["Tenant from request"] --> BAD["Data leaks, slow growth,
lost trust"]
    A2["Tenant per customer by default"] --> BAD
    A3["Names as identifiers"] --> BAD
    A4["Unverified domains"] --> BAD
    A5["Merging across businesses"] --> BAD
    A6["Silent super-access"] --> BAD
    A7["Bespoke setups"] --> BAD
    

Figure 26 gathers the habits to avoid. Compare your own design against this list from time to time.

A short checklist of what to do and what to avoid.

Best practices

• Choose your tenancy model deliberately and write down why.
• Use one organization per customer, linked by a stable identifier.
• Place the tenant claim in tokens and take tenant context only from verified tokens.
• Enforce isolation twice: in application code and in the data store.
• Include the tenant in every cache key, queue message, file path, and search index.
• Run automated cross-tenant tests on every change.
• Provide a self-service federation wizard and require proof of domain control.
• Support just-in-time creation and directory-driven provisioning.
• Let customers map their groups to your roles, within boundaries.
• Set safe defaults and guardrails on customer policies.
• Tag every log event with the tenant and offer per-customer support views.
• Protect administrators, both yours and your customers’, with strong sign-in and change notifications.
• Confirm limits and features in official documentation for your plan.

Common mistakes

• Treating the word tenant as if it had one meaning.
• Assuming the identity service alone guarantees isolation.
• Forgetting that departing employees need active deprovisioning.
• Letting one customer’s load harm all others.
• Allowing public email domains to be used for enterprise routing.
• Over-promising customization in sales conversations.
• Ignoring customers’ certificate renewals until sign-in breaks.
• Neglecting documentation for customers’ identity engineers.

flowchart LR
    PL["Plan model"] --> BU["Build isolation and onboarding"]
    BU --> TE["Test across tenants"]
    TE --> PI["Pilot customers"]
    PI --> SC["Scale"]
    SC --> MO["Monitor per customer"]
    MO --> IM["Improve"]
    IM --> PL
    

Figure 27 reminds us that the work never ends. Customers, standards, and threats change, and a steady cycle keeps the design in good order.

Four fictional companies show the ideas in use. All names and details are invented for teaching.

flowchart LR
    C["Cedarline
start small, pooled"] --> LESSON["Common thread:
solid foundations, then grow"]
    G["Granite Peak
enterprise self-service and bridge"] --> LESSON
    L["Lumen
multi-membership"] --> LESSON
    O["Oakridge
layered isolation"] --> LESSON
    

Figure 28 shows each company’s emphasis. Their needs differed, yet all relied on the same foundations: a clear tenant model, tokens that carry context, layered isolation, and self-service onboarding.

Thirty short answers to questions beginners often ask. Always confirm specifics in the official documentation and your plan.

A good multi-tenant identity design is invisible to customers and a relief to your team.

You began this guide with no background and now understand the core of B2B multi-tenant identity. You know the vocabulary, including the two meanings of tenant. You know the silo, pool, and bridge models and why most products pool. You know how organizations represent customers, how enterprise federation lets staff use their own corporate sign-in, how home realm discovery finds the right path, and how tokens carry the tenant context that makes isolation possible. You have seen how roles, delegated administration, self-service onboarding, and directory-driven provisioning let you grow without growing your support burden.

Remember that identity states who is acting and for which business, while your product must enforce isolation in its own data layer with several independent safeguards. Treat the work as a cycle of planning, building, testing across tenants, piloting, scaling, monitoring, and improving. Confirm every plan-specific detail in the current official documentation, because names and limits change while the ideas stay steady.