Skip to content

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 userId cookie (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.com in production for cross-subdomain reuse.
  • PlayerEntity (Cosmos players container, partition key /userId) already has a LinkedIdentities list, Stats, Streaks, Settings, and group memberships — it was explicitly built to support a later real-account merge (see PlayerResponse.cs).
  • Groups (GroupEntity/GroupStandingsEntity) are keyed by userId throughout, with an owner UserId field.
  • 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 via HttpUserIdTargetingContextAccessor, 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.md and 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; separate playerId (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.

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:

{ playerId, authLevel: "anonymous" | "verified", issuedAt, expiresAt }
  • 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).
  • authLevel is the only new concept: endpoints that require a real account (billing, cross-device notification registration) check for verified; everything else keeps working identically for anonymous players.
  • Unlike the anonymous cookie (effectively permanent), a verified session 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 identity prepare operation described below. It mints/updates the verified signed cookie only after an immediate or user-confirmed commit reaches 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:

  1. Promote (common case). The anonymous player has no LinkedIdentities entry and no canonical account exists yet for this external identity → attach the external identity to the existing PlayerEntity in place. No data moves. This is the cheap, default path and should be the outcome for the large majority of first-time sign-ins.
  2. 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:
  3. Look up the external identity → playerId mapping via a point read against the existing lookups container (already planned for join-code/name-uniqueness lookups — add a second key shape for this, still point-read only).
  4. Recompute stats/streaks from source plays documents rather than algebraically summing two uncertain aggregates (matches the already-locked principle).
  5. plays documents 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 move plays, just resolve reads through old→new userId aliases) before committing to "repoint" as literally moving data.
  6. Repoint group memberships and any push subscriptions (once those exist) to the canonical playerId.
  7. Use the non-mutating prepare → optional /account/finish pause → idempotent commit protocol specified in doc/accounts-identity-ux-implementation-plan.md, section 6.2.1. prepare computes the disposition and preview without linking or moving data. Write a durable merge-operation record (id, status) before commit mutates anything, so a crash/retry resumes the same operation rather than applying twice.
  8. 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, and needs-reconfirmation; do not hold one HTTP request indefinitely or introduce a general queue/saga framework for v1.
  9. 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=verified only 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:

  1. A completed play beats an in-progress play.
  2. 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.
  3. Add an immutable nullable completedAt UTC field to PlayEntity, assigned by the server only on the transition from InProgress to Completed; never accept it from the client or change it on later saves. For legacy completed records without it, use updatedAt as 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 ordinal playKey ({puzzleKey}|{userId} today) as the final deterministic fallback. Never use current wall-clock time during merge.
  4. 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.
  5. 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.
  6. 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.

  1. Create/find the durable merge-operation record first. The same source, target, and sign-in attempt reuse the same operation ID.
  2. 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 PlayerEntity records in ordinal playerId order. Each lease contains operationId, acquiredAt, and leaseUntil. Stable ordering prevents deadlock; if acquisition is partial, release only leases still owned by this operation and retry with bounded jitter.
  3. 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.
  4. A different operation that owns an unexpired required lease returns internal error code merge_account_busy with HTTP 409 and Retry-After. The BFF waits/polls with bounded jitter and retries the same commit/operation; ordinary UI shows processing, not an error.
  5. 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-progress marker.
  6. 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.
  7. 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-reconfirmation and render a refreshed preview. If only non-material counts changed, the BFF may continue the serialized retry without bothering the player.
  8. 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.
  9. 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.
  10. 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:

  1. A user-assigned managed identity on the frontend (minigame-www) Container App.
  2. A second Entra app registration, in the normal organizational tenant (not the customer- facing verbolus.onmicrosoft.com CIAM tenant), representing "the backend API" as a protected resource, with an app role (e.g. Internal.IdentityLink).
  3. 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").
  4. Frontend: @azure/identity's DefaultAzureCredential().getToken("api://<backend-app-id>/.default") acquires a short-lived token via the managed identity automatically when running in Azure.
  5. Backend: Microsoft.Identity.Web's AddMicrosoftIdentityWebApi() 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/prepare and POST /v1/internal/identity/commit) require [Authorize(Roles = "Internal.IdentityLink")]. playerId itself 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 same Internal.IdentityLink app 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 mutating Entitlements.
  • 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 flips Entitlements.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 the Stripe-Signature header against the webhook signing secret before processing anything; handle checkout.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:

  1. 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.
  2. 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 per globalization.instructions.md.
  3. 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 purge billing records).
  4. Ad-surface entitlement check — must short-circuit ad loading the instant Entitlements.AdFree is true, the same way the existing consent/kill-switch checks already gate ad loading — no reload or redeploy required.
  5. Privacy Policy update — doc/engagement-platform-plan.md already 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 state and nonce, 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 new authLevel field 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-word to /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.md flags 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-completedAt duplicate 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 → A operations cannot create a cycle; a live required lease returns merge_account_busy plus Retry-After; expired lease takeover; a materially stale preview returns needs-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 and Retry-After semantics.
  • 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 until CurrentPeriodEnd, 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 in tf/backend/container_app.tf, sourced from out-of-band sensitive tfvars/env vars.
  • New Cosmos container: billing, partition key /playerId, added to the shared database autoscale wherever players/groups are provisioned today.
  • Rollout gating: use the existing Azure App Configuration + TargetingFilter mechanism 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.com cookie-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 an app_role block for Internal.IdentityLink; a user-assigned managed identity on minigame-www, granted that role via an azuread_app_role_assignment; and a small separate verbolus-bff-local-dev application/service principal + client secret, granted the same role, for local development only (never referenced from tf/backend/container_app.tf or tf/frontend/container_app.tf). The azuread provider is already configured in tf/providers.tf (used today for the CI/CD app registration in tf/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")

  1. Add and verify a custom domain name on the tenant — Entra ID > Settings > Domain names > Custom domain names, then add a DNS TXT record on the chosen subdomain (e.g. login.verbolus.com) to verify ownership, then delete the TXT record once verified.
  2. Associate the verified domain with a custom URL domain — Entra ID > Domain names > Custom URL domains > Add custom url domain.
  3. 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.
  4. Point the custom domain at Front Door — create a CNAME record (e.g. login.verbolus.com → <endpoint>.azurefd.net), add the domain in Front Door's Domains blade, verify via a _dnsauth TXT record, associate the domain with the Front Door endpoint, and enable default-route.
  5. Test — run a user flow and substitute the custom domain for verbolus.ciamlogin.com in the browser URL bar; confirm sign-in still works.
  6. 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.
  7. (Optional, later) Submit a support ticket to block the default ciamlogin.com domain — 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, AdFree entitlement 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

  1. Pricing, tiers, and trial policy — not decided.
  2. Audience age policy (flagged as undecided in doc/engagement-platform-plan.md) — determines whether payments/accounts need age-gating or parental consent.
  3. Immediate-vs-period-end cancellation behavior — needs explicit product sign-off.
  4. Whether merge-time plays reassignment should physically move documents (recreate under a new partition key) or resolve through a permanent userId-alias table — prototype both before committing.