Multi-Tenant Identity & SSO

​

Overview

​

Architecture

​

High-level flow

​

Per-request data flow

1. Subdomain sets req.school and req.db (unchanged): derived from Host (e.g. rpi from rpi.meridian.study). In development, localhost defaults to rpi.
2. JWT is verified; payload may include globalUserId, tenantUserId, platformRoles, roles.
3. Middleware resolves req.user.tenantUserId from the global DB via TenantMembership(globalUserId, req.school). For backward compatibility, req.user.userId = req.user.tenantUserId so existing code using req.user.userId and getModels(req, 'User') keeps working. When there is no membership, userId is null (guest on that tenant).
4. Admin routes use requireAdmin: platform admin (from global DB or token) first, then tenant User.roles (admin/root).

​

Tenant derivation (subdomain)

• Production: Tenant is the first segment of the host. Examples: rpi.meridian.study → req.school = 'rpi', tvcog.meridian.study → req.school = 'tvcog'.
• Development: If the host is localhost or an IP address, the backend defaults to req.school = 'rpi' so local testing works without subdomains.

​

Global database

​

Purpose

• GlobalUser – one identity per person (email, name, picture, provider ids).
• PlatformRole – which global users are platform admins (or root).
• TenantMembership – which global user is linked to which tenant and which tenant User id.
• Session – refresh sessions keyed by globalUserId so token refresh works across tenants (SSO).

​

Connection

• File: Meridian/backend/connectionsManager.js
• Function: connectToGlobalDatabase()
• Config: Reads MONGO_URI_PLATFORM or MONGO_URI_GLOBAL. If unset, derives a DB from the default tenant URI (e.g. same cluster, database name meridian_platform).
• Attach: In app.js, the same middleware that sets req.db sets req.globalDb = await connectToGlobalDatabase() so every request has access.

​

Global schemas

​

getGlobalModelService

• File: Meridian/backend/services/getGlobalModelService.js
• Usage: const { GlobalUser, PlatformRole, TenantMembership, Session } = getGlobalModels(req, 'GlobalUser', 'PlatformRole', 'TenantMembership', 'Session');
• Rule: Use only in auth flows, session handling, and platform-admin resolution. Tenant routes continue to use getModelService(req, ...) with req.db.

​

JWT shape and auth

​

New token payload

• globalUserId – always present for authenticated users.
• tenantUserId – present when the user has a TenantMembership for the tenant they logged in on; for other tenants, resolved in middleware from TenantMembership.
• platformRoles – optional array from PlatformRole (e.g. ['platform_admin']) to avoid a DB hit on every request.
• roles – tenant User roles (for backward compatibility and existing authorizeRoles when not using platform admin).

​

Backward compatibility

​

Login/register flow (create-or-find GlobalUser + TenantMembership)

1. Get or create GlobalUser by email (and optionally by googleId / appleId / SAML id). New GlobalUser: copy email, name, picture, provider ids from the tenant User or OAuth profile.
2. Get or create TenantMembership for (globalUserId, req.school). If creating, create or find the tenant User in req.db, then set TenantMembership.tenantUserId to that User’s _id.
3. Load PlatformRole for this globalUserId (if any).
4. Issue JWT with globalUserId, tenantUserId (for current school), platformRoles, roles (from tenant User).
5. Create Session in the global DB keyed by globalUserId so refresh works across tenants.

​

Sessions and refresh (global)

• Session storage lives in the global DB. The Session collection has globalUserId, refreshToken, device/userAgent/ip, expiresAt. Refresh token payload: { globalUserId, type: 'refresh' }.
• On refresh: verify JWT, validate session in global DB, resolve tenantUserId for req.school via TenantMembership, then issue new access (and optionally refresh) token with the same shape.

​

Cookie domain for SSO

• In production, when setting accessToken / refreshToken cookies, set domain: '.meridian.study' so the cookie is sent to all subdomains.
• In development, omit domain (defaults to current host).
• CORS: Production corsOptions.origin in app.js must allow all intended subdomains (e.g. rpi.meridian.study, tvcog.meridian.study) so the frontend on any subdomain can send credentials and receive cookies.

​

Auth middleware (verifyToken)

• File: Meridian/backend/middlewares/verifyToken.js
• After verifying the JWT, if the payload has globalUserId, the middleware resolves tenantUserId from TenantMembership for (decoded.globalUserId, req.school) and sets:
  • req.user.globalUserId
  • req.user.tenantUserId
  • req.user.userId = tenantUserId (so existing code using req.user.userId works)
  • req.user.roles (from tenant User if found, else from token)
  • req.user.platformRoles
