t1k:web:devops:cloudflare-access
| Field | Value |
|---|---|
| Module | devops |
| Version | 1.31.4 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/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)The three rules
Section titled “The three rules”- 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 itsidcreates 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. - 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;bypassadmits everyone and gates nothing. - One app per Worker, but several Workers per app. A
worker_idbelongs to exactly ONE app: a second app on it is409 [12132]. One app may list severalworkerdestinations, 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.
Create — read first, then create once
Section titled “Create — read first, then create once”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.
cf zero-trust access applications list # apps and the policies attached to eachcf zero-trust access policies list # reusable policies and their app_countcf zero-trust access service-tokens list # tokens, their names and expiryReuse, 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}.
# 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 IDcf 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.
Rotate, audit, retire
Section titled “Rotate, audit, retire”| Task | Command |
|---|---|
| Rotate the secret | cf 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 backs | cf zero-trust access policies list, match include[].service_token.token_id |
| Find app-local policies | cf zero-trust access applications list | jq -r '.[]|.name as $a|(.policies//[])[]|select((.reusable//false)==false)|"\($a): \(.name)"' |
| Find orphans | cf zero-trust access policies list | jq -r '.[]|select((.app_count//0)==0)|"\(.name) \(.id)"' |
| Retire an app | delete the app, then its policy (deleting the app leaves the policy behind), then the token |
| Rename a policy | cf zero-trust access policies update <id> --name <new> --decision … --include … — never through the app body |
Hard rules
Section titled “Hard rules”--decisionand--includeare required onpolicies update; omitting--decisionprints--decision is requiredand exits non-zero.refreshdoes 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→workercannot 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_headersis 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
Section titled “References”- references/access-objects.md — request/response shapes, measured facts
/t1k:web:devops:cloudflare-internal-netbird— the repeatable-internalvariant built on this/t1k:cloudflare—cfitself, deploy flags, config shape