Skip to content
MSO CloudDocumentation

App family and identity hub

On this page

MSO Cloud is the sign-in, membership, entitlement and analytics core for a family of separately deployed apps. ContentHeat, which turns trend data into ad images, videos and posts, is the first. Customers keep one credential and one admin screen; each app keeps its own repo, database, workers and release cadence.

The structure follows arc42 (sections 1-12). The diagrams use the C4 model: level 1 (system context), level 2 (containers) and one runtime sequence. The binding decision is ADR 0058. The schedule, gates and research live in the programme plan and its research appendix.

MSO Cloud is the hub; apps connect to itMembers and adminsSign in onceOpen apps from the launcherpeopleMSO Cloudwww.msocloud.netIdentityOnly OpenID Connect issuerOrganization and brandOne entitlement row per org and appApp launcherGrid of enabled apps, org and brand carriedPlatform API v1 and eventsScoped reads, signed webhooksData and dashboardsThree data planes, owned hereContentHeatAd images, videos, postsOIDC relying partyOwn repo, database, deploycontentheat.younetgroup.comNext appSame contractsign inlaunchauthorize (code + PKCE)token (private_key_jwt)Platform API v1 readssigned webhooksback-channel logoutcontent.publishedsame contractSolid arrows: ContentHeat. Dashed arrow: a further app on the same contract.
MSO Cloud is the hub: one sign-in, one launcher, one API. Each app keeps its own code, database and release cadence.

1. Introduction and goals#

Requirements. A customer works across www.msocloud.net and contentheat.younetgroup.com. The family must offer:

  • one login;
  • an app launcher that carries org and brand context;
  • per-org app enablement by an admin;
  • logout everywhere.

The design also has to admit a second and third app (proofframe, curious-kids-content-studio, already on the same host) without new identity work.

Quality goals, with weights in brackets:

# Quality goal Measurable target
Q1 User experience (20) Launcher to app: 0 login prompts (J1); org and brand survive the switch in both directions (J2); invite once in MSO (J3)
Q2 Security (20) OpenID conformance suite passes before the pilot and after every issuer-library minor; no implicit account linking; ≤ 5 s logout to 401
Q3 Independent scale (15) ContentHeat render workers (10-12 GB each) scale and deploy without an MSO release
Q4 Maintainability (15) Shared code is one versioned contract package plus design tokens; each repo keeps its own rulebook and gates
Q5 Data integrity (10) One owner per dataset; cross-system count reconciliation delta 0 over 14 days
Q6 Migration safety (10) Every step additive and reversible per org; existing ContentHeat data untouched

Stakeholders. Org members and admins (one sign-in, one invite), platform super admins (link orgs, audited), the operator (only approver of Ask-first changes), app teams (own release cadence), and external reviewers of the authorization server.

2. Constraints#

Constraint Source
Two registrable domains, so no parent-domain cookie can be shared ADR 0058 Context
MSO sessions are 14-day Auth.js JWTs; each carries a sid whose auth_sessions row makes it revocable MSO web session callback
MSO web is an OIDC client of upstream directories; the issuer is a separate sidecar ADR 0058 D2
ContentHeat runs its own sign-in library with passkey and two-factor plugins and no SSO ContentHeat auth configuration
ContentHeat forbids framing (frame-ancestors 'none') ContentHeat CSP
Its sign-in library refuses implicit linking to an unverified local user; ContentHeat users default to unverified ContentHeat account-link code and schema
Tenant data is behind attested RLS; a satellite never reads MSO Postgres, Redis, Cube or MCP ADR 0054
One production host: Ryzen 9 9950X, 32 threads, 125 GiB, one shared reverse proxy Host inventory 2026-11-01
Live tenancy (organizations: 7, users: 24, memberships: 40, active custom domains: 2) Production read 2026-11-01

3. Context and scope#

