Skip to main content

access

@rtorcato/cf-common/access verifies the Cf-Access-Jwt-Assertion header that Cloudflare Access adds to requests behind Zero Trust. A Worker should check it instead of trusting the Cf-Access-Authenticated-User-Email header, which anyone who can reach the Worker directly (for example on workers.dev) can forge.

It uses Web Crypto only. No JWT library is involved.

Verify a request​

You need your Access team domain and the application's AUD tag (both in the Zero Trust dashboard, under the Access application).

import { accessJwt, verifyAccessJwt } from '@rtorcato/cf-common/access'
import { CloudflareError } from '@rtorcato/cf-common/errors'
import { requireEnv } from '@rtorcato/cf-common/env'

const token = accessJwt(request)
if (!token) throw new CloudflareError('Unauthorized', { status: 401 })

const identity = await verifyAccessJwt(token, {
teamDomain: requireEnv(env, 'ACCESS_TEAM_DOMAIN'), // myteam.cloudflareaccess.com
aud: requireEnv(env, 'ACCESS_AUD'),
})
identity.email // the signed-in user

accessJwt returns null when the header is missing. verifyAccessJwt returns the token's claims (email, sub, iss, aud, exp, …) with aud always as an array.

What is checked​

The RS256 signature against the team's published keys, then the issuer (https://<teamDomain>), the aud tag, exp and nbf. Any other signing algorithm, including none, is rejected.

Key caching​

The keys come from https://<teamDomain>/cdn-cgi/access/certs. They are cached in the isolate for an hour. If a token names a key that isn't cached (Cloudflare rotated them), the keys are refetched, at most once a minute so junk tokens can't hammer the endpoint.

When it fails​

A token that fails any check throws a CloudflareError with status 401 and code ACCESS_JWT_INVALID. If the certs endpoint can't be reached, it throws a non-exposed 502 with code ACCESS_JWKS_HTTP_ERROR. Under defineFetch these map to a 401 and a generic Internal error. See errors.

See the access API reference for the exported types.