Real accounts and paid subscriptions plan¶
Status: product and architecture proposal Date: 2026-08-21
Audience: product, identity, backend, frontend, security, privacy, and billing reviewers
Lifecycle: proposed architecture with implementation tracked separately. The platform roadmap owns delivery status, and the Accounts and identity UX implementation plan owns player journeys and interaction details.
This document designs the "real user identity" and "payments" items currently parked as one-line placeholders in the platform roadmap's Phase 8+ backlog. It complements the Engagement platform plan, which already locked several identity/payment decisions in its "Accounts and anonymous migration" section — this document does not relitigate those, it makes them concrete enough to sequence into numbered phases and implement. Where the two documents overlap, the Engagement platform plan remains authoritative on product principles; this document is authoritative on the technical design.
Product reviewers can focus on the decisions and user/account boundaries. Implementers should also read the identity, merge, session, entitlement, and rollout sections. Operational deletion behavior is maintained separately in the Account Deletion Runbook.
What already exists (do not rebuild)¶
- Anonymous-first identity. A signed, httpOnly
userIdcookie (CookieSigner,HttpContextExtensions.GetUserId()) is the single, cookie-only source of identity for every endpoint today — deliberately not header-based, to prevent IDOR. The frontend proxy (proxy.ts) issues and re-signs it; the cookie is domain-scoped to.verbolus.comin production for cross-subdomain reuse. PlayerEntity(Cosmosplayerscontainer, partition key/userId) already has aLinkedIdentitieslist,Stats,Streaks,Settings, and group memberships — it was explicitly built to support a later real-account merge (seePlayerResponse.cs).- Groups (
GroupEntity/GroupStandingsEntity) are keyed byuserIdthroughout, with an ownerUserIdfield. - Export and delete already exist (
PlayerExportResponse.cs) — account deletion must extend this, not duplicate it. - Secrets pattern. Sensitive Terraform variables (
cookie_signing_key,admin_debug_key,application_insights_connection_string) are supplied out-of-band and injected as native Container Apps secrets (tf/backend/container_app.tf). No Key Vault exists yet — new secrets (OIDC client secret, Stripe keys) should follow this same pattern unless the number of secrets or rotation needs outgrow it. - Feature flags. Azure App Configuration +
TargetingFilter, evaluated server-side viaHttpUserIdTargetingContextAccessor, already supports per-user rollout gating (tf/backend/feature_flags.tf). Reuse this to gate sign-in/payments rollout rather than a branch-based flag. - Locked product decisions (from
doc/engagement-platform-plan.mdand the account UX design, restated here because they drive the technical design): use Microsoft Entra External ID and its hosted credential UI instead of storing or processing passwords in Verbolus; launch with Entra local email/password, Google, and personal Microsoft-account sign-in, with Facebook optional; separateplayerId(canonical person),installationId(one browser/PWA install), and external identity (OIDC issuer + subject); sign-in must merge, never replace, an anonymous identity; accounts are required for payments, multi-device sync, and durable cross-device notification history, but not for ordinary anonymous play; monetization must never change competitive outcomes (paid tier may remove ads, add cosmetics/archives — never better puzzles or scores).
Decisions this document adds¶
1. Identity provider¶
| Option | Fit |
|---|---|
| Microsoft Entra External ID (CIAM) | Selected. Azure-native, sits next to the existing App Configuration/Container Apps/Cosmos managed-identity investment, and hosts local email/password plus configured social sign-in. Verify personal Microsoft accounts end to end before launch. |
| Auth0 / Clerk | Better out-of-the-box Next.js SDKs and hosted-UI customization; adds a second vendor, a second billing relationship, and a second place secrets can leak. Fallback if External ID's hosted UI proves too rigid or its social-provider list too narrow. |
| Roll-your-own (password/magic link) | Rejected — contradicts the locked "hosted sign-in over building passwords" decision, and adds password storage, breach, and deliverability liability the team doesn't need to take on. |
Before public launch, complete configuration acceptance tests for hosted-UI branding, local email/password sign-up and recovery, Google, and personal Microsoft accounts. Configure Facebook only after product/privacy approval. Auth0/Clerk remain contingency options only if a release-blocking Entra limitation is discovered; they are not an open implementation choice for this branch.
2. Session architecture — extend the existing cookie, don't replace it¶
The existing userId cookie is deliberately the only identity signal every endpoint trusts.
Keep that invariant. Rather than introducing a parallel JWT/session system, evolve
CookieSigner's payload from a bare ID into a small signed struct:
GetUserId()keeps working unchanged for every existing endpoint (it already treats unsigned/legacy cookies as trusted-as-is, per its own doc comment — the new payload shape gets the same kind of graceful fallback).authLevelis the only new concept: endpoints that require a real account (billing, cross-device notification registration) check forverified; everything else keeps working identically for anonymous players.- Unlike the anonymous cookie (effectively permanent), a
verifiedsession gets a real expiry/rotation window, refreshed by the Next.js BFF layer. - Next.js is the OIDC client (BFF pattern). The authorization-code + PKCE exchange happens
server-side in a new route handler alongside
proxy.ts; access/refresh/ID tokens from the IdP never reach client JS. Once the ID token is validated, the handler calls the non-mutating identityprepareoperation described below. It mints/updates the verified signed cookie only after an immediate or user-confirmedcommitreaches its safe checkpoint. The ASP.NET Core backend never talks to the IdP directly — it reads the forwarded signed cookie and trusts only the BFF's authenticated internal identity call.
3. Anonymous → account merge¶
Two paths, not one:
- Promote (common case). The anonymous player has no
LinkedIdentitiesentry and no canonical account exists yet for this external identity → attach the external identity to the existingPlayerEntityin place. No data moves. This is the cheap, default path and should be the outcome for the large majority of first-time sign-ins. - Merge (device already has an account elsewhere). A canonical player for this external
identity already exists (e.g., signing in on a second device) and is distinct from the
current anonymous player → run the full merge described in
doc/engagement-platform-plan.md("Merge workflow", 9 steps). Concretely for this codebase: - Look up the external identity →
playerIdmapping via a point read against the existinglookupscontainer (already planned for join-code/name-uniqueness lookups — add a second key shape for this, still point-read only). - Recompute stats/streaks from source
playsdocuments rather than algebraically summing two uncertain aggregates (matches the already-locked principle). playsdocuments are partitioned by{puzzleKey}|{userId}— reassigning ownership means recreating each document under the new partition key, not an in-place update. Prototype the cost/complexity of this against the alternative of a permanent alias table (never physically moveplays, just resolve reads through old→newuserIdaliases) before committing to "repoint" as literally moving data.- Repoint group memberships and any push subscriptions (once those exist) to the canonical
playerId. - Use the non-mutating
prepare→ optional/account/finishpause → idempotentcommitprotocol specified indoc/accounts-identity-ux-implementation-plan.md, section 6.2.1.preparecomputes the disposition and preview without linking or moving data. Write a durable merge-operation record (id, status) beforecommitmutates anything, so a crash/retry resumes the same operation rather than applying twice. - The common uncontended commit may finish in one request, but the durable operation/status
contract must also support
merge_account_busy, bounded polling, crash recovery, andneeds-reconfirmation; do not hold one HTTP request indefinitely or introduce a general queue/saga framework for v1. - Show the user the "streak, plays, groups, settings that will be attached" preview before
committing whenever a decision is required. Keep the original guest cookie active during
that callback-to-completion pause and mint
authLevel=verifiedonly after the safe checkpoint.
3a. Duplicate-play and concurrent-merge rules¶
These are implementation decisions, not open questions. The merge workflow generalizes to any
number of devices by merging each additional source into the current canonical playerId, one
incoming-source operation at a time. Each operation must nevertheless rebuild its authoritative
input from the canonical account's complete alias closure; it must not reason from only the two
PlayerEntity aggregate snapshots.
Duplicate logical plays¶
A logical play is identified by its game-owned puzzle identity (currently puzzleKey; for the
global Daily this already includes game, scope, and date). Build one authoritative play set before
recomputing stats, streaks, scorecards, or standings.
For two records with the same logical puzzle identity:
- A completed play beats an in-progress play.
- If both are completed, the earliest completion is the official result. Do not choose by score. Letter Golf is lower-score-wins, so the earlier proposal to keep the higher score was directionally wrong; choosing either the best or worst result would also let account merging become a way to shop multiple guest attempts. “First completion wins” preserves the game's one-official-Daily-attempt rule independently of scoring direction.
- Add an immutable nullable
completedAtUTC field toPlayEntity, assigned by the server only on the transition fromInProgresstoCompleted; never accept it from the client or change it on later saves. For legacy completed records without it, useupdatedAtas the compatibility fallback. If timestamps are equal, missing, or otherwise indistinguishable, keep the pre-merge canonical target's record; if neither is from the canonical target, use ordinalplayKey({puzzleKey}|{userId}today) as the final deterministic fallback. Never use current wall-clock time during merge. - Combine stats-eligibility flags conservatively. In particular, if any duplicate says solutions were viewed before completion, the merged logical play remains excluded from stats/streaks; merging another device must not erase the self-spoiled state.
- The non-authoritative duplicate does not contribute to stats, streaks, scorecards, group standings, or the resumable current play. Preserve it as a superseded merge record (or preserve equivalent provenance in the durable merge record) for export, support, and deletion until its normal retention expires; label its exclusion reason. Do not silently destroy user data merely to deduplicate an aggregate.
- Practice puzzles with distinct puzzle IDs stay distinct. If a future game can produce duplicate records under one logical ID with different semantics, that game must supply an explicit pure merge resolver before its records can be merged; identity code must not assume higher or lower scores are universally better.
Streaks are recomputed after play deduplication. A Daily date contributes at most once for each
gameType + scope + puzzleDate, and only when the authoritative logical play is stats-eligible.
Chronologically replay the union of qualifying dates, so overlap never double-counts a day and
non-overlapping source dates extend the combined streak normally.
Concurrent merges and alias-graph safety¶
The durable operation ID makes retries of one operation idempotent; operation-owned account
leases serialize different operations that race into the same canonical account. A target-only
lease is not sufficient by itself: reciprocal A → B and B → A operations could each lock their
own target and create an alias cycle. Therefore each merge reserves both current canonical roots.
- Create/find the durable merge-operation record first. The same source, target, and sign-in attempt reuse the same operation ID.
- Resolve the current canonical roots of source and target. If they are already the same root,
finish idempotently. Otherwise acquire renewable ETag-guarded leases on both root
PlayerEntityrecords in ordinalplayerIdorder. Each lease containsoperationId,acquiredAt, andleaseUntil. Stable ordering prevents deadlock; if acquisition is partial, release only leases still owned by this operation and retry with bounded jitter. - After both leases are held, resolve both roots again. If either changed while the leases were being acquired, release the owned leases and retry root resolution with the same operation ID. This invariant plus the ordered pair of leases prevents alias forks and cycles.
- A different operation that owns an unexpired required lease returns internal error code
merge_account_busywith HTTP 409 andRetry-After. The BFF waits/polls with bounded jitter and retries the same commit/operation; ordinary UI shows processing, not an error. - If a holder crashes, its leases expire. A retry may take them over with an ETag compare/exchange
and resume from durable operation state. Renew during work and release/clear a lease only when
its operation ID still owns it. Never use a permanent Boolean
merge-in-progressmarker. - With both stable roots reserved, re-read the target, every alias already merged into it, and the new source closure. Rebuild the deduplicated authoritative play set from that fresh union. This is essential: a second merge must include the first merge's source plays even when physical play migration has not occurred.
- Recompute the material decision fingerprint used by the merge preview: duplicate-play winners,
display-name choice, billing/canonical-account choice, and any other user-visible conflict. If a
preceding merge changed that fingerprint, stop in
needs-reconfirmationand render a refreshed preview. If only non-material counts changed, the BFF may continue the serialized retry without bothering the player. - Persist the canonical player with ETag protection. On an ETag conflict, re-read and recompute while both leases are still owned; never overwrite a newer settings/stats write with the stale snapshot.
- Mark the source alias, update identity/group mappings, and reach the documented safe checkpoint before completing the operation. A post-commit reconciler repairs non-critical projections and captures plays completed concurrently with the merge.
- Two operations for the same source and target converge idempotently. If a source is already merged into a different target, reject the new direction as a conflict; never create an alias fork or merge loop.
The leases are an internal coordination detail. Do not hold an HTTP request open indefinitely, do not blindly retry with a new operation ID, and do not expose raw account IDs or lease state to the browser.
4. BFF-to-backend trust boundary¶
The Next.js BFF validates the OIDC token itself (signature, issuer, audience, nonce) and then
needs to tell the backend "link/merge this external identity onto playerId=X." The backend
must not trust a client-asserted {issuer, subject, playerId} directly — that's the same IDOR
class of risk HttpContextExtensions.GetUserId()'s doc comments already warn about for the
anonymous cookie.
Decision: Microsoft Entra app-to-app auth via Managed Identity, not a shared secret. A
static shared secret (mirroring the existing Admin:DebugKey pattern) was the initial default,
but rejected in favor of this because it requires no rotation runbook ever — Azure and Entra
own key issuance and rotation entirely; no credential exists to leak or rotate in production.
This also matches the security posture AGENTS.md already states: "Keep secrets out of
source and use identity-based access where supported."
Mechanism:
- A user-assigned managed identity on the frontend (
minigame-www) Container App. - A second Entra app registration, in the normal organizational tenant (not the customer-
facing
verbolus.onmicrosoft.comCIAM tenant), representing "the backend API" as a protected resource, with an app role (e.g.Internal.IdentityLink). - An app role assignment granting the frontend's managed identity that role — this is the actual access-control decision ("only the BFF may call internal identity-link endpoints").
- Frontend:
@azure/identity'sDefaultAzureCredential().getToken("api://<backend-app-id>/.default")acquires a short-lived token via the managed identity automatically when running in Azure. - Backend:
Microsoft.Identity.Web'sAddMicrosoftIdentityWebApi()validates the bearer token against the org tenant, fetching/caching/rotating Entra's JWKS itself — no custom JWKS code. Internal-only endpoints (e.g.POST /v1/internal/identity/prepareandPOST /v1/internal/identity/commit) require[Authorize(Roles = "Internal.IdentityLink")].playerIditself is still resolved from the existing signed cookie, exactly like every other endpoint — never from the request body.
Local development fallback (Managed Identity does not exist outside Azure compute):
DefaultAzureCredential is a chain — EnvironmentCredential is checked before
ManagedIdentityCredential, so supplying three standard environment variables makes local dev
(bare npm run dev, or a local Docker container) work with zero code branching:
AZURE_TENANT_ID— the org tenant ID (same tenant as the backend API app registration above, not the CIAM tenant).AZURE_CLIENT_ID/AZURE_CLIENT_SECRET— client ID/secret of a small, dedicated app registration/service principal, e.g.verbolus-bff-local-dev, that exists only to stand in for the managed identity locally. It gets the sameInternal.IdentityLinkapp role assignment on the backend API app as the real managed identity, and nothing else. Treat its secret like any other local dev credential: gitignored, narrowly scoped, easy to revoke, never used in Container Apps.
These three vars, plus BFF_BACKEND_SCOPE, are documented in frontend/minigames/.env.example
and the root README.md configuration reference table — see those files for the
authoritative shape. tf/bff_identity.tf defines the Entra resources;
frontend/minigames/src/lib/internal-identity-client.ts is the server-only client that
acquires the token and forwards the caller's Cookie header.
Known trade-off: this makes the internal identity-link endpoint the first piece of this codebase where local backend/frontend development requires real internet connectivity — there is no offline emulator for Entra ID, unlike the Cosmos DB Emulator. Every other local dev path (dictionaries, Cosmos, the rest of the API) stays fully offline-capable; only this one endpoint family needs to reach Microsoft's real endpoints, for both token acquisition and validation.
Testing: this codebase already has WebApplicationFactory-based integration tests (see
MiniGamesBackEnd.Tests/PlayerEndpointsTests.cs). Don't call the real Entra tenant from tests —
add a test AuthenticationHandler that fabricates a ClaimsPrincipal carrying the
Internal.IdentityLink role claim directly, matching the existing fake-store-substitution
pattern already used for IPlayerStore in those tests. Keep one separate, infrequent smoke
test against real deployed infrastructure for the actual end-to-end Entra flow.
Payments and subscriptions¶
Provider¶
| Option | Fit |
|---|---|
| Stripe (Checkout + Billing + Customer Portal) | Selected; the Stripe-side setup already exists. Hosted Checkout keeps 100% of PCI scope off this codebase. Handles proration, dunning/retries, and Stripe Tax for many jurisdictions. Lower fees than a merchant-of-record. |
| Paddle (or similar merchant-of-record) | Worth a second look given the team's size: Paddle acts as merchant of record and absorbs global consumer VAT/sales-tax registration and remittance entirely, at the cost of higher fees and less control. If Stripe Tax's jurisdiction coverage or the team's appetite for tax registration is a blocker, fall back here rather than building in-house tax handling. |
Proceed with Stripe. Revisit a merchant-of-record only if tax-compliance overhead becomes a real release blocker; it is not an open implementation choice for the current work.
Entitlement model¶
Start with a single entitlement — AdFree — matching the exact concept doc/advertising-strategy.md
already assumes ("paid ad removal ... removes third-party advertising everywhere the entitlement
is active"). Design the field as a small map so future entitlements (cosmetic themes, puzzle
archive access) extend it without a new schema:
PlayerEntity.Entitlements = {
AdFree: bool,
StripeCustomerId: string,
StripeSubscriptionId: string,
SubscriptionStatus: string, // mirrors Stripe's subscription status
CurrentPeriodEnd: DateTime,
}
Storing this on PlayerEntity (not a separate container) means the hot "is this user ad-free"
check on every page load stays a single point read by userId — no extra RU cost or fan-out.
New billing container¶
Add a billing container (partition key /playerId, shared database autoscale like the
others) for:
- Webhook idempotency. Stripe's own guidance is to key processed events by their event ID;
store
{ eventId, processedAt }and reject/no-op replays before mutatingEntitlements. - Payment/subscription history, for support and for the existing export/delete flow to include (payment metadata is user data too).
Keeping billing data in its own container (rather than folding it into players) leaves room
for tighter Cosmos RBAC scoping later if that granularity becomes available, and keeps the
sensitive audit trail out of the same document every ordinary read touches.
Flows¶
- Checkout. "Sign in to subscribe" (already a documented soft-prompt) → backend creates a
Stripe Checkout Session server-side (
client_reference_id = playerId, success/cancel URLs back to Settings) → redirect to Stripe-hosted Checkout → webhook confirms and flipsEntitlements.AdFree→ user lands back on Settings. - Manage/cancel. Use Stripe's hosted Customer Portal (link generated server-side) instead of
building custom billing UI. Decide explicitly: cancellation take effect at
CurrentPeriodEnd(the player keeps what they paid for), not immediately — this needs product sign-off but is the conventional default and avoids a mid-period clawback. - Webhook endpoint (
POST /v1/billing/webhook): verify theStripe-Signatureheader against the webhook signing secret before processing anything; handlecheckout.session.completed,customer.subscription.updated/deleted,invoice.payment_failed; respond 2xx fast and do slow work (if any) out of band. - Card data, CVV, and full PANs never reach this codebase — Stripe Checkout/Portal own that entirely.
UI/UX workflow¶
Reuse the soft-prompt moments already specified in doc/engagement-platform-plan.md — do not
invent new interruption points. New surfaces needed:
- Sign-in launcher — a "Sign in" entry point in Settings, plus the existing contextual prompts (protect your streak, keep this group, sign in to subscribe, cross-device notifications). A minimal custom screen redirects to the IdP's hosted UI; no custom password/social-button matrix to build if External ID's hosted UI is used directly.
- Merge preview dialog — shown once, right after OIDC callback, before the session is
finalized: streak, plays, groups, and settings about to be attached. Needs focus management
and screen-reader-friendly copy per
accessibility.instructions.md, and i18n-ready strings perglobalization.instructions.md. - Settings → Account section (extends
settings-form.tsx) — sign-in state, linked identity, display name, "Subscribe to remove ads" CTA or "Manage subscription" (Customer Portal link) once subscribed, "Sign out," and "Delete account" wired into the existing export/delete flow (extended to also cancel any active Stripe subscription and purgebillingrecords). - Ad-surface entitlement check — must short-circuit ad loading the instant
Entitlements.AdFreeis true, the same way the existing consent/kill-switch checks already gate ad loading — no reload or redeploy required. - Privacy Policy update —
doc/engagement-platform-plan.mdalready flags the Privacy page as inaccurate about what's collected; adding payment processor data (Stripe customer ID, subscription status) makes this more urgent, not less.
Security¶
- OIDC flow correctness. Authorization code + PKCE, validated
stateandnonce, ID token signature/issuer/audience validation server-side only (BFF pattern above) — never trust a client-supplied token. - CSRF. The merge and checkout-session-creation endpoints are state-changing and
cookie-authenticated; add explicit CSRF protection (double-submit token or
SameSite=Strict/Lax plus an anti-forgery token), matching this being a cross-site-cookie risk area the anonymous-only endpoints didn't previously have to consider. - No header-trust regression. Keep identity cookie-only, exactly as
HttpContextExtensions.GetUserId()already documents — the newauthLevelfield must not become a second, spoofable identity path. - Webhook verification. Always verify
Stripe-Signature; treat an unverifiable webhook as untrusted input, not as an authenticated event. - Rate limiting. Apply the same per-IP rate-limiting pattern already used for
play-endpoints/verify-wordto/v1/auth/*and/v1/billing/*. - Secrets. OIDC client secret, Stripe secret key, and Stripe webhook signing secret follow the existing native Container Apps secret + sensitive Terraform variable pattern; revisit Key Vault only if secret count/rotation cadence outgrows that.
- Least privilege / data minimization. Never store card data. Store only the Stripe customer/subscription IDs needed to manage entitlements and support requests.
- Compliance surface.
doc/engagement-platform-plan.mdflags that the audience age policy is not yet decided — resolve this before shipping payments, since it determines whether age-gating or parental consent applies to purchases.
Testing¶
- Backend unit tests: cookie payload signing/parsing (including
authLevel/expiry), promote-vs-merge decision logic; completed-over-in-progress and earliest-completedAtduplicate resolution; legacy timestamp/tie fallback; conservative stats-eligibility taint; superseded-play provenance; chronological streak recomputation from unique eligible dates; ordered root-pair lease acquisition/partial release/renewal/expiry/owner-only release and reciprocal-merge cycle prevention; material preview-fingerprint changes; Stripe webhook signature verification; and entitlement application logic — all as pure/testable units, consistent with existing conventions. - Integration tests (Cosmos emulator): promote path; full-merge path with overlapping puzzle
histories and no double-counting; source provenance remains exportable/deletable; merge retried
after a simulated crash (idempotent); two distinct sources racing into one canonical target
serialize, with the second recomputing from the full alias closure; reciprocal
A → B/B → Aoperations cannot create a cycle; a live required lease returnsmerge_account_busyplusRetry-After; expired lease takeover; a materially stale preview returnsneeds-reconfirmation; concurrent late-play reconciliation; group membership correctly repointed post-merge; and webhook replay (same event ID twice → no double effect). - Contract tests: OpenAPI additions for new
/v1/internal/identity/*and/v1/billing/*endpoints, including stable machine codes andRetry-Aftersemantics. - Frontend unit tests (Vitest): sign-in launcher, merge preview dialog, account/subscription settings section, merge processing/retry/refreshed-preview states, entitlement-gated ad surface.
- Playwright journeys: anonymous play → sign in → merge preview → confirm → stats/groups
retained; overlapping Daily plays preserve the first completed official result; a busy target
stays on
Combining your progress…and completes without duplicate effects; subscribe with a Stripe test-mode card → ad-free entitlement active; cancel via Customer Portal → entitlement remains active untilCurrentPeriodEnd, then lapses. - Accessibility: review new screens against
accessibility.instructions.md, especially focus handling across the redirect-heavy OIDC flow.
Infrastructure / Terraform¶
- IdP bootstrap is likely a one-time manual/Graph step, not fully declarative from day one —
Terraform's provider support for creating an Entra External ID (CIAM) tenant itself is
limited; treat it like
tf/meta/bootstrap.tf's existing one-time setup pattern. Once the CIAM tenant exists, the app registration (redirect URIs, client secret) can be Terraform-managed. - New Container Apps secrets:
oidc-client-secret,stripe-secret-key,stripe-webhook-secret, added the same way as the three existing secrets intf/backend/container_app.tf, sourced from out-of-band sensitivetfvars/env vars. - New Cosmos container:
billing, partition key/playerId, added to the shared database autoscale whereverplayers/groupsare provisioned today. - Rollout gating: use the existing Azure App Configuration +
TargetingFiltermechanism to stage sign-in/payments to an internal cohort first, matching how other risky features have shipped. - CORS/cookie domain: confirm the OIDC redirect URI and the extended session cookie both
work cleanly with the existing
.verbolus.comcookie-domain and enumerated-origins CORS policy — no relaxing of either is expected to be needed. - BFF-to-backend trust boundary (see "4. BFF-to-backend trust boundary" above): a second
azuread_application/azuread_service_principal(org tenant, not the CIAM tenant) representing the backend API, with anapp_roleblock forInternal.IdentityLink; a user-assigned managed identity onminigame-www, granted that role via anazuread_app_role_assignment; and a small separateverbolus-bff-local-devapplication/service principal + client secret, granted the same role, for local development only (never referenced fromtf/backend/container_app.tfortf/frontend/container_app.tf). Theazureadprovider is already configured intf/providers.tf(used today for the CI/CD app registration intf/cicd.tf) — no new provider setup needed.
Deferred: custom URL domain for the hosted sign-in page¶
Status: deferred, cosmetic only, not a blocker for any phase below.
Today's Entra External ID tenant uses the default shared domain
(verbolus.ciamlogin.com). Because Google (and any other social IdP) derives the title it
shows on its own consent screen from the redirect URI's domain, users signing in with Google
see a generic "Sign in to ciamlogin.com" branding instead of "Verbolus." This is expected
behavior for the shared default domain and does not affect security or functionality — it is
purely cosmetic.
Microsoft documents a supported fix: put a custom domain in front of the tenant's default domain via Azure Front Door. Revisit this once a production domain is finalized, to avoid doing the DNS/Front Door work twice.
Steps (per Microsoft Learn, "How to enable custom URL domains for External ID")¶
- Add and verify a custom domain name on the tenant — Entra ID > Settings > Domain names >
Custom domain names, then add a DNS
TXTrecord on the chosen subdomain (e.g.login.verbolus.com) to verify ownership, then delete the TXT record once verified. - Associate the verified domain with a custom URL domain — Entra ID > Domain names > Custom URL domains > Add custom url domain.
- Create an Azure Front Door instance — Standard or Premium tier; origin type
Custom, origin host name<tenant-name>.ciamlogin.com(verbolus.ciamlogin.com); origin Host name and Origin host header must match. - Point the custom domain at Front Door — create a
CNAMErecord (e.g.login.verbolus.com→<endpoint>.azurefd.net), add the domain in Front Door's Domains blade, verify via a_dnsauthTXT record, associate the domain with the Front Door endpoint, and enable default-route. - Test — run a user flow and substitute the custom domain for
verbolus.ciamlogin.comin the browser URL bar; confirm sign-in still works. - Update the Google OAuth client's authorized redirect URIs to use the custom domain
instead of the current
verbolus.ciamlogin.com/tenant-ID-based URIs, and update the app's own OIDC configuration/redirect URIs accordingly. - (Optional, later) Submit a support ticket to block the default
ciamlogin.comdomain — only after confirming the custom domain works, since blocking removes access to the default domain entirely.
Caveats¶
- Requires Azure Front Door (Standard or Premium tier) as a permanent, additional Azure resource — this is infrastructure to provision, monitor, and maintain, not a one-time setting.
- Needs a production domain/subdomain decided first (e.g.
login.verbolus.com); doing this before the production domain is finalized risks redoing the DNS/CNAME/TXT work. - Any redirect-URI change requires re-registering with Google's OAuth client and retesting the full sign-in flow end-to-end.
- Purely cosmetic — does not change token validity, security posture, or user data handling.
Monetary cost¶
- Azure Front Door Standard tier: base platform fee (~US$35/month) plus usage-based charges for routing/data transfer/requests. Premium tier costs more and adds managed WAF rule sets, which this scenario doesn't need.
- No other new recurring cost — DNS record changes are typically free with the existing domain registrar.
Proposed phasing (for doc/roadmap.md Phase 8+)¶
Split the current one-line "Real user identity" backlog item into three sequenced sub-phases:
- 8a — Identity foundation. IdP spike/setup, sign-in/sign-out, session cookie evolution
(
authLevel), promote-path merge, full-merge path, merge preview UI, Settings account section. No payments yet. - 8b — Subscriptions. Stripe integration, checkout, webhook, Customer Portal,
AdFreeentitlement enforcement, Settings subscription management, Privacy Policy update. - 8c — Cross-device follow-ons. Push notification targeting by canonical
playerId(unblocks the existing Phase 8+ push-notifications item), cross-device group-nudge attribution, account deletion fully wired through export/delete, i18n of new screens.
Remaining open questions before the affected phases ship¶
- Pricing, tiers, and trial policy — not decided.
- Audience age policy (flagged as undecided in
doc/engagement-platform-plan.md) — determines whether payments/accounts need age-gating or parental consent. - Immediate-vs-period-end cancellation behavior — needs explicit product sign-off.
- Whether merge-time
playsreassignment should physically move documents (recreate under a new partition key) or resolve through a permanent userId-alias table — prototype both before committing.