Org members and adminsSign in once at MSO CloudOpen apps from the launcherInvite people, enable appspersonSuper adminsLink orgs, bulk-link usersAudited, reversibleperson (platform staff)Org directoriesGoogle, LDAP/AD, org OIDCterminate in the MSO sessionexternal system, upstream IdPMSO Cloud (platform core)OIDC issuer https://msocloud.netMembership, org role, brand scopeApp entitlement ledgerApp launcherPlatform API v1, webhooksWarehouse: three data planesDashboards, charts, AI analysisOwns: identity + analytical datasoftware system in scopeContentHeatAd images, videos, postsOIDC relying partyOwn repo, DB, workers, deploycontentheat.younetgroup.comsatellite appSocial and ad channelsFacebook, TikTok, YouTubeexternal systemsFuture satellitesSame contract and kit<app>.msocloud.netData sourcesMarketplaces, ad and web accounts, CRM, files (1st party) · social listening (3rd party)pulled only by MSO Cloud connectorssign in, launchadministerfederated loginOIDC, launchAPI, content.publishedsame contractpublishconnectors pullperformance pulled back by MSO connectors
C4 level 1. MSO Cloud is the only sign-in and the only data owner for analytics; satellites own their own work data.
Neighbour Direction What crosses
Org members and admins in One sign-in at MSO Cloud (Google, LDAP/AD, org OIDC, password, passkey, TOTP); launcher clicks
Org directories in Upstream identity; it terminates in the MSO session and reaches apps only as amr/acr
ContentHeat and later apps both OIDC tokens out; Platform API reads and content.published events in; signed webhooks out
Data sources in Marketplace, marketing and social-listening data, pulled only by MSO connectors
Social and ad channels in, via MSO connectors Creatives are published by ContentHeat; their performance comes back through MSO's existing connectors

4. Solution strategy#

Problem Strategy
One login across domains MSO is the only OpenID Connect issuer; apps are relying parties
App enablement per org The plugin install ledger carries plan, limits, validity and status; a satellite is a manifest kind
Switching apps A launcher grid every app renders from one endpoint and one markup contract
Data reuse Analytical data stays in the MSO warehouse; apps read it through a scoped API and keep their own work data
Independent scale and release Each app is its own deployable on its own origin; the only shared code is a versioned contract package

Options rejected: merging into one monorepo, an iframe or micro-frontend shell, path zones on MSO hosts, and a hosted identity vendor. Reasons are in ADR 0058, Rejected.

5. Building block view#

EdgeCDN → reverse proxy (one per host) · msocloud.net · <org>.msocloud.net · customer domains | contentheat.younetgroup.com · heat.<customer>MSO Cloud stack (monorepo)boundary: msocloud.net registrable domainapps/web (Next.js 16)Login, admin, launcher/api/platform/v1/api/internal/idp/session/api/apps/launch, idp-handoffcontainerapps/idp (certified OIDC library)Issuer, JWKS, ES256code+PKCE, refresh, client credsprivate_key_jwt, RFC 9068/8707back-channel logoutcontainer, newapps/workerConnectors, rollupsplatform_outbox → signed webhookstrends.updated, org.app.changedcontainerPostgres 16 (FORCE RLS)Warehouse: 3 planesyng_auth: sessions, signing keysrole yng_idp: key table onlydatabaseRedisQueues, cacheidp grants under own prefixstoreRustFSUploads, backupsobject storeapps/idp reads the session from apps/web over an internal bearer route;it holds no SESSION_SECRET and no app DB URL.ContentHeat stack (own repo)boundary: own deploy, own release cadenceweb (Next.js 16, sign-in library)genericOAuth provider msoback-channel logout receiverprovision + webhook routescontainerworkerpg-boss jobsAI callscontainerworker-mediaffmpeg, Chromium10-12 GB eachcontainer, scales alonePostgres 18Org, brand, RBACpg-boss, RLSmso-social projectiondatabaseRustFSGenerated assetsobject storeOIDCplatform API (at+jwt, one org)HMAC webhooks
C4 level 2. The only links between the stacks are OIDC, the platform API and signed webhooks; no shared database, Redis, cookie or session secret.
Container Responsibility Technology
MSO apps/web Login, admin, launcher, Platform API v1, the internal session route for the issuer, launch and handoff routes Next.js 16.4, Auth.js 5.0.0-beta.32
MSO apps/idp OIDC issuer https://msocloud.net: discovery, JWKS, authorize, token, end-session, back-channel logout A certified OIDC provider library, ES256 keys
MSO apps/worker Connectors, rollups, platform_outbox webhooks BullMQ on Redis
MSO Postgres Warehouse (three data planes), yng_auth.auth_sessions, issuer key table Postgres 16, FORCE RLS
MSO Redis Queues, cache, issuer grants under their own key prefix Redis
ContentHeat web Relying party, provisioning and webhook receivers, back-channel logout receiver, creative workflow UI Next.js 16.4, generic OAuth provider
ContentHeat worker, worker-media AI generation, ffmpeg and Chromium rendering; scale independently pg-boss on Postgres 18
ContentHeat Postgres, RustFS Orgs, brands, RBAC, briefs, approvals, trend-feed projection; generated assets Postgres 18 with RLS, S3-compatible store

