Cloudflare Access for Internal Sites

Identity-backed perimeter authorization in front of a Worker -- account-level setup, Worker-scoped applications that cover workers.dev and previews without a zone, the WebSocket limitation, and reading the caller's identity from the Worker

Overview -- Access Is an Allowlist, Not a Signup System

Cloudflare Access puts an identity check in front of a site before any request reaches the origin. A visitor hits the URL, gets redirected to an identity provider, proves who they are, and comes back with a signed session -- all of it enforced at Cloudflare's edge, none of it code you write.

The word that decides where Access fits is allowlist. You enumerate who may enter -- specific email addresses, an email domain, an identity-provider group -- and an administrator edits a policy to admit anyone new. There is no self-service registration, by design.

Three Tools, Three Audiences

Access does not supersede the password gate. They answer different questions about who the viewer is and what it costs to enroll them, and the cheapest correct tool is usually not the strongest one.

That first row is the whole distinction. Access needs an identity it can enroll and allowlist before the person shows up. A client reviewing a staging build, a contractor on a two-week engagement, an outside reviewer you cannot add to the corporate directory -- for those, "send the URL and the password" stays the right answer, and a password gate remains the tool. One-time PIN narrows the gap (see below) but does not close it: you still have to know their address ahead of time.

The three compose. A mature setup runs app-level auth for end users, Access over /admin and every preview deployment, and a password gate on the one staging URL that goes out to a client.

Setup Is Account-Level, Not Token-Level

Nothing about an API token decides whether Access is available. Access lives inside Zero Trust, which is turned on per Cloudflare account, and the dashboard is a complete interface to it -- a token is only needed if you intend to manage Access from code.

Three one-time decisions before any policy exists:

1. A Zero Trust organization. The first visit to the Zero Trust dashboard asks for a team name, which becomes the team domain <team>.cloudflareaccess.com. That hostname is where every login lands and is the iss claim in the resulting JWT. Renaming it later is disruptive -- choose deliberately.

2. A plan. Check Cloudflare's Zero Trust plan page for the current Free-tier limits. Do not trust a remembered figure -- the widely-repeated "50 users" cap comes from a 2022 document and is not what the current plan page says, and Cloudflare's own account-limits page tiers several other features by plan without stating a user cap at all.

3. A login method. Either a real identity provider (Google Workspace, Microsoft Entra, Okta) or One-time PIN, which needs no IdP configuration at all: the visitor enters an email address, selects Send login code, and pastes back the PIN that arrives by email. It expires ten minutes after the request.

Attaching Access to a Worker Instead of a Hostname

The traditional Access application is bound to a hostname, which historically raised an awkward question for Workers served on *.workers.dev: that is not a zone you own. Access applications can now target the Worker itself, which sidesteps the question entirely.

Cloudflare's Workers documentation states that a Worker-scoped application protects every domain associated with that Worker -- its routes, Custom Domains, workers.dev hostname, and previews. No zone, no custom domain, and no DNS record required.

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/apps" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "type": "self_hosted",
    "name": "Access for my-worker",
    "destinations": [{ "type": "worker", "worker_id": "c81a2d22c29840ed9d61681a3270dbff" }],
    "policies": [{
      "decision": "allow",
      "include": [{ "email_domain": { "domain": "example.com" } }]
    }]
  }'

Two constraints the API schema states and the prose does not: at most one all_workers and one all_preview_workers destination may exist per account, and the destinations list also accepts non-Worker variants (public for a hostname or URI, private for a CIDR/port, via_mcp_server_portal). public is the old hostname-shaped destination -- it is not a Worker-scoped one, and mistaking it for the equivalent of worker is an easy way to build an application that covers nothing you expected.

Precedence, and Why Deleting a Policy May Change Nothing

The most specific rule wins: hostname- or path-based Access first, then Worker-level, then account-level all_workers as the fallback. The consequence worth internalizing -- and which Cloudflare states directly, that removing Worker-level Access can reveal account-level Access underneath -- is that on an account running all_workers, deleting a Worker's own policy does not make that Worker public. It falls through to the account-wide rule.

Exempting one Worker takes an explicit bypass, not a deletion:

{
  "decision": "bypass",
  "include": [{ "everyone": {} }]
}

applied to a worker destination for the Worker in question.

What the Visitor Actually Sees

With an identity provider already configured -- the normal case in a company that uses Zero Trust for anything else -- most people type nothing at all:

Two details that matter in practice:

• The original deep link survives. A visitor who clicks a link to /items/123 lands back on /items/123, not on the site root. Shared links keep working.

• Denied users get Cloudflare's block page, not your 404. A colleague who is not on the policy sees a generic refusal with no idea who to ask. The block page is customizable -- put a name or a channel on it, or the first support request will be someone asking why the link is broken.

