Cloudflare Access — step-by-step setup
Follow these steps in order. You only need Phase 1 until dashboard.lovely-home.co.uk DNS is on Cloudflare.
Estimated time: 45–60 minutes the first time.
Before you start
You need:
- Cloudflare account with Zero Trust enabled (free tier is fine).
- Admin access to Workers & Pages for the Home Hub project and
lovely-home-hub-apiWorker. - Terminal on your Mac with the repo cloned (
worker/folder). - A list of owner emails (you, Donna, …) and each house-sitter email (exact addresses).
Merge and deploy PR #20 (security lockdown) before turning this on in production, or the Worker will reject API calls without Access secrets configured.
Which “Add application” screen to use (important)
Cloudflare shows Add an application with tabs. Lovely Home is not a private internal app.
| What you are protecting | Top tab | Sub-tab (pill buttons) | Do not use |
|---|---|---|---|
Pages dashboard (*.pages.dev) | Self-hosted and private | Public DNS | Private destinations |
Worker API (lovely-home-hub-api.*.workers.dev) | Self-hosted and private | Workers (pick your Worker) or Public DNS (enter the workers.dev hostname) | Private destinations |
Private destinations is for things like 10.0.0.5 or myapp.internal behind a tunnel — that is why the diagram shows IP addresses. Your dashboard is on the public internet (pages.dev), so that sub-tab is the wrong one.
You will create two Access applications (Pages first, then Worker). Repeat Add an application twice.
Step 1 — Write down your hostnames
- Open Cloudflare Dashboard → Workers & Pages.
- Click the Pages project (likely named home-dashboard or similar).
- Note the production URL, e.g.
https://home-dashboard-a11.pages.dev→ this is your Pages hostname (nohttps://in Access forms — hostname only). - Still on Pages → Deployments → open a preview if you use PR previews → note the preview hostname pattern.
- Click Workers & Pages → open lovely-home-hub-api (Worker).
- Under Triggers or the overview, note the workers.dev URL, e.g.
https://lovely-home-hub-api.mark-lovely67.workers.dev
→ hostname only:lovely-home-hub-api.mark-lovely67.workers.dev— this is your Worker hostname.
Keep these three hostnames on a sticky note:
| Label | Hostname (example) | Yours |
|---|---|---|
| Pages | home-dashboard-a11.pages.dev | |
| Worker | lovely-home-hub-api.mark-lovely67.workers.dev | |
| Custom (later) | dashboard.lovely-home.co.uk | skip for now |
Step 2 — Find your Zero Trust team name
- In Cloudflare, open Zero Trust (left menu, or go to one.dash.cloudflare.com).
- Go to Settings → Custom pages (or Team name / Organization depending on UI).
- Note the team name used in login URLs:
https://{TEAM_NAME}.cloudflareaccess.com
Example: team namemark-lovely67→ you will set Worker secretCF_ACCESS_TEAM_DOMAINtomark-lovely67(the subdomain only, nohttps://).
Step 3 — Create Access app for the dashboard (Pages)
- Zero Trust → Access → Applications.
- Click Add an application.
- Top tab: Self-hosted and private (already selected).
- Sub-tab: click Public DNS (not Private destinations).
- Click Continue (or Continue with Self-hosted and private).
- On the next screens, fill in:
- Application name:
Lovely Home — Pages production - Session Duration: 30 days for the wall tablet (Fully Kiosk). Shorter durations (e.g. 24–48 hours) force Cloudflare sign-in even while House Sitter Mode is still active on the device cookie — confusing on a kiosk. Use the same duration on both Pages and Worker Access apps.
- Public hostname / domain: your full Pages host, e.g.
home-dashboard-a11.pages.dev
(Some UIs split “subdomain” + “domain”; forhome-dashboard-a11.pages.devyou may enter subdomainhome-dashboard-a11and domainpages.dev, or one field with the full hostname.) - Path: leave empty (protect entire site)
- Application name:
- Continue to Policies (Step 3a below).
If you do not see Public DNS, try Continue from the first screen and look for a Public hostname or Domain field on the next page — enter home-dashboard-a11.pages.dev.
Step 3a — Owner policy
- Click Add a policy.
- Policy name:
Owners - Action: Allow
- Configure rules → Include → choose Emails → enter each owner email (one per line or comma-separated, e.g.
mark@…,donna@…). - Authentication method: leave default or choose One-time PIN, Google, etc. for owners.
- Save policy.
Step 3b — House-sitter policy
- Add a policy again.
- Policy name:
House sitters - Action: Allow
- Include → Emails → add only approved sitter addresses (each sitter’s real email).
- Authentication method: One-time PIN is OK here because the email is explicitly listed.
- Save policy.
Do not add a rule Include: Everyone.
- Finish creating the application (Save application).
Test: open https://home-dashboard-a11.pages.dev in a private window → you should see Cloudflare Access login, not the dashboard.
Step 4 — Create Access app for the Worker API (required)
The browser calls the Worker directly for weather, controls, Wi‑Fi, calendar, etc. Without this app, the dashboard will load but API calls fail with 401.
- Access → Applications → Add an application again.
- Top tab: Self-hosted and private.
- Sub-tab: choose Workers.
- Continue → select
lovely-home-hub-apifrom the list (your API Worker). - Application name:
Lovely Home — Worker API - Policies: add the same two Allow policies as Step 3 (Owners + House sitters with the same email lists).
Alternative if Workers tab does not list your script: use sub-tab Public DNS and enter hostname lovely-home-hub-api.{your-subdomain}.workers.dev (from Step 1).
- Save application.
Step 4a — Copy the Application Audience (AUD)
- Open the Worker API application you just created.
- On Overview (or Quick actions), find Application Audience (AUD) — a long hex string.
- Copy it somewhere safe → you will paste it into
CF_ACCESS_AUDin Step 6.
Step 5 — (Optional) Protect Pages preview URLs
If GitHub PRs deploy to https://{hash}.home-dashboard-a11.pages.dev:
Terraform-managed sites: terraform apply adds home-dashboard-a11.pages.dev and *.home-dashboard-a11.pages.dev to the same Pages Access app as your custom domain (see platform-terraform.md). Remove any older manual Access app that only listed home-dashboard-a11.pages.dev to avoid duplicates.
Manual setup (legacy):
- Add an application → Self-hosted.
- Domain: try
*.home-dashboard-a11.pages.devif Cloudflare accepts wildcards; otherwise add one app per preview hostname you care about, or restrict previews to owners only in a separate policy. - Use at least the Owners policy; sitters on preview is usually unnecessary.
Skip this step if you do not use public preview URLs.
Step 6 — Set Worker secrets (terminal)
On your Mac:
cd /path/to/home-dashboard/worker
npx wrangler loginThen set each secret (Wrangler prompts for the value; paste carefully):
npx wrangler secret put CF_ACCESS_TEAM_DOMAIN
# Enter: your team name from Step 2 (e.g. mark-lovely67)
npx wrangler secret put CF_ACCESS_AUD
# Enter: the AUD string from Step 4a (Worker API app only)
npx wrangler secret put OWNER_EMAILS
# Enter: comma-separated owner emails only, e.g. mark@example.com,donna@example.com
# Must match emails in your Owners Access policy. Sitters are NOT listed here.Confirm existing secrets are still present (re-run only if missing):
npx wrangler secret put VIRTUAL_BUTTONS_ACCESS_CODE
npx wrangler secret put OWNER_PIN
# … plus PRIVATE_* and APPLE_CALENDAR_ICS_URL if you use My DayOptional:
npx wrangler secret put OWNER_SESSION_SECRET
# Use a long random string (not the same as OWNER_PIN)Step 7 — Deploy the Worker
cd worker
npm install
npm run deploy- Approve any Durable Object migration prompt (
ControlActionLimiter/ v2). - Confirm the deploy URL matches what you use for
VITE_API_BASE_URL.
Quick check:
curl -s "https://YOUR-WORKER-HOSTNAME.workers.dev/api/health"Should return JSON with "status":"ok".
Protected route without login:
curl -s -o /dev/null -w "%{http_code}\n" \
"https://YOUR-WORKER-HOSTNAME.workers.dev/api/session"Should print 401 (good).
Step 8 — Pages environment variables
Production API traffic uses same-origin /api/* (Pages Function). See cloudflare-pages-configuration.md for the full checklist (WORKER_API_ORIGIN, HUB_API binding, dual CF_ACCESS_AUD).
Minimum plaintext vars on Pages project home-dashboard (Production and Preview):
| Variable | Value |
|---|---|
WORKER_API_ORIGIN | https://lovely-home-hub-api.mark-lovely67.workers.dev |
VITE_DEPLOYMENT_MODE | home or house-sitter |
Add Settings → Bindings → Service binding HUB_API → lovely-home-hub-api, then redeploy.
Do not add a wrangler.toml at the repo root for Pages.
Step 9 — Test in the browser
- Private/incognito window →
https://home-dashboard-a11.pages.dev. - Complete Access login as an owner email.
- Dashboard should load; weather should update (proves Worker + JWT works).
- Open DevTools → Network → click a request to your Worker → confirm request headers include
Cf-Access-Jwt-Assertion(often added by Cloudflare on the Worker hostname when both are protected). - Log out / use another browser profile → log in as a sitter email → guest apps work; My Day and other owner tools stay hidden unless enabled for sitters in Settings → People.
- As owner, use in-app PIN to switch to owner device mode → My Day loads when the calendar feed is configured (owners may need PIN once per session on a locked tablet).
If something fails
| What you see | Fix |
|---|---|
| Access login never appears on Pages | Re-check Step 3 application domain matches exact Pages hostname |
| Dashboard loads, weather “unavailable”, API 401 | Complete Step 4 (Worker Access app); same email policies |
| API 503 | Step 6 secrets missing or Worker not redeployed after secrets |
| CORS error in console | Worker ALLOWED_ORIGINS must include your Pages origin; redeploy Worker from latest wrangler.toml |
| Calendar 403 for you | Your login email must be in OWNER_EMAILS, not just Access Owners policy |
Step 10 — When dashboard.lovely-home.co.uk is ready (Phase 2)
- DNS: Finish transfer; domain uses Cloudflare nameservers; proxied (orange cloud).
- Pages: Project → Custom domains → Set up a custom domain → enter
dashboard.lovely-home.co.uk→ wait for Active certificate. - Access: Add application (Self-hosted) for
dashboard.lovely-home.co.uk— duplicate the same Owner + Sitter policies from Step 3. - Update the household device bookmark to
https://dashboard.lovely-home.co.uk. - Smoke-test again (weather, controls, sitter vs owner).
Worker CORS already lists https://dashboard.lovely-home.co.uk in worker/wrangler.toml; redeploy Worker after merging if you changed vars.
Adding or removing a house sitter
- Zero Trust → Access → Applications.
- Edit each of: Pages app, Worker API app, (previews/custom if used).
- House sitters policy → add or remove the email → Save.
- No Worker redeploy needed for sitter list changes (Access only).
- To promote someone to owner: add email to Owners policy and add to Worker secret
OWNER_EMAILS, then redeploy is not required forOWNER_EMAILSif you update viawrangler secret put OWNER_EMAILS(secret update is live immediately).
Quick reference — where things live
| What | Where in Cloudflare |
|---|---|
| Who can open the website | Zero Trust → Access → Applications → Policies |
| Who is “owner” for calendar/API | Worker secret OWNER_EMAILS |
| Worker validates JWT | Secrets CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD |
| API URL in the app | Pages → Settings → Environment variables → VITE_API_BASE_URL |
| CORS allowed origins | worker/wrangler.toml → ALLOWED_ORIGINS |
More detail: cloudflare-access-runbook.md · cloudflare-access.md