Skip to content

access-setup.md

Latest commit

 

History

History
162 lines (119 loc) · 4.97 KB

access-setup.md

File metadata and controls

162 lines (119 loc) · 4.97 KB
Raw

Cloudflare Access Setup for serverless-memex

Follow these steps to replace the bearer-token auth with Cloudflare Access service tokens.

Prerequisites

  • Access to the Cloudflare dashboard at https://dash.cloudflare.com
  • Your account must be on a plan that includes Cloudflare Access (Zero Trust). The free tier includes Access for up to 50 users/service tokens — this should cover personal use.

Step 1 — Enable Zero Trust

  1. In the Cloudflare dashboard, click Zero Trust in the left sidebar (or navigate to https://one.dash.cloudflare.com).
  2. If prompted, complete the Zero Trust onboarding (choose a team name, e.g. mattjacobs). This becomes your team domain: mattjacobs.cloudflareaccess.com. Write it down — you will need it in Step 4.

Step 2 — Create the Access Application

  1. In Zero Trust, go to Access → Applications.
  2. Click Add an application.
  3. Choose Self-hosted.
  4. Fill in the form:
    • Application name: serverless-memex
    • Session Duration: 24 hours (or whatever you prefer; service tokens ignore session duration but it is required)
    • Application domain: serverless-memex.mattjacobs.workers.dev
      • Subdomain: serverless-memex
      • Domain: mattjacobs.workers.dev
      • Path: (leave blank to cover all paths)
  5. Click Next.

Step 3 — Add a Service Token Policy

  1. On the Policies step, click Add a policy.
  2. Fill in:
    • Policy name: service-token-access
    • Action: Service Auth (this is the option specifically for machine-to-machine service tokens — it does NOT prompt for a login page)
    • Under Configure rules, set:
      • Include → rule type: Service Token → select the token you will create in Step 4 (you may need to create it first and come back, or proceed and edit the policy afterward)
  3. Click Save policy, then Next, then Add application.

If the UI requires selecting a token at policy creation time, complete Step 4 first, then come back and add the policy.

Step 4 — Mint a Service Token

  1. In Zero Trust, go to Access → Service Auth → Service Tokens.

  2. Click Create Service Token.

  3. Fill in:

    • Service Token name: memex-cli
    • Service Token Duration: Non-expiring (or set a rotation schedule if preferred)

  4. Click Generate token.

  5. IMPORTANT: Copy both values immediately — the Secret is only shown once:

    • Client ID: looks like xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.access
    • Client Secret: a long random string

  6. Save them in ~/.secrets:

    MEMEX_CLIENT_ID=<paste Client ID here>
MEMEX_CLIENT_SECRET=<paste Client Secret here>

  7. Go back to the policy created in Step 3 and confirm the memex-cli token is selected in the Service Token rule. Save if needed.

Step 5 — Set the Team Domain in the Worker

The Worker must know your CF Access team domain to verify JWTs. Add it as a Wrangler variable:

cd ~/dev/projects/serverless-memex
set -a && source .secrets && set +a
pnpm exec wrangler secret put CF_TEAM_DOMAIN

When prompted, enter your team domain without the https:// prefix, e.g.:

mattjacobs.cloudflareaccess.com

Step 6 — Deploy the Updated Worker

cd ~/dev/projects/serverless-memex
set -a && source .secrets && set +a
pnpm exec wrangler deploy

Step 7 — Verify

Test that unauthenticated requests are rejected:

curl -sS -o /dev/null -w "%{http_code}" https://serverless-memex.mattjacobs.workers.dev/search \
  -X POST -H "Content-Type: application/json" -d '{"query":"test"}'
# Expected: 401

Test that authenticated requests succeed:

source ~/.secrets
curl -sS -X POST https://serverless-memex.mattjacobs.workers.dev/search \
  -H "CF-Access-Client-Id: $MEMEX_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $MEMEX_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"query":"test"}' | jq .

Then test the shell functions:

echo "test capture" | memex-capture
memex-search "test"

Step 8 — Remove the Old Bearer Secret

Once Access is working, delete the now-unused AUTH_SECRET Wrangler secret:

cd ~/dev/projects/serverless-memex
set -a && source .secrets && set +a
pnpm exec wrangler secret delete AUTH_SECRET

Notes

  • The Worker verifies the Cf-Access-Jwt-Assertion JWT that Cloudflare Access injects. It fetches CF's JWKS from https://<team-domain>/cdn-cgi/access/certs and caches the public keys in memory for the lifetime of the isolate.
  • If you see 401 Unauthorized after setup, check that: (a) the service token is attached to a Service Auth policy (not a regular Allow policy), (b) CF_TEAM_DOMAIN is set correctly (no trailing slash, no https://), and (c) you sourced ~/.secrets so the shell functions have the new env vars.
  • The old MEMEX_TOKEN variable in ~/.secrets is no longer needed and can be removed once everything is verified working.