Stanchion docs

Stanchion (formerly cMail): the docs and code keep the old name until the code is renamed.


Onboarding an organisation that uses Microsoft 365

This guide takes a new cmail instance from nothing to "staff sign in with their Microsoft account", for an organisation whose mail stays in Exchange Online. Optional steps then make cmail a warm standby: a standby subdomain, the Exchange mirror, shared mailbox permissions, and the standby switch.

It is the order that worked in the first production onboarding of a Microsoft 365 tenant. Each step says why it is there, what to run (a script from scripts/onboarding/ and the manual equivalent), how to check it, how to undo it, and what tripped us up.

Status. The steps and their order are proven once, on one tenant, with Exchange Online staying primary and its MX untouched. The scripts are parameterised versions of the ones used there; in this form they are tested only against mocks (scripts/onboarding/onboarding.Tests.ps1), not yet against a tenant. Run each with -WhatIf first. The feature docs linked from each step stay the reference for settings and behaviour.

Every step that changes a live system (DNS, Entra, Exchange, a remote database) needs the owner's yes under your own change process.

In this article

Checklist

Placeholders: example.com is the organisation's mail domain, https://mail.example.com the web app, cmail-web the Pages project, apps/email-worker/wrangler.toml the instance's own Worker config.

# Step Done when
0 Accounts, tools, decisions Cloudflare account, Entra admin, az + pnpm + PowerShell 7 ready; names chosen
1 Instance: D1, R2, Worker, Pages, migrations Empty database migrated; Worker and Pages deployed; *.pages.dev answers
2 Custom domain mail.example.com https://mail.example.com answers 200 over HTTPS
3 Sign-in app (new-signin-app.ps1) "Sign in with Microsoft" shows on the sign-in page
4 Bootstrap (set-bootstrap-secrets.ps1, then -Remove) One active manager; /bootstrap redirects
5 Microsoft 365 sync (new-sync-app.ps1) Dry run report reads right; dry run off; counts match Microsoft 365
6 Staff sign-in A synced person signs in with Microsoft, no invitation
7 Passkeys A person signs in at /auth/passkey
8 Welcome emails (optional) One test account got its email
9 Standby subdomain (optional) standby.example.com has Cloudflare MX; apex MX unchanged
10 Exchange mirror (optional, exchange-mirror.ps1) Admin shows reports "filed", none refused
11 Shared mailbox permissions (optional, perms-setup.ps1) Go/no-go is GO; dry run report matches Exchange
12 Standby test, switch, copy-back (optional) Each feature's own drill done

0. What you need first

Purpose. Everything later assumes these are in place; missing one is the usual reason a step stalls halfway.

Pitfalls.

1. Instance

Purpose. Create the storage and deploy both apps before any sign-in exists, so you test each layer on its own.

Run. Follow Deployment and verification sections 1 to 3: create D1 and R2 (pnpm d1:create, pnpm r2:create), fill in the instance's apps/web/wrangler.toml and apps/email-worker/wrangler.toml (set APP_NAME, MAIL_DOMAIN = "example.com" and, for now, APP_URL = "https://<project>.pages.dev"), set SESSION_SECRET and the required inbound Worker secret, then:

# Is the database empty? Both must be 0 for a new instance.
pnpm exec wrangler d1 execute <db name> --remote --config apps/web/wrangler.toml --env="" --command "SELECT count(*) AS c FROM users"
pnpm exec wrangler d1 execute <db name> --remote --config apps/web/wrangler.toml --env="" --command "SELECT count(*) AS c FROM messages"
pnpm db:migrate              # applies every migration in packages/shared/migrations
pnpm deploy:email-worker     # the Worker first: Pages binds to it
pnpm deploy:web

Check. pnpm exec wrangler d1 migrations list DB --remote --config apps/web/wrangler.toml says there is nothing to apply. https://<project>.pages.dev/ answers 200 and shows no sign-in buttons yet (that is correct: no provider is configured).

Undo. Nothing holds mail yet: delete the Pages project, Worker, D1 and R2 in the dashboard if you need to start again.

Pitfalls.

2. Domain for the web app

Purpose. Sign-in callbacks and passkeys are bound to the final web address, so it must be fixed before step 3.

Run (dashboard). Workers & Pages > the Pages project > Custom domains > Set up a domain > mail.example.com. Then, in the zone's DNS, add a proxied CNAME mail -> <project>.pages.dev (if the dashboard did not add it for you). Add the custom domain in Pages first: a CNAME without it returns errors (Pages custom domains).

Then set APP_URL = "https://mail.example.com" in apps/web/wrangler.toml and redeploy the web app (pnpm deploy:web).

