Who are you, and what may you see?

Identity is two questions. Authentication asks who you are; authorization asks what you may touch. We answer the first with open standards and an identity provider we can swap, and the second inside our own apps, where the data lives. Every app is multitenant from its first migration, because adding tenants later means touching every query.

1. The shape of a tenant

An organization is a customer: a dealer group, a franchise, a company. Inside it sit rooftops, the physical locations whose data is kept apart, and groups, which collect rooftops (a region, a brand) and can contain other groups. People join an organization through a membership, and what they can do comes from grants: a role on a group or a rooftop.

Organization ─┬─ Group "West"  ─┬─ Rooftop "Phoenix"
              │                 └─ Rooftop "Tucson"
              └─ Group "East"  ─── Rooftop "Austin"

User ── Membership(org) ──┬─ Grant(role: :manager, on: Group "West")
                          └─ Grant(role: :viewer,  on: Rooftop "Austin")

A grant on a group covers every rooftop beneath it, so a regional manager is one row, not twenty. An owner role on the organization itself covers everything. That is the whole model: four tables plus the user.

organizations  id, name, slug
units          id, organization_id, parent_id, kind (group|rooftop), name, path
memberships    id, organization_id, user_id, status
grants         id, membership_id, unit_id (null = whole org), role

Groups and rooftops share one units table with a materialized path (/1/4/9/), so "every rooftop this person can see" is one indexed LIKE query instead of a recursive walk. Every business record carries organization_id and rooftop_id.

2. Scoping every query

• Resolve the tenant once per request, from the subdomain or the signed-in membership, into Current.organization and the set of visible rooftop ids.
• Reach data through that scope (Current.organization.deals.where(rooftop: visible_rooftops)), never through a bare Deal.find. A Rails model concern makes the scoped path the easy one.
• As a backstop, use PostgreSQL row-level security with correct tenant policies, a constrained runtime role and trusted app.organization_id context. An unscoped query must not expose another tenant's rows; it may still return rows allowed for the current tenant. Reject missing or invalid tenant context or deny all tenant rows, and verify that behavior rather than assuming it from an RLS flag.
• Test it: every tenant model gets a test that a user from organization A cannot read organization B's rows, and a rooftop viewer cannot read a sibling rooftop.

Make the database backstop real

PostgreSQL 18 documentation, checked October 16, 2026; deployed version and configuration unverified. Enabling RLS ordinarily leaves the table owner exempt. FORCE ROW LEVEL SECURITY subjects an otherwise non-bypass owner to policy, but superusers and BYPASSRLS roles remain exempt: FORCE is not a universal bypass override.

Our design recommendation is a non-owner, non-superuser, non-bypass runtime role, separate from migration ownership. Review inherited privileges and permitted SET ROLE paths, not just the immediate role's flags. Check request, job and export connections against the expected tenant-table list; a missing table must fail the check. Derive tenant context from trusted authorization and test its lifecycle across transactions, pool reuse and retries. A tenant setting is not itself an authorization decision.

Test indirect paths too. Ordinary views use their owner's base-relation permissions and RLS policies; security_invoker=true instead uses the caller's. CURRENT_USER in a view is not proof of that permission identity. SECURITY DEFINER functions run with owner privileges. A passing direct-table test does not establish wrapper isolation; review privileged helpers separately.

Acceptance experiments—proposed, not run: in a separately authorized disposable PostgreSQL 18 fixture, use synthetic A/B tenants. With valid A context, an unscoped read may return allowed A rows but no B rows; B-targeted updates/deletes affect zero rows, while cross-tenant inserts and retagging fail policy checks. Missing or invalid context must reject the operation or deny all tenant rows under the application's documented contract. Repeat through jobs, exports, views/functions, retries and connection reuse; retain sibling-rooftop authorization tests separately.

Include deliberately unsafe negative controls: an owner without FORCE, a BYPASSRLS role with table privileges, and a wrapper owned by that exempt table owner should expose the fixture's isolation failure. An ordinary owner with FORCE and an applicable tenant policy should be constrained. These checks are a proposed test design, not evidence of a secure deployed database or a complete security audit. No database access or permission changes were performed for this clarification.

