Skip to content

t1k:web:devops:cloudflare-access

FieldValue
Moduledevops
Version1.31.4
Effortmedium
Tools—

Keywords: access app, access applications, access audit, access policies, access policy, bypass everyone, cf zero-trust access, cf-access-client-id, cf-access-client-secret, cloudflare access, non_identity, reusable policy, service auth, service token

/t1k:web:devops:cloudflare-access
[app|policy|token|audit|retire] <name>

Cloudflare Access: apps, reusable policies, service tokens

Section titled “Cloudflare Access: apps, reusable policies, service tokens”

Access is configured through three objects, and getting their relationship wrong is silent — the gate keeps working while the account accumulates dead policies, or the app gates nothing at all.

service token ──include[].service_token──> reusable policy ──policies:[{id}]──> app
(secret shown once) (account object) (worker or hostname)
  1. Create the policy as a REUSABLE account policy and attach it by {id}. An inline policy object in an app body (policies: [{name, decision, include}]) makes an app-local policy (reusable: false). Re-sending it without its id creates a NEW policy and silently DETACHES the old one, which survives as an orphan (app_count: 0) still carrying its old name. That is the “legacy policy” an audit keeps finding.
  2. A service-token gate needs decision: "non_identity" — the API name for the dashboard’s Service Auth. Any other decision sends machine callers to an IdP login; bypass admits everyone and gates nothing.
  3. One app per Worker, but several Workers per app. A worker_id belongs to exactly ONE app: a second app on it is 409 [12132]. One app may list several worker destinations, and each gates that Worker’s traffic however it arrives — custom domains and zone routes it serves on another Worker’s hostname (measured). Prefer adding a destination over creating a second app.

Before creating anything, look at what is already there. An app, a policy or a token with your name may exist, and a policy may already admit the token you are about to mint.

Terminal window
cf zero-trust access applications list # apps and the policies attached to each
cf zero-trust access policies list # reusable policies and their app_count
cf zero-trust access service-tokens list # tokens, their names and expiry

Reuse, in this order — same name, then any policy whose include[].service_token.token_id already carries this token (a renamed or hand-made policy is not a reason to grow a duplicate) — and create only when neither hits. Then attach by {id}.

Terminal window
# 1. token — the secret is shown ONCE, on create (and on a version bump)
TOKEN=$(cf zero-trust access service-tokens create --name <name> --duration forever)
TID=$(jq -r .id <<<"$TOKEN")
# 2. reusable policy (account-level, NOT app-local)
PID=$(cf zero-trust access policies create --name <name> --decision non_identity \
--include "[{\"service_token\":{\"token_id\":\"$TID\"}}]" | jq -r .id)
# 3. app, policy attached BY ID
cf zero-trust access applications create --body "$(jq -nc --arg pid "$PID" --arg w <worker-id> '{
name: "<name>", type: "self_hosted",
destinations: [{ type: "worker", worker_id: $w }],
session_duration: "0s", allowed_idps: [],
policies: [{ id: $pid }] }')"

For a hostname destination use { "type": "public", "uri": "<host>" }; the API derives self_hosted_domains from it, so do not also send domain.

For the one workflow that must be repeatable — a Worker on <name>-internal plus its service token, Access app and NetBird service — run scripts/internal-netbird.sh from /t1k:web:devops:cloudflare-internal-netbird instead of retyping this.

TaskCommand
Rotate the secretcf zero-trust access service-tokens update <id> --name <n> --client-secret-version <v+1> --previous-client-secret-expires-at <ISO8601> — all three are required; without --name the token’s name is erased (measured)
See what a token backscf zero-trust access policies list, match include[].service_token.token_id
Find app-local policiescf zero-trust access applications list | jq -r '.[]|.name as $a|(.policies//[])[]|select((.reusable//false)==false)|"\($a): \(.name)"'
Find orphanscf zero-trust access policies list | jq -r '.[]|select((.app_count//0)==0)|"\(.name) \(.id)"'
Retire an appdelete the app, then its policy (deleting the app leaves the policy behind), then the token
Rename a policycf zero-trust access policies update <id> --name <new> --decision … --include … — never through the app body
  • --decision and --include are required on policies update; omitting --decision prints --decision is required and exits non-zero.
  • refresh does not rotate a service token — it re-reads the record and returns no secret.
  • A non-interactive delete needs --force, otherwise the CLI prints “Aborted” and exits 1.
  • public → worker cannot be flipped in place on a claimed hostname (12132); create the app with the right destination from the start.
  • The account caps service tokens at 50, and a client secret is readable by whoever holds the consumer’s config (a NetBird service’s custom_headers is visible to any user PAT).
  • Matching a policy by name alone creates duplicates — a renamed policy that already admits the same token is invisible to a name lookup.

More, with exact bodies and the measurements behind each claim: references/access-objects.md. Symptom-level entries: ledger/gotchas/t1k-web-devops-cloudflare-access.md.

  • references/access-objects.md — request/response shapes, measured facts
  • /t1k:web:devops:cloudflare-internal-netbird — the repeatable -internal variant built on this
  • /t1k:cloudflare — cf itself, deploy flags, config shape