Check. curl -sI https://mail.example.com/ answers 200 with a valid certificate.

Undo. Remove the custom domain in Pages and the mail CNAME.

Pitfalls.

3. Sign-in app

Purpose. Staff sign in with their Microsoft 365 account. This app only signs people in: delegated openid email profile, single tenant, nothing else. The sync (step 5) has its own app.

Script.

pwsh -File scripts/onboarding/new-signin-app.ps1 -TenantId <tenant id> `
  -AppUrl https://mail.example.com -PagesProject cmail-web -WhatIf
# then without -WhatIf; add -GrantAdminConsent if users may not consent to apps

It creates (or reuses by name) the app with the Web redirect URI https://mail.example.com/auth/callback/microsoft, stores MICROSOFT_CLIENT_ID and pipes a new client secret from az ad app credential reset into wrangler pages secret put MICROSOFT_CLIENT_SECRET (az ad app credential reset). The secret is never shown.

Manual equivalent. Entra admin center > App registrations > New registration: single tenant; redirect URI platform Web, https://mail.example.com/auth/callback/microsoft. API permissions: Microsoft Graph delegated openid, email, profile only. Certificates & secrets > New client secret; then pnpm exec wrangler pages secret put MICROSOFT_CLIENT_ID --project-name cmail-web --env="" and the same for MICROSOFT_CLIENT_SECRET, pasting at the prompt.

Then, either way: MICROSOFT_TENANT_ID = "<tenant id>" in apps/web/wrangler.toml [vars], and pnpm deploy:web (Pages secrets take effect on the next deployment).

Check. The sign-in page shows "Sign in with Microsoft". It does nothing useful until step 4: nobody has an account yet.

Undo. az ad app delete --id <app id>; pnpm exec wrangler pages secret delete MICROSOFT_CLIENT_SECRET --project-name cmail-web --env="" (and MICROSOFT_CLIENT_ID); redeploy.

Pitfalls.

Reference: Configuration: OAuth, Deployment step 4.

4. Bootstrap the first manager

Purpose. The first manager is the only account created without an invitation. Bootstrap is on only while two temporary secrets exist.

Script.

pwsh -File scripts/onboarding/set-bootstrap-secrets.ps1 -PagesProject cmail-web -AdminEmail admin@example.com
pnpm deploy:web
# open https://mail.example.com/bootstrap, paste the token (it is on your clipboard),
# sign in with Microsoft as admin@example.com
pwsh -File scripts/onboarding/set-bootstrap-secrets.ps1 -PagesProject cmail-web -Remove
pnpm deploy:web

The token is 32 random bytes, copied to the clipboard and not shown (-TokenOutput Console shows it once instead).

Manual equivalent. Deployment step 9.

Check.

pnpm exec wrangler d1 execute <db name> --remote --config apps/web/wrangler.toml --env="" --command "SELECT role, status, count(*) AS n FROM users GROUP BY role, status"

shows exactly one active manager. After -Remove and the redeploy, /bootstrap redirects away.

Undo. If bootstrap failed or the token may have leaked, run -Remove, redeploy, and start again with a new token.

Pitfalls.

5. Microsoft 365 sync

Purpose. cmail creates an account and mailbox for each licensed person on the mail domain, pauses leavers, and (optionally) finds shared mailboxes. It reads Microsoft 365 and never writes to it.

Script.

pwsh -File scripts/onboarding/new-sync-app.ps1 -TenantId <tenant id> -MailDomain example.com `
  -WranglerConfig apps/email-worker/wrangler.toml -DetectSharedMailboxes -WhatIf
# then without -WhatIf

It creates a separate app with Graph application permissions User.Read.All (plus MailboxSettings.Read with -DetectSharedMailboxes, GroupMember.Read.All with -GroupScoped), tries admin consent with az ad app permission admin-consent (reference), reads the grants back from the service principal's appRoleAssignments, grants any that are still missing directly (grant an appRoleAssignment), and pipes a new client secret into the Worker secret M365_CLIENT_SECRET.

Manual equivalent. Microsoft 365 sync: Entra app setup.

Then, either way, in apps/email-worker/wrangler.toml [vars]: M365_TENANT_ID, M365_CLIENT_ID, MAIL_DOMAIN, M365_DETECT_SHARED_MAILBOXES = "true" if wanted; keep the */15 * * * * cron; pnpm deploy:email-worker. Then Admin > Microsoft 365 sync: turn it on with dry run on, press Sync now, and read the report.