3. Signing in: one door, open standards

Our apps never talk to Okta, Microsoft or Google directly. They speak OpenID Connect to one identity provider of ours, which acts as a broker: it holds local accounts and passkeys, and it federates out to each enterprise customer's own provider. The app sees a single issuer and a single token format whoever the customer is.

• OIDC is the default for everything new: JSON, HTTPS, easy to debug. In Ruby, omniauth_openid_connect handles the app side.
• SAML 2.0 is still what many enterprises run. The broker speaks it so our apps don't have to.
• Home realm discovery: the sign-in page asks for an email first. If the domain belongs to an organization with its own SSO, the person goes straight to their company's login; otherwise they use a passkey.
• SCIM lets a customer's directory create, update and, most importantly, remove our users automatically. Someone who leaves the company loses access the same day without anyone filing a ticket.
• The customer's group claims (for example west-region-managers) map to our grants through a per-organization table the customer's admin controls. Their directory decides who is in a group; our app decides what that group may do.

Because the app only knows OIDC_ISSUER, OIDC_CLIENT_ID and OIDC_CLIENT_SECRET from its .env, replacing the broker is a configuration change. That is the adapter rule from Own your stack, with the standard itself as the interface.

4. Choosing the broker

All of these speak OIDC and SAML and support passkeys. The difference is weight, licence and how naturally they model many organizations.

Our proposal: trial Zitadel first, because its data model already matches ours (organizations with their own SSO and admins) and it is light enough for this machine. Keycloak is the fallback if we hit a gap. A hosted broker stays an option for a customer who needs SSO before we can run one, and since apps only speak OIDC, moving between them costs a config change plus a user export. Nothing is installed yet.

5. Passkeys and YubiKeys

Passwords get phished, reused and leaked. Passkeys (WebAuthn / FIDO2) don't: the browser signs a challenge with a key that is bound to our domain, so a look-alike site gets nothing useful.

• YubiKeys are the gold standard. The private key never leaves the hardware, it needs a touch (and a PIN where we require it), and it works on any machine with USB or NFC. Staff, admins and anyone who can change grants must use a hardware key.
• Register two. Everyone with a hardware key enrolls a spare, kept somewhere else. Losing one key should be an inconvenience, not an account recovery.
• Synced passkeys (iCloud Keychain, Google Password Manager, 1Password, Bitwarden) are fine for ordinary users: still phishing-resistant, far easier to live with.
• Enterprise policy: an organization can require hardware keys for its members, and can restrict them to approved models using the authenticator's attestation.
• Fallbacks: TOTP authenticator apps as a second factor, recovery codes printed once. No SMS codes and no security questions.
• When the broker owns sign-in, it handles WebAuthn. If an app ever does it directly, the webauthn gem is the Ruby implementation, on top of the authentication generator Rails ships.

6. Sessions, step-up and audit

• Sessions are rows in the database, not just cookies, so an admin or a SCIM deprovision can end them everywhere at once.
• Sensitive actions (changing grants, exporting data, adding a key) ask for a fresh touch of the passkey, even mid-session.
• Sign-ins, failures, grant changes and impersonation are written to an append-only audit log and sent to observability, so "who saw this rooftop's data last week?" has an answer.
• The broker's client secrets and signing keys go through the secrets adapter like every other secret.

7. The rules

• Every app is multitenant from the start: organization, groups and rooftops, memberships, and grants on a unit.
• Every query goes through the tenant scope, backed by row-level security and cross-tenant tests.
• Apps authenticate only through OIDC to our broker; enterprise SSO, SAML and SCIM are the broker's job.
• Passkeys first, hardware keys for anyone with admin power, never SMS.
• Authorization lives in our app and our database, not in tokens from someone else's provider.

These rules are section 15 of AGENTS.md, which every coding agent working here follows.

Provided as is, for information only, with no warranty and no liability. Not legal or professional advice. Security and radio material is for authorized, lawful use only. Full disclaimer.

Visits are logged on our own server: IP address, browser and device details, and pages viewed. We use them to understand traffic and spot attacks, and never share or sell them.