Identity & Access Control

Multi-tenancy lets one deployment serve many organizations, each with its own members, roles, settings, and data, isolated from every other. In identity terms, it means every request is evaluated in the context of a specific organization, not just a specific user.

Model

erDiagram
  USER ||--o{ MEMBERSHIP : holds
  ORGANIZATION ||--o{ MEMBERSHIP : grants
  MEMBERSHIP }o--o{ ROLE : assigned
  ORGANIZATION ||--o{ ROLE : defines
  ORGANIZATION ||--o{ DOMAIN : verifies
  ORGANIZATION ||--o{ SSO_CONNECTION : configures
  ORGANIZATION ||--o{ INVITATION : sends

  USER {
    string id PK
    string email
  }
  ORGANIZATION {
    string id PK
    string name
    string region
  }
  MEMBERSHIP {
    string user_id FK
    string organization_id FK
    string status
  }

Users exist once, globally. Membership connects a user to an organization, and roles attach to the membership, not to the user. The same person can be an admin in one organization and a viewer in another.

Resolving the Active Organization

sequenceDiagram
  autonumber
  actor U as User
  participant A as Application
  participant I as Identity subsystem
  U->>A: Request with token (org claim: org_A)
  A->>A: Verify token, read user and active organization
  A->>I: Membership of user in org_A?
  I-->>A: Active, roles: editor
  A->>A: Scope every query to org_A
  U->>A: Switch to org_B
  A->>I: Issue token for org_B
  I-->>A: Denied unless an active membership exists

Design Points

• One active organization per token. The token names the organization the user is acting in. Switching organizations issues a new token instead of passing an organization identifier in each request, which callers could tamper with.
• Isolation in depth. Every query is scoped to the active organization in application code, and where possible again in the database, for example with PostgreSQL row-level security keyed on a session variable.
• Organization-level policy. Each organization can require SSO, enforce MFA, restrict sign-in to verified domains, and set session lifetimes. See Enterprise Identity & Governance.
• Invitations and domain capture. Users join by invitation, or automatically when their email belongs to a domain the organization has verified.
• Regional placement. Organizations with residency requirements are pinned to a region, and their identity data stays there.

Across Ownership Scopes

Isolation is the application's responsibility in every scope: no identity platform can scope the application's own queries.

Watch For

• Personal and organizational accounts. Decide early whether a user can exist without an organization, and what happens to their resources when they leave one.
• Cross-tenant identifiers. Resource identifiers must not be guessable across organizations, and lookups must check the organization even when the identifier is known.
• Support access. Staff who need to see a customer's organization should use audited, time-limited elevation, never a shared admin account.