Shared code is published to a private package registry under the younetgroup scope, as @younetgroup/platform-contract (Zod schemas, CONTRACT.md, the vi copy bundle, the J1-J6 conformance specs) and @younetgroup/design-tokens (CSS variables). Minor versions are additive; a breaking change gets a new major kept 90 days beside the old one. ContentHeat's repository moved to younetgroup/content-engine-platform on 2026-11-01, so one package ACL and one CI identity cover both apps. Its Docker build reads the registry with a read:packages token passed as a BuildKit secret, never as a build arg.

6. Runtime view#

6.1 Launcher to app with zero prompts (J1)

Browseracme.msocloud.netmsocloud.net (web)apps/idpContentHeat1 click ContentHeat tile → /api/apps/launch/contentheat2 302 + single-use token (60 s, bound to sid)3 /api/auth/idp-handoff?token=…4 platform-host session, same sid → 302 to app5 open /o/<org>/b/<brand>6 302 /oauth2/auth (PKCE S256, prompt=none)7 authorization request8 GET /api/internal/idp/session (bearer)9 {sub, sid, amr, auth_time, email_verified}10 302 back with code11 callback with code12 token request, private_key_jwt13 ID token (orgs[], sid) + refresh tokenZero login prompts · org and brand in the URL · audit row records the origin host
Journey J1, zero prompts: a 60-second single-use handoff carries the session from the tenant host to the issuer host, then standard OIDC with prompt=none.

The authorize step always runs on the issuer host, because the issuer's interaction cookie is host-scoped. A user on a tenant host (acme.msocloud.net) or a custom domain therefore crosses once through a single-use, 60-second handoff token bound to the session id (sid). The token is built on the existing magic-link mechanism, and an audit row records the origin host.

6.2 Cold deep link and white-label orgs

  1. A user opens a deep link into ContentHeat for an org and brand, with no app session.
  2. The app redirects to /oauth2/auth with prompt=none and an org hint.
  3. If the issuer host already holds a session, the code returns with no UI.
  4. If not, the issuer renders that org's branded login (the existing branded login of ADR 0045) on msocloud.net.
  5. The user signs in once and returns to the deep link.

White-label orgs use the same flow; their browsers pass through msocloud.net redirects for the sign-in step. Home-realm discovery (email to org) and an app host on the customer's own domain are directions: Future direction.

6.3 Logout everywhere

  1. Sign-out in any app calls the issuer's end_session with id_token_hint.
  2. The issuer sets auth_sessions.revoked_at for the sid.
  3. It posts an OIDC Back-Channel Logout logout_token to every client holding that sid.
  4. Each app verifies the token against the issuer JWKS (iss, aud, iat, events, jti replay set) and deletes its sessions by sid, falling back to sub.
  5. The post-logout redirect clears the MSO cookie.