• If the token is legacy (no globalUserId), behavior is unchanged: req.user.userId = decoded.userId, req.user.roles = decoded.roles.
• verifyTokenOptional: Same resolution when the token is valid; when the token is expired, the refresh path uses the global Session and TenantMembership, then sets req.user with the new shape.

​

Platform admins (requireAdmin)

​

Resolve admin status

• File: Meridian/backend/middlewares/requireAdmin.js
• Middleware: requireAdmin (or “require platform or tenant admin”):
  1. If req.user.platformRoles includes platform_admin or root → allow.
  2. Else if req.user.globalUserId exists, load PlatformRole from the global DB; if roles include platform_admin or root → allow.
  3. Else if req.user.userId exists, load User from req.db; if user.roles includes admin or root → allow.
  4. Else return 403.

​

Platform admins API

​

Platform admins UI

• Frontend: Meridian/frontend/src/pages/Admin/PlatformAdminsPage/PlatformAdminsPage.jsx – lists platform admins, “Add” by email, “Remove”. Wired under the Admin area (e.g. “Platform Admins” tab).
• Visibility should be restricted to users who pass the backend requireAdmin check (platform or tenant admin).

​

Seeding the first platform admin(s)

• Env: PLATFORM_ADMIN_EMAILS=admin@example.com (comma-separated if multiple).
• Script: From Meridian/backend/, run node scripts/seedPlatformAdmins.js. It creates or finds GlobalUser by email and adds PlatformRole with platform_admin.
• Alternatively, create a migration that inserts GlobalUser + PlatformRole for a fixed email. Document in backend docs how to add the first platform admin.

​

Cross-tenant event registration

​

Event schema: global attendees

• File: Meridian/backend/events/schemas/event.js (or Events-Backend equivalent)
• Field: globalAttendees – array of { globalUserId, email, name, picture?, sourceTenant?, registeredAt, guestCount, checkedIn, checkedInAt, checkedInBy }. No ref to User in tenant DB.
• Index: Ensure queries for “is this user already registered?” consider both attendees.userId and globalAttendees.globalUserId.

​

RSVP route: global guest

• In POST RSVP (e.g. POST /rsvp/:event_id): If req.user.userId exists, keep current behavior (add/update in event.attendees). Else if req.user.globalUserId exists, treat as global guest: check event.globalAttendees by globalUserId, then append to globalAttendees with data from GlobalUser and apply the same validation (capacity, deadline, form if any). FormResponse may store globalSubmittedBy (ObjectId) for global guests.
• In DELETE RSVP (withdraw): Allow withdrawal if either attendees.userId === req.user.userId or globalAttendees.globalUserId === req.user.globalUserId.
• GET event/list: Include both attendees and globalAttendees (or a merged view with a flag like isGuest: true) so organizers see “Name (guest)” or “Name (from RPI)” as needed.

​

Join school (create tenant user + membership)

• Endpoint: POST /auth/join-tenant (or /join-tenant). Protected by verifyToken. Expects req.user.globalUserId (user must be logged in with global identity). Body can be empty; tenant comes from req.school.
• Logic: Look up TenantMembership for (req.user.globalUserId, req.school). If already active, return success. Else: load GlobalUser; create a new User in req.db with email, name, picture, provider ids from GlobalUser and default tenant fields (roles: ['user'], etc.); create TenantMembership with globalUserId, tenantKey: req.school, tenantUserId: newUser._id, status: 'active'. Optionally issue a new token with tenantUserId set.
• Frontend: When validate-token returns user: null but communities (or similar), show a “Join [School name]” CTA that calls this endpoint and then refreshes auth state.

​

Migration and backward compatibility

​

Legacy tokens

• Keep accepting the old JWT shape (userId, roles only) in verifyToken.js; set req.user.userId, req.user.roles. Optional: lazy backfill (on first request with legacy token, resolve or create GlobalUser + TenantMembership and set req.user.globalUserId for that request only; optionally refresh token with new shape).

​

Existing users (one-time migration)

• Script: Meridian/backend/scripts/migrateUsersToGlobalIdentity.js
• Behavior: For each tenant key (e.g. rpi, tvcog), load all Users from that tenant’s DB; for each User, get or create GlobalUser by email (and provider ids), then get or create TenantMembership for (globalUserId, tenantKey) with tenantUserId = User._id. Existing User documents are not changed.
• Config: Edit tenantKeys in the script to match your tenants; ensure MONGO_URI_PLATFORM (or MONGO_URI_GLOBAL) and tenant DB URIs are set. Run from Meridian/backend/: node scripts/migrateUsersToGlobalIdentity.js.