Check. The dry run counts match Microsoft 365 (people, shared mailboxes, conflicts). Fix conflicts at the source, then turn dry run off. The first live round runs on the next 15-minute tick and always reconciles after a dry run. Admin then shows result ok; Admin > People lists the synced people.

Undo. Turn the sync off (accounts stay as they are). To remove it: wrangler secret delete M365_CLIENT_SECRET --config apps/email-worker/wrangler.toml --env="", remove the vars, az ad app delete --id <app id>.

Pitfalls.

6. Staff sign-in

Purpose. Synced people sign in with Sign in with Microsoft on cmail's own page, with no invitation.

Run. Nothing extra: it works once steps 3 and 5 are done and the web app knows the tenant (MICROSOFT_TENANT_ID set to the tenant GUID, or M365_TENANT_ID on the web app). cmail binds the person by the ID token's oid and tid, never by email or UPN (how it works).

Check. A synced, non-manager test person signs in and lands in their mailbox. The audit log shows auth.sync_link_bound. A refused sign-in shows its reason on auth.sign_in_denied.

Undo. Turning the sync off stops new binds; existing binds keep working like any sign-in.

Pitfalls. Guests and managers never bind this way (managers come from bootstrap or invitations). If you put Cloudflare Access in front of the site, read staff sign-in first.

7. Passkeys

Purpose. A sign-in that keeps working when Microsoft or Cloudflare Access is down.

Run. Admin > Passkey sign-in > turn on. Each person signs in with Microsoft (a fresh sign-in), then Mail > Settings > Passkeys > add one, and bookmarks https://mail.example.com/auth/passkey.

Check. Sign out, open /auth/passkey, sign in with the passkey.

Undo. Turn passkey sign-in off: every passkey session ends; registered passkeys are kept.

Pitfalls. Passkeys are bound to the APP_URL host. Behind Cloudflare Access, /auth/passkey needs its own Bypass application. Details: Passkey break-glass sign-in.

8. Welcome emails (optional)

Purpose. Email each person the sync creates once, with first sign-in steps.

Run. Needs working outbound mail from MAIL_DOMAIN and step 6. Admin > Microsoft 365 sync > Welcome emails, with the sync in dry run first; send to one test account before anyone else. Full steps: Microsoft 365 welcome emails: runbook.

Check. The test account's Inbox in Exchange has the email; Exchange message trace shows it delivered.

Undo. Turn the switch off: unsent emails are cancelled.

9. Standby subdomain (optional)

Purpose. Give cmail its own way to receive mail while the domain's MX stays with Exchange Online. Steps 10 and 12 build on it.

Run (dashboard). Email Service > Email Routing > the apex domain > Settings > Subdomains > add standby (giving standby.example.com) (Email Routing subdomains).

Do not:

Check.

dig +short MX example.com            # still only Exchange Online
dig +short MX standby.example.com    # Cloudflare (route*.mx.cloudflare.net)
dig +short TXT standby.example.com   # v=spf1 ... include:_spf.mx.cloudflare.net ...

On Windows without dig:

Resolve-DnsName example.com -Type MX
Resolve-DnsName standby.example.com -Type MX
Resolve-DnsName standby.example.com -Type TXT

Expected: the apex MX and SPF are untouched; the subdomain has Cloudflare MX and SPF; Cloudflare also publishes its own DKIM selector record at the apex (harmless). Email Routing shows "Enabled" with "DNS records misconfigured" for the apex: that is expected while the apex MX stays with Exchange.

Undo. Remove the subdomain under Email Routing > Settings > Subdomains; check the apex records are unchanged.

Pitfalls.

10. Exchange mirror (optional)

Purpose. cmail keeps a live copy of the tenant's mail from one Exchange journal rule, so a standby has recent mail. Read Exchange mirror first, including how a report is trusted and the privacy section.

Script (three runs, each after the step before is checked). It needs an active Exchange Administrator (or Global Administrator) role; after connecting it checks the journaling cmdlets are available and stops before any change if not. Every Exchange call stops on error.

$m = @{ StandbySubdomain = 'standby.example.com'; JournalAddressFile = '<private folder>/journal-address.txt' }
# a. New journal address -> Worker secret M365_JOURNAL_ADDRESS, then the file (only once the secret is stored)
pwsh -File scripts/onboarding/exchange-mirror.ps1 @m -NewJournalAddress -WranglerConfig apps/email-worker/wrangler.toml
# b. Exchange: NDR address (previous value saved), TNEF-off remote domain, journal rule DISABLED
pwsh -File scripts/onboarding/exchange-mirror.ps1 @m -NdrAddress journal-ndr@standby.example.com -WhatIf
pwsh -File scripts/onboarding/exchange-mirror.ps1 @m -NdrAddress journal-ndr@standby.example.com
# c. After the mirror is on in Admin: enable the rule
pwsh -File scripts/onboarding/exchange-mirror.ps1 @m -Enable