ContentHeat sessions are DB rows with the cookie cache off, so the next request returns 401. The acceptance bound is 5 s (journey J5). Front-channel logout is not used, because cookie partitioning breaks it.

6.4 Data pull and change events

  • Org provisioning. Users and memberships are created just-in-time from ID-token claims at each login. The app can read the org, its brands and members from the Platform API with a client-credentials token.
  • Changes. MSO writes org.app.changed, membership.changed, user.disabled and trends.updated to platform_outbox in the same transaction as the change. A worker sweep delivers them as HMAC-SHA256-signed webhooks with X-MSO-Event-Id, retrying with backoff: Platform API and events.
  • Trend reads. ContentHeat reads /api/platform/v1/orgs/{id}/social/trends (+ /counts) with an access token that carries one org_id and the platform:social.read scope.
  • Lineage. When ContentHeat publishes a creative it emits content.published (asset id, channel post id, brand, campaign) to MSO.
  • Reconciliation. verify:data asserts the trend counts endpoint against the rows the list returns; the app compares its projection per brand against that endpoint.

7. Deployment view#

Node Runs
CDN and DNS DNS and CDN for msocloud.net and *.msocloud.net; cache bypass for /oauth2/* and /.well-known/*
Reverse proxy (one per host) Routes PathPrefix(/oauth2, /.well-known/openid-configuration, /.well-known/jwks.json) on the platform host to msocloud-idp; the rest to apps/web
Stack msocloud-* web, worker, msocloud-idp, Postgres 16, Redis (issuer grants under their own prefix), RustFS
Stack ce-prod-* web, worker, worker-media, landing, Postgres 18, RustFS

Keys and secrets. Issuer signing keys (ES256, overlapping rotation) and the ContentHeat client key live in yng_auth, envelope-encrypted with the existing secret-encryption key. The issuer connects as a dedicated role yng_idp that can only SELECT the key table. It never holds the web app's DB URL or SESSION_SECRET, and reads the MSO session only through GET /api/internal/idp/session. That route uses bearer authentication and returns {sub, sid, amr, auth_time, email, email_verified}.

Deploys. Each repo deploys on its own: MSO through ./scripts/start-prod.sh (the issuer sidecar with its --with-idp flag), ContentHeat through its own start-prod.sh.

8. Cross-cutting concepts#

8.1 Identity and claims

The ID token carries iss, sub, aud, exp, iat, auth_time, nonce, sid, amr[], acr, email, email_verified, name, locale. Under https://msocloud.net/claims/ it adds:

  • orgs: [{id, slug, name, role, brand_ids|null, apps[]}], capped at 50; beyond that, orgs_truncated: true and the app calls /me;
  • active_org, active_brand and super_admin.

An access token is an RFC 9068 at+jwt with aud=https://msocloud.net/api/platform, exp ≤ 10 min and exactly one org_id. email_verified derives only from a new users.email_verified_at, set by magic link, a Google identity or an LDAP bind. App-specific roles stay in the app. The role floor maps owner→owner, admin→admin, editor→creator and viewer→viewer. App admins may add finer roles within that floor.

8.2 Tenancy and entitlement

"Org X has app Y on plan Z" is one row in org_plugin_installations. The table carries plan, limits, valid_to and status, and a trial is just a valid_to value. The plugin manifest has kind:'satellite' with clientId, launchUrl, scopes and planIds ; the launch URL is overridable per environment. Entitlement is checked twice:

  • at login, from the apps[] claim;
  • on the server, through /orgs/{id}/entitlements, with a 5-minute cache that webhooks invalidate.

The issuer refuses a client-credentials token for an org without the app installed, so enforcement sits at the data, not in navigation (§47). The launcher (GET /api/platform/v1/me/launcher) returns one tile per app for the active org, in state enabled, not_enabled or expired; the app is opt-in per org. Seat assignment is not in the schema: Future direction.

8.3 Data ownership

Each dataset has one owner, following data mesh's "source-aligned" ownership.

Data Owner Others get it by
Social trends (3rd-party market-intel plane), marketing and marketplace performance MSO warehouse Platform API v1, one scope per plane; trends.updated webhooks
The shared social trend feed: synced once in MSO Cloud, the same rows for every org MSO warehouse, shared dataset plane The four social/trend-feed routes; an app keeps a projection and pulls on change
Dashboards, charts, AI analysis MSO Deep link from any app's launcher to the MSO dashboard; never an iframe
Briefs, generated assets (RustFS), render jobs, brand kits, approvals, schedules ContentHeat Not shared; content.published events carry ids only
Performance of a published creative MSO MSO's ad and social connectors pull it and attribute it to the creative via content.published lineage; ContentHeat never pushes numbers

The social trend feed is synced in MSO Cloud: one vendor account, one session, one sync for every org. ContentHeat no longer calls the vendor; it pulls the feed through the Platform API (Platform API and events) and keeps a local projection, so a render never blocks on MSO uptime. The projection keeps the source key it already uses (ADR 0061 D7); no new mso-social key is introduced.

  • Pull. Per linked org the app reads the feed state and stores that org's grant (enabled, slices) with the time MSO confirmed it. Each slice any org was granted is fetched once with If-None-Match and replaced in one transaction, only when the answer's revision is higher than the stored one; history windows work the same way. A failed or partial pull changes nothing. Triggers are the trends.updated webhook and an hourly reconciliation.
  • Grants and the 3 h lease. Every local read is scoped by the org's stored grant. A grant MSO denied (enabled: false, 403, or a refused token) is removed at once. A grant MSO has not confirmed for 3 hours stops being honored until the next confirmation. An org not linked to MSO has no grant and no feed. Content may be stale; authorization may not.
  • Owner. MSO Cloud holds the dataset, the spam-review decisions and the recipient list. The app's own tables are its projection only.

8.4 Security controls and the standard each follows

Control Standard
Authorization code with PKCE S256 for every client OIDC Core 1.0; RFC 7636; RFC 9700 (OAuth 2.0 Security BCP)
Client authentication by signed JWT assertion, no shared client secrets RFC 7523 (private_key_jwt)
JWT access tokens with a fixed aud and one org RFC 9068; RFC 8707 resource indicators
Exact redirect URIs, static first-party clients, dynamic registration off RFC 9700 §2.1, §4.1
Refresh-token rotation with family revocation RFC 9700 §4.14
Server-side session id, revocable OWASP ASVS V3 (session management)
Logout to every app OIDC Back-Channel Logout 1.0
Account linking only with proof of both accounts; the MSO provider is never trusted for implicit linking OWASP ASVS V2; the library's verified-email default
Signed, idempotent webhooks HMAC-SHA256 with event-id replay protection
Library patch SLA of 7 days for the issuer library, the sign-in libraries and the JOSE library Operating control

9. Architecture decisions#

Decision Summary
D1 Platform core plus satellites, each app on its own origin; no path zones, iframes or shared secrets
D2 One issuer, https://msocloud.net, served by a certified sidecar
D3 Server-side session id and revocation table first
D4 Tenant-host users reach apps with zero prompts through a single-use handoff
D5 Verified email recorded in MSO
D6 Claim contract: orgs[] in the ID token, one org per access token
D7 Entitlement reuses the plugin install ledger
D8 Org pushed on install, users just-in-time, changes by signed webhooks
D9 Linking an existing app account needs proof of both accounts
D10 Platform API v1, one scope per data plane
D11 Logout everywhere through back-channel logout
D12 Shared contract and design tokens as versioned packages
D13 White-label orgs: branded login on the issuer; an app host on the customer's domain follows
D14 Moving the web sign-in library is a separate decision, ADR 0059 (gate 2027-Q2)
D15 Data ownership: analytics in MSO, creative and workflow data in the app (section 8.3)

All of these are recorded in ADR 0058. D15's source key is amended by ADR 0061 D7. The ContentHeat side is recorded as its decision D225 (relying party of MSO Cloud).

10. Quality scenarios#

Scenario Response Measure
An admin signed in at acme.msocloud.net clicks the ContentHeat tile App opens on the same org and brand 0 login prompts (J1)
An MSO admin removes a member Webhook plus next-login claims remove access in the app Member absent from the next claims
A user signs out in either app Every app tab is signed out ≤ 5 s to 401 (J5)
The issuer library releases a minor version Conformance suite reruns before upgrade OpenID Basic, Config, RP-Initiated and Back-Channel Logout profiles pass
The issuer is down Existing app sessions continue; new logins fail closed with a Vietnamese message No data exposure; recovery by router label
Trends change in MSO trends.updated refreshes the app projection 14-day per-brand count delta 0
A second app joins Satellite kit: manifest, client, relying-party wiring, conformance specs ≤ 2 engineer-weeks

Acceptance for a linked org. All of these hold:

  • a real admin performs journeys J1, J2, J3 and J5 (the specs ship in @younetgroup/platform-contract);
  • 0 users are left unmatched;
  • the 14-day trend-count reconciliation delta is 0;
  • logout takes <= 5 s.

11. Risks and technical debt#

CI runs pnpm --filter @yng/idp test:conformance after unit tests. This separate integration tier starts the issuer on loopback with an in-memory adapter; the pure unit configuration excludes it.

Risk or debt Mitigation
Operating an identity provider (frequent library advisories) Configuration-only use of a certified library; 7-day patch SLA; issuer conformance; external review of the authorization server before the second customer org
Identity split-brain: a role removed in MSO stays live in an app No app-local password for linked users; claims refreshed at every login; webhooks; back-channel logout; trend-count reconciliation in verify:data
The handoff route becomes a session-minting hole Single-use, 60-second, sid-bound token; same-site check; audit row; rate limit; operator review before merge
Wrong account or org link Credential proof; super-admin-only org links; per-org unlink; rehearsal on a DB clone
White-label users see msocloud.net in the address bar during sign-in Branded login on the issuer; an app host on the customer's own domain removes it
MSO still runs Auth.js 5.0.0-beta.32 ADR 0059 decides the move (gate 2027-Q2); the issuer contract is frozen so apps do not notice
The vendor's terms on storing and redistributing the trend data are open The feed goes only to orgs that hold it, so the recipient list is a written fact; one MSO sync replaces ContentHeat's own vendor connector (ADR 0061)
Contract package sits on a different GitHub owner than ContentHeat Move the ContentHeat repo into younetgroup; token as BuildKit secret meanwhile

12. Glossary#

Term (en) Vietnamese Meaning
Issuer / IdP Nơi cấp danh tính The one service that signs ID and access tokens: https://msocloud.net
Relying party (RP) Ứng dụng tin cậy IdP An app that accepts the issuer's tokens instead of keeping its own passwords
Satellite app Ứng dụng vệ tinh An app with its own repo, database and deploy that signs in through MSO
Entitlement Quyền dùng ứng dụng Whether an org has an app, on which plan, until when
Launcher Trình mở ứng dụng The grid of enabled apps shown in every app's top bar
Handoff token Token chuyển phiên Single-use, 60-second token that carries a session from a tenant host to the issuer host
Back-channel logout Đăng xuất qua kênh sau Server-to-server logout message from the issuer to each app
Step-up Xác thực tăng cường A fresh second factor asked before a sensitive action
Data plane Mặt phẳng dữ liệu One of three datasets that never mix: 1st-party marketplace, 1st-party marketing, 3rd-party market-intel
Projection Bản chiếu dữ liệu An app's read copy of data another system owns, reconciled against the owner
Grant Quyền đọc đã cấp An org's stored right to read the trend feed's slices in an app; lapses after 3 hours without MSO confirming it