​

Security and SOC2 notes

• Global DB: Restrict access (network and credentials); only the main app should connect. Use least privilege for platform admin management (only platform admins can add/remove).
• Audit: Log platform admin add/remove (who, when, by whom) in your existing audit or logging pipeline.
• Cookie: httpOnly, secure in production, sameSite: 'strict' (or lax if cross-site links must preserve login). Domain .meridian.study only in production.

​

Setting up in staging / production

​

1. Environment variables

​

2. CORS and cookie domain

• Production (NODE_ENV=production): The app allows origins https://www.meridian.study, https://meridian.study, https://rpi.meridian.study, https://tvcog.meridian.study and sets auth cookies with domain: '.meridian.study' so SSO works across subdomains.
• Staging: If your staging site uses the same parent domain (e.g. rpi.staging.meridian.study), add those origins in Meridian/backend/app.js in the corsOrigin / corsOptions.origin arrays, and set cookie domain to .staging.meridian.study in:
  • Meridian/backend/routes/authRoutes.js (cookieOptions / clearOpts)
  • Meridian/backend/middlewares/verifyToken.js (cookieOptions on refresh)
  • Meridian/backend/services/authGlobalService.js (cookieOptions in issueTokens)
  • Meridian/backend/routes/adminRoutes.js (impersonate cookieOpts) If staging uses a different domain entirely, use the same pattern (one parent domain for CORS and cookie domain).

​

3. Add new tenants (if needed)

const schoolDbMap = {
  rpi: process.env.MONGO_URI_RPI,
  tvcog: process.env.MONGO_URI_TVCOG,
  // staging: process.env.MONGO_URI_STAGING,
};

​

4. (Optional) Migrate existing users

1. Set MONGO_URI_PLATFORM (or MONGO_URI_GLOBAL) and all tenant URIs (MONGO_URI_RPI, MONGO_URI_TVCOG, etc.) in the environment.
2. In Meridian/backend/scripts/migrateUsersToGlobalIdentity.js, set tenantKeys to the list of tenant keys you use (e.g. ['rpi', 'tvcog']).
3. From the backend directory, run:
   node scripts/migrateUsersToGlobalIdentity.js
   
4. The script creates GlobalUser (by email) and TenantMembership per tenant User. Existing User documents are not modified. New logins will attach to these GlobalUsers.

​

5. Seed the first platform admins

1. Set PLATFORM_ADMIN_EMAILS to a comma-separated list of emails (e.g. admin@meridian.study). These must be emails that exist (or will exist) as GlobalUser—e.g. after migration, or after the first login with that email.
2. From the backend directory, run:
   MONGO_URI_PLATFORM=<your-global-db-uri> PLATFORM_ADMIN_EMAILS=admin@example.com node scripts/seedPlatformAdmins.js
   
   Or ensure MONGO_URI_PLATFORM is already in the environment and run:
   PLATFORM_ADMIN_EMAILS=admin@example.com node scripts/seedPlatformAdmins.js
   
3. Those users can then log in on any tenant and access admin routes (e.g. Platform Admins UI). You can also add/remove platform admins later via the Admin → Platform Admins UI (if you have at least one tenant or platform admin).

​

6. Deploy and verify

1. Deploy the backend (with the env vars above). Ensure the app starts and can connect to both tenant DBs and the global DB.
2. Open a tenant subdomain (e.g. https://rpi.meridian.study), log in, and confirm auth works.
3. If SSO is configured, open another tenant (e.g. https://tvcog.meridian.study) in the same browser and confirm you are still logged in (same user or no prompt to log in again, depending on membership).
4. As a platform admin, open Admin → Platform Admins and confirm you can list/add/remove platform admins.
5. (Optional) Test global-guest event RSVP: log in on tenant A, open an event on tenant B (where you have no tenant User), and confirm you can register as a guest or use “Join school” if implemented.

​

7. Security checklist

• Use HTTPS in staging/production so cookies are sent with secure: true.
• Restrict global DB network and credentials to the app only; do not expose it to other services unless required.
• Audit: Ensure platform admin add/remove is logged (who, when, by whom) for SOC2 or compliance.
• Keep JWT_SECRET and JWT_REFRESH_SECRET strong and not committed to the repo.

​

Quick reference: key files

​

Related docs