With One-time PIN in place of an IdP, the visitor types twice: their email address, then the six-digit code that arrives by email. Only addresses matching a policy get a code that works.

How often anyone re-authenticates is configurable, at three levels that are easy to conflate. Application session duration (Applications > Configure > Overview) ranges from immediate timeout to one month and defaults to 24 hours. A policy may override it for the people that policy matches, over the same range. Global session duration is separate again -- it governs IdP re-login account-wide, runs from 15 minutes to one month, and also defaults to 24 hours. A Cloudflare One Client session, where one exists, overrides all of them.

Reading the Identity in the Worker

Once a request is through, the Worker can read who sent it -- no JWT parsing, no library:

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // ctx.access is undefined when Access did not authenticate the request
    // -- e.g. the Worker is reachable on a route the application does not
    // cover. Treat that as a failure, not as an anonymous visitor.
    if (!ctx.access) {
      return new Response("Access required", { status: 403 });
    }

    const identity = await ctx.access.getIdentity();
    return new Response(`Signed in as ${identity?.email ?? "unknown"}`);
  },
};

The application's audience tag is on the same object, as ctx.access.aud.

This is the capability a shared password fundamentally cannot offer: per-visitor attribution. Recording who triaged an item, or showing the signed-in user, becomes possible without writing an auth system.

For hostname-based applications, or anywhere explicit verification is wanted, validate the Cf-Access-Jwt-Assertion header against the team's JWKS endpoint instead. Fetch the keys; never hardcode one:

import { createRemoteJWKSet, jwtVerify } from "jose";

// Module-level cache so one isolate reuses a single JWKS fetcher across
// requests. It cannot be built at module scope directly: `env` only exists
// inside the handler, so the URL is not known until the first request.
const jwksCache = new Map<string, ReturnType<typeof createRemoteJWKSet>>();

function getJwks(teamDomain: string) {
  let jwks = jwksCache.get(teamDomain);
  if (!jwks) {
    jwks = createRemoteJWKSet(new URL(`${teamDomain}/cdn-cgi/access/certs`));
    jwksCache.set(teamDomain, jwks);
  }
  return jwks;
}

export async function verifyAccessJwt(request: Request, env: Env) {
  const token = request.headers.get("Cf-Access-Jwt-Assertion");
  if (!token) throw new Error("Missing Cf-Access-Jwt-Assertion header");

  return await jwtVerify(token, getJwks(env.TEAM_DOMAIN), {
    issuer: env.TEAM_DOMAIN,
    audience: env.POLICY_AUD, // the application's AUD tag
  });
}

TEAM_DOMAIN here is the full origin -- https://my-team.cloudflareaccess.com, scheme included and no trailing slash. It is used twice for two different reasons: new URL() rejects a bare hostname outright, and the iss claim Access signs is the origin form, so a value that omits the scheme fails the issuer check even where the URL happens to build.

The same RS256-plus-JWKS shape appears in Auth with Pages Functions -- Access is one more third-party issuer, verified the same way.

Simulating an Identity in Local Dev

wrangler dev has no Access in front of it, so ctx.access would be undefined for every local request and the guard above would reject everything. An access.dev block supplies a fake identity instead:

{
  "access": {
    "dev": {
      "aud": "my-app", // required -- Wrangler will not start without it
      "identity": { "email": "admin@example.com" } // optional
    }
  }
}

Remove the block and ctx.access goes back to undefined, which is the way to test the unauthenticated branch.

API Token Permissions Are Separate from the Deploy Token

Deploying a Worker that sits behind Access needs no Access permission on the deploy token. Access applications are created through /accounts/{account_id}/access/apps, an API surface the Worker upload never touches, and the deploy token Cloudflare's own dashboard generates contains no Access: permission at all. Enabling Access does not break an existing deploy pipeline, and the deploy token should stay as narrow as it already is (see Cloudflare Account Setup).

Managing Access from code -- Terraform, or direct API calls -- is what needs permissions. Create a separate token for it. All of them are Account-scoped:

Related

• Password Gate for Preview and Staging Sites -- the shared-secret alternative, and still the right tool for outside viewers who cannot be allowlisted in advance.

• Access Service Tokens for CI -- how Playwright smoke tests and health checks get through an Access-protected URL without a login redirect.

• Auth with Pages Functions -- verifying a third-party IdP token, and the path to take when the app has public signup.

• HTTP-only Cookie Sessions -- the per-user session layer Access deliberately does not provide.

• Workers PR Previews -- the preview-alias URLs a worker destination is meant to cover.

• Cloudflare Account Setup -- the deploy token, which needs none of the permissions on this page.