Between a and b:

  1. Worker [vars]: M365_TENANT_ID, M365_JOURNAL_NDR_DOMAIN = "standby.example.com", INBOUND_AUTHSERV_ID = "mx.cloudflare.net" and the rest of Exchange mirror setup; migration 0027; deploy the Worker, then the web app.
  2. Email Routing on standby.example.com: one rule for the literal journal address (from the file) -> Send to a Worker -> the cmail email Worker. A second rule for the NDR address to a mailbox a person reads (a cmail mailbox through its standby address, or "Send to an email" to a verified address outside Exchange Online).
  3. Add include:spf.protection.outlook.com to the SPF TXT record of standby.example.com, keeping the Cloudflare include.

Between b and c: Admin > Exchange mirror > Turn on.

Manual equivalent. Exchange mirror: Exchange Online (Set-TransportConfig -JournalingReportNdrTo, New-RemoteDomain + Set-RemoteDomain -TNEFEnabled $false, New-JournalRule -Scope Global -Enabled $false, then Enable-JournalRule). Save (Get-TransportConfig).JournalingReportNdrTo before changing it.

Check. Send a message between two licensed users. Within a minute Admin > Exchange mirror shows a last report time, the message "filed", and no refused reports. If reports are refused, read the reason and the safe diagnostic in the audit log (diagnosing).

Undo. exchange-mirror.ps1 @m -Rollback: disables and removes the rule, removes the remote domain and restores the saved NDR address. Then Admin > Exchange mirror > Turn off; optionally delete the routing rule and M365_JOURNAL_ADDRESS. Mirrored mail stays until a manager removes it.

Pitfalls (all seen live).

11. Shared mailbox permissions (optional)

Purpose. Copy who has Full Access and Send As on shared mailboxes from Exchange into cmail daily. Graph cannot read these permissions, and the Exchange Online Admin API (preview) does not cover them, so cmail runs the Exchange PowerShell module in a Cloudflare Container, read-only. Read Shared mailbox access from Exchange Online first.

Script.

pwsh -File scripts/onboarding/perms-setup.ps1 -TenantId <tenant id> -Organization <name>.onmicrosoft.com `
  -WranglerConfig apps/email-worker/wrangler.toml -WhatIf
# then without -WhatIf, on Windows, as an admin who can consent and manage Exchange roles

After the role pre-flight it creates a third app with the Office 365 Exchange Online application permission Exchange.ManageAsApp (admin consent, checked, with the direct grant as fallback); a self-signed certificate with a CSP key, the public part on the app (a rerun reuses a valid certificate that is already on the app instead of adding another); a custom role from "Mail Recipients" trimmed to six read cmdlets (Get-Mailbox, Get-MailboxPermission, Get-RecipientPermission, Get-Recipient, Get-User, Get-Group) in its own role group; the app's Exchange service principal in that group. Then, as the app, the go/no-go: no write cmdlet (Add-/Remove-MailboxPermission, Add-/Remove-RecipientPermission, Set-Mailbox) may be available to the app's session (nothing is attempted), and a shared mailbox's grants must be readable; any unexpected error is a no-go. Only on GO does it pipe the PFX (base64) and its random password into the Worker secrets M365_EXO_CERT_PFX_B64 and M365_EXO_CERT_PASSWORD, and delete the PFX file (app-only auth for Exchange Online PowerShell).

Manual equivalent. Setup steps 1 to 5.

Then: [vars] M365_EXO_APP_ID and M365_EXO_ORGANIZATION; uncomment the container block from wrangler.toml.example; migration 0028; with Docker running, deploy the Worker, then the web app; Admin > Shared mailbox access > Turn on (dry run stays on).

Check. Two cron runs later the report matches Exchange for a shared mailbox where you know who has Full Access. Run the collector check in step 4 of the feature doc before turning dry run off.

Undo. Admin > Turn off. perms-setup.ps1 ... -Rollback removes the role group, role, Exchange service principal, Entra app and the local certificate. Comment the container block out and redeploy to remove the container. Grants already written stay (see the feature doc's rollback).

Pitfalls.

12. Standby test, switch and copy-back (optional)

These are drills, each with its own runbook. Do them in a planned window, after steps 9 and 10.

Lessons from the first onboarding

Beyond the pitfalls above, these cost time and are